Repository files navigation

Racker is an experimental harness tool for provisioning and launchingcontainers, with a focus onoperating system containers.

By a "harness tool", we mean a combination of image bakery and payloadlauncher.

• The image bakery is based on modern and generic tools for creating machineimages likemkosi andPacker, as wellOCI-compliant container images. Container images can be acquired from both vendor-specific and standardized distribution channels likeOCI-compliant imageregistries.
• A payload is any of an interactive command prompt (shell), a single programinvocation, or a long-running daemon.

• A lightweight wrapper aroundsystemd-nspawn to provide and launchcontainer environments for/withsystemd.
• A lightweight wrapper aroundvagrant to provide convenient access to allthings needing a full VM, like running Windows on Linux or macOS.
• A tribute to the authors and contributors of GNU, Linux, systemd, Python,VirtualBox, Vagrant, Docker, Windows, Windows Docker Machine and countlessothers.

• Launch interactive command prompts or invoke programs non-interactivelywithin a isolated and volatile Linux and Windows environments.
• Build upon the runtime harness framework to build solutions for running andtesting software packages in different environments, mostly run headless andnon-interactively.

Racker has two different subsystems / runner backends, one for Linux andanother one for Windows.

• For running Linux operating system containers, Racker usessystemd andsystemd-nspawn. Provisioning of additional software is performed using thenative package manager of the corresponding Linux distribution.

On the host side, Racker can run on Linux, macOS, and Windows. On the containerside, the following list of operating systems has been verified to workwell.

• AmazonLinux 2022
• Arch Linux 20220501
• CentOS 7-9
• Debian 9-12 and unstable (stretch, buster, bullseye, bookworm, sid)
• Fedora 35-37
• openSUSE 15 and latest (leap, tumbleweed)
• Oracle Linux 8
• Red Hat RHEL 8 and 9
• Rocky Linux 8
• SUSE SLES 15 and BCI:latest
• Ubuntu LTS 20 and 22 (focal, jammy)

The aims of Racker are very similar toDocker,Podman,Distrobox andToolbox. However, there are also some differences.

Most people running Linux probably want to usePodman these days. For morebackground, enjoy readingContainer wars andContainer Tools Guide.

• Racker is currently based onsystemd-nspawn andVagrant instead ofDocker orPodman.
• Racker's focus is to provide easy provisioning and launchingOS containersaka.OS-level virtualization, usingsystemd as init process.
• The acquisition and provisioning of operating system images does not need anyspecial preparation steps, those are handled by Racker on the fly.
• Racker aims to provide concise usability by folding its usage into a singlecommand.
• Racker is written in Python instead of Golang or Bash.

See alsoComparison with similar tools - more details.

systemd-nspawn may be used to run a command or OS in a light-weightnamespace container. In many ways it is similar tochroot, but morepowerful since it fully virtualizes the file system hierarchy, as well asthe process tree, the various IPC subsystems and the host and domain name.

It is primarily intended for use in development, experimenting, debugging,instrumentation, testing and building of software.

It can easily be used to start containers capable of booting up a completeand unmodified Linux distribution inside as normal system services.

For learning more details aboutsystemd-nspawn, we strongly recommend toread the more extensivesystemd-nspawn in a nutshell.

Install prerequisites:

apt-get updateapt-get install --yes systemd-container skopeo umoci python3-pip python3-venv

Install Racker:

python3 -m venv .venvsource .venv/bin/activatepip install racker --upgrade

To install the latest development version, use this command instead:

pip install git+https://github.com/cicerops/racker --upgrade

Theracker program aims to resemble the semantics of Docker by providing acommand line interface compatible with thedocker command.

# Invoke the vanilla Docker `hello-world` image.# FIXME: Does not work yet.# racker run -it --rm hello-world /hello# racker run -it --rm quay.io/podman/hello# Acquire rootfs images.racker pull debian:bullseye-slimracker pull fedora:37# Launch an interactive shell.racker run -it --rm debian:bullseye-slim bashracker run -it --rm fedora:37 bashracker run -it --rm docker://registry.access.redhat.com/ubi8/ubi-minimal /bin/bashracker run -it --rm docker://quay.io/centos/centos:stream9 bash# Launch a single command.racker run -it --rm debian:11-slim hostnamectlracker run -it --rm opensuse/tumbleweed hostnamectlracker run -it --rm ubuntu:jammy /bin/cat /etc/os-releaseracker run -it --rm registry.suse.com/suse/sle15 /bin/cat /etc/os-releaseracker run -it --rm registry.suse.com/bci/bci-base:15.4 /bin/cat /etc/os-releaseracker run -it --rm docker://ghcr.io/jpmens/mqttwarn-standard /usr/bin/hostnamectl# Verbose mode.racker --verbose run -it --rm fedora:37 hostnamectl# Use stdin and stdout, with timing.timeecho"hello world"| racker run -it --rm fedora:37 cat /dev/stdin> hellocat hello

The idea behindpostroj is to provide an entrypoint to a command lineinterface implementing actions that don't fit intoracker, mostly having amore high-level character.

Currently,postroj pkgprobe implements a flavor offull systemintegration/acceptance testing in order to test the soundness of actualinstalled binary distribution packages, in the spirit ofautopkgtest.

To do so, it implements the concept ofcurated operating system images,whose labels have a different layout than labels of Docker filesystem images.

Getting started:

# List available images.postroj list-images# Acquire images for curated operating systems.postroj pull debian-bullseyepostroj pull fedora-37# Acquire rootfs images for all available distributions.postroj pull --all# Run a self test procedure, invoking `hostnamectl` on all containers.postroj selftest hostnamectl

Package testing:

# Run a self test procedure, invoking example probes on all containers.postroj selftest pkgprobe# Run two basic probes on different operating systems.postroj pkgprobe --image=debian-bullseye --check-unit=systemd-journaldpostroj pkgprobe --image=fedora-37 --check-unit=systemd-journaldpostroj pkgprobe --image=archlinux-20220501 --check-unit=systemd-journald# Run probes that need to install a 3rd party package beforehand.postroj pkgprobe \    --image=debian-stretch \    --package=http://ftp.debian.org/debian/pool/main/w/webfs/webfs_1.21+ds1-12_amd64.deb \    --check-unit=webfs \    --check-network=http://localhost:8000postroj pkgprobe \    --image=debian-bullseye \    --package=https://dl.grafana.com/oss/release/grafana_8.5.1_amd64.deb \    --check-unit=grafana-server \    --check-network=http://localhost:3000postroj pkgprobe \    --image=centos-8 \    --package=https://dl.grafana.com/oss/release/grafana-8.5.1-1.x86_64.rpm \    --check-unit=grafana-server \    --check-network=http://localhost:3000

A SuT which just uses a dummy probe/bin/systemctl is-active systemd-journaldon Debian 10 "buster" cycles quite fast, essentially demonstrating that theoverhead of environment setup/teardown is insignificant.

time postroj pkgprobe --image=debian-buster --check-unit=systemd-journaldreal    0m0.589suser    0m0.161ssys     0m0.065s

On a cold system, where the filesystem image would need to be acquired beforespawning the container, it's still fast enough:

time postroj pkgprobe --image=debian-bookworm --check-unit=systemd-journaldreal    0m22.582suser    0m8.572ssys     0m3.136s

• Q: How does it work?

  A: Directly quoting themachinectl documentation here:

  Note thatsystemd-run with its--machine= switch may be used in place of themachinectl shell command, and allows non-interactive operation, more detailed andlow-level configuration of the invoked unit, as well as access to runtime and exitcode/status information of the invoked shell process.

  In particular, usesystemd-run's--wait switch to propagate exit status informationof the invoked process. Usesystemd-run's--pty switch for acquiring an interactiveshell, similar tomachinectl shell. In general,systemd-run is preferable forscripting purposes.

• Q: How does it work, really?

  A: Roughly speaking...
  • skopeo andumoci are used to acquire root filesystem images from Docker image registries.
  • systemd-nspawn is used to run commands on root filesystems for provisioning them.
  • Containers are started withsystemd-nspawn --boot.
  • systemd-run is used to interact with running containers.
  • machinectl is used to terminate containers.
• Q: How is this project related with Docker?

  A: The runtime is completely independent of Docker, it is solely based onsystemd-nspawn containers instead. However, root filesystem images can bepulled from Docker image registries in the spirit ofmachinectl pull-dkr.Other than this, theracker command aims to be a drop-in replacement forits correspondingdocker counterpart.
• Q: Do I need to have Docker installed on my machine?

  A: No, Racker works without Docker.
• Q: How are machine names assigned?

  A: Machine names for spawned containers are automatically assigned.The name will be assembled from the distribution'sfullname attribute,prefixed withpostroj-.Examples:postroj-debian-buster,postroj-centos-8.
• Q: Does the program need root privileges?

  A: Yes, the program currently must be invoked withroot or correspondingsudo privileges. However, it would be sweet to enable unprivilegedoperations soon.systemd-nspawn should be able to do it, using--private-users or--user?
• Q: Where does the program store its data?

  A: Data is stored at/var/lib/postroj.In this manner, it completely gets out of the way of any other images, forexample located at/var/lib/machines. Thus, any images created or managedby Racker will not be listed bymachinectl list-images.

  A: The download cache is located at/var/cache/postroj/downloads.
• Q: Where are the filesystem images stored?

  A: Activated filesystem images are located at/var/lib/postroj/images.
• Q: How large are curated filesystem images?

  A: The preference for curated filesystem images is to use their corresponding"slim" variants where possible, aiming to only use artefacts with downloadsizes < 100 MB.
• Q: Are container disks ephemeral?

  A: Yes, by default, all container images will be ephemeral, i.e. all changes tothem are volatile.

It's always the cable. ;]

1. If you see that your container might not have network access, make sure toprovide a valid DNS configuration in your host's/etc/resolv.conf.When in doubt, please addnameserver 9.9.9.9 as the first entry.

2. Sometimes, configuring an arbitrary name server is not permitted. An indicatorcould be this configuration within/etc/resolv.conf:

   nameserver 127.0.0.53options edns0 trust-ad

   If that is the case, you can look up the trusted DNS servers by runningresolvectl status orresolvectl dns. Then, use the DNS server listedthere to announce pernameserver <dns host> entry to your container's/etc/resolv.conf.