Skip to content

catalog

catalog

Distro-slot catalog — facts about the shared matrix base images.

Everything in here is a property of a slot (the base image and how a test container on it behaves), never of a consuming repository: which Containerfile builds it, which podman the distro ships, whether the image is systemd-free, and which user runs the tests. Repo-specific choices (slot selection, extra packages, test phases) live in each repo's matrix.yml — see config.

Two slot kinds exist:

  • container — a regular distro image; tests run via su as the slot's test user.
  • nix — the wrapped-Python oddball (no su, no podman inside); the runner switches users via Python os.setuid and reports the Python version instead of a podman version.

SOURCE_MOUNT = '/src' module-attribute

WORKSPACE_DIR = '/workspace' module-attribute

RESULTS_MOUNT = '/results' module-attribute

PYTHON_VERSION = '3.12' module-attribute

OWNERSHIP_LABEL = 'io.terok.matrix-test' module-attribute

MATRIX_ENV = 'TEROK_MATRIX' module-attribute

EXPECT_ENV = 'TEROK_EXPECT' module-attribute

KERNEL_ISOLATED_ENV = 'TEROK_KERNEL_ISOLATED' module-attribute

SLOT_ENV = 'TEROK_SLOT' module-attribute

KRUN_RUNTIME = 'krun' module-attribute

KRUN_PASST_ANNOTATION = 'krun.use_passt=1' module-attribute

KRUN_DISK_IMG = '/krun-disk.img' module-attribute

KRUN_DISK_SIZE = '16G' module-attribute

KRUN_DISK_MOUNT = '/kd' module-attribute

SYSTEMD_INIT = '/usr/lib/systemd/systemd' module-attribute

SYSTEMD_COMM = 'systemd' module-attribute

USER_MANAGER_UNIT = 'user@{uid}.service' module-attribute

SYSTEM_BUS_SOCKET_UNIT = '/usr/lib/systemd/system/dbus.socket' module-attribute

SYSTEMD_CONTROL_DIR = '/etc/systemd/system.control' module-attribute

BOOT_TARGET = 'terok-matrix.target' module-attribute

SLOT_SERVICE = 'terok-matrix-slot.service' module-attribute

FLAVORS = ('podman', 'dbus') module-attribute

UV_IMAGE_TAG = '0.11' module-attribute

UV_MANAGED_PYTHON_DIR = '/opt/uv/python' module-attribute

SLOTS = {'debian12': SlotSpec(expected_podman='4.3.1'), 'ubuntu2404': SlotSpec(expected_podman='4.9.3'), 'ubuntu2604': SlotSpec(expected_podman='5.7.0'), 'debian13': SlotSpec(expected_podman='5.4.2'), 'fedora43': SlotSpec(expected_podman='5.8.4'), 'fedora44': SlotSpec(expected_podman='5.8.4'), 'podman': SlotSpec(expected_podman='5.8.4', user='podman'), 'alpine': SlotSpec(expected_podman='5.3.2', non_systemd=True, pasta_symlink=True), 'void': SlotSpec(expected_podman='5.8.3', non_systemd=True, pasta_symlink=True), 'mageia': SlotSpec(expected_podman='4.9.5'), 'manjaro': SlotSpec(expected_podman='6.1.0', pasta_symlink=True), 'nix': SlotSpec(kind=SlotKind.NIX), 'nixos': SlotSpec(expected_podman='5.8.7', requires_boot=True, boot_init='/init', bash_path='/run/current-system/sw/bin/bash')} module-attribute

SlotKind

Bases: StrEnum

How a slot's test container is driven.

CONTAINER = 'container' class-attribute instance-attribute

NIX = 'nix' class-attribute instance-attribute

SlotSpec(expected_podman='latest', non_systemd=False, user='testrunner', kind=SlotKind.CONTAINER, pasta_symlink=False, requires_boot=False, boot_init=SYSTEMD_INIT, bash_path='/bin/bash') dataclass

Facts about one matrix slot's base image.

Parameters:

Name Type Description Default
expected_podman str

Distro-shipped podman version the slot is pinned to; "latest" for rolling images (and for slot kinds that never read it, like nix).

 'latest'
non_systemd bool

The runner hard-fails the slot if systemd is present — these slots exist to prove the systemd-free floor.

 False
user str

Non-root user baked into the image (uid 1000).

 'testrunner'
kind SlotKind

Driving mode, see SlotKind.

 CONTAINER
pasta_symlink bool

The distro ships /usr/bin/pasta as a symlink to passt (upstream's default; Debian hard-links, Fedora builds it apart). AppArmor attaches profiles by the resolved path and is not container-namespaced, so on a host with the distro passt profile the nested pasta runs under that profile and loses its netns — the runner skips such slots there.

 False
requires_boot bool

The image needs its normal boot to provision runtime state (NixOS security wrappers); skip it outside --krun.

 False
boot_init str

Image entry point for a booted slot.

 SYSTEMD_INIT
bash_path str

Bash path for scripts and systemd units in this image.

 '/bin/bash'

expected_podman = 'latest' class-attribute instance-attribute

non_systemd = False class-attribute instance-attribute

user = 'testrunner' class-attribute instance-attribute

kind = SlotKind.CONTAINER class-attribute instance-attribute

requires_boot = False class-attribute instance-attribute

boot_init = SYSTEMD_INIT class-attribute instance-attribute

bash_path = '/bin/bash' class-attribute instance-attribute

runs_nested_podman(flavor)

Whether this slot runs nested rootless podman under flavor.

True only for a container-kind slot on the podman flavor: the nix slot has no podman inside, and the dbus flavor runs none. This gates the resolv.conf fix and, under krun, the device setup and store binds.

Source code in src/terok_util/matrix/catalog.py 
168
169
170
171
172
173
174
175
def runs_nested_podman(self, flavor: str) -> bool:
    """Whether this slot runs nested rootless podman under *flavor*.

    True only for a container-kind slot on the ``podman`` flavor: the nix
    slot has no podman inside, and the dbus flavor runs none.  This gates
    the resolv.conf fix and, under krun, the device setup and store binds.
    """
    return flavor == "podman" and self.kind is SlotKind.CONTAINER

may_boot_systemd(flavor, krun)

Whether this slot boots systemd as PID 1, where its image ships one.

Only under krun: the microVM owns its kernel and cgroup tree, so the image's systemd can be PID 1 and give the tests a real per-user manager. Under a shared kernel the slot stays a plain --init container, and the systemd-free floor slots stay systemd-free everywhere. NixOS requires boot even on the dbus flavor. Otherwise the runner checks for the image's own systemd and system bus.

Source code in src/terok_util/matrix/catalog.py 
177
178
179
180
181
182
183
184
185
186
187
188
189
def may_boot_systemd(self, flavor: str, krun: bool) -> bool:
    """Whether this slot boots systemd as PID 1, where its image ships one.

    Only under krun: the microVM owns its kernel and cgroup tree, so the
    image's systemd can be PID 1 and give the tests a real per-user
    manager.  Under a shared kernel the slot stays a plain ``--init``
    container, and the systemd-free floor slots stay systemd-free
    everywhere.  NixOS requires boot even on the dbus flavor.  Otherwise
    the runner checks for the image's own systemd and system bus.
    """
    return krun and (
        self.requires_boot or (self.runs_nested_podman(flavor) and not self.non_systemd)
    )