rules_podman

bazel_dep(name = "rules_podman", version = "0.0.2")

load("@rules_podman//podman/machine:machine.bzl", "podman_machine")

podman_machine(
    name = "machine",
    image = "//path:fcos.raw",              # a bootable Podman/FCOS disk
    ssh_authorized_keys = ["ssh-ed25519 AAAA… you@host"],
)

common --registry=https://registry.fastverk.com/
common --registry=https://bcr.bazel.build/

bazel_dep(name = "rules_podman", version = "0.0.1")

podman = use_extension("@rules_podman//podman:extensions.bzl", "podman")
# Optional: pin a specific Podman version (defaults to the bundled pin).
# podman.toolchain(version = "5.8.2")
use_repo(podman, "podman")
register_toolchains("@podman//:podman_toolchain_def")

load("@rules_podman//podman:defs.bzl", "podman_run", "podman_build", "podman_image_load")

# `bazel run //:podman -- ps -a` — args forwarded verbatim. Daemonless on Linux.
podman_run(name = "podman")

# `bazel run //:image` — stage the context + `podman build`, in a clean store.
podman_build(
    name = "image",
    srcs = ["Containerfile", "app/server.py"],
    image_tags = ["registry.example.com/app:latest"],
    storage = "ephemeral",
    # build_args = {"VERSION": "1.2.3"},
)

# `bazel run //:load` — `podman load -i` an OCI/docker archive
# (e.g. the output of @rules_oci's oci_load).
podman_image_load(
    name = "load",
    image = "//path/to:image.tar",
)

tools/refresh_versions.py            # latest stable
tools/refresh_versions.py --version 5.8.2

bazel run //docs:update

Real usage, taken from the module’s examples/.

examples/machine/BUILD.bazel

load("@bazel_skylib//rules:build_test.bzl", "build_test")
load("@bazel_skylib//rules:diff_test.bzl", "diff_test")
load("@rules_macvm//vm:toolchains.bzl", "vm_provider")
load("@rules_podman//podman/machine:machine.bzl", "podman_machine")
load("@rules_shell//shell:sh_binary.bzl", "sh_binary")

# Our own mock VMM (rules_macvm's is dev-only and invisible to consumers).
sh_binary(
    name = "mock_vmm",
    srcs = ["mock_vmm.sh"],
)

vm_provider(
    name = "mock_provider",
    efi_boot = True,
    kind = "mock",
    linux_boot = True,
    nested = True,
    rosetta = True,
    virtiofs = True,
    vmm = ":mock_vmm",
    vsock = True,
)

# A Podman service VM built against the mock backend, so the provisioning
# + VM spec are tested hermetically (no Apple Virtualization.framework).
# For a real machine, drop `provider` (uses the registered @vfkit
# toolchain) and point `image` at a bootable Podman/FCOS disk, on a Mac.
podman_machine(
    name = "machine",
    image = "fcos.raw",
    provider = ":mock_provider",
    ssh_authorized_keys = ["ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAID demo@rules_podman"],
)

# Golden: the rendered Ignition (ssh key + enable podman.socket).
diff_test(
    name = "machine_ignition_test",
    file1 = "machine.ignition.ign.golden",
    file2 = "machine.ignition.ign",
)

# Golden: the resolved vfkit-style VM command line (EFI boot + vsock +
# nat + rosetta + the ignition).
diff_test(
    name = "machine_argv_test",
    file1 = "machine.argv.golden",
    file2 = "machine.argv",
)

build_test(
    name = "machine_build_test",
    targets = [
        ":machine",
        ":machine.ignition",
    ],
)

examples/smoke/BUILD.bazel

load("@bazel_skylib//rules:build_test.bzl", "build_test")
load("@rules_podman//podman:defs.bzl", "podman_build", "podman_image_load", "podman_run")
load("@rules_shell//shell:sh_test.bzl", "sh_test")

# `bazel run //examples/smoke:podman -- ps -a` — drive Podman. Daemonless
# on Linux; on macOS/Windows it talks to your `podman machine`.
podman_run(
    name = "podman",
)

# `bazel run //examples/smoke:daemonless` — proves the Linux engine runs
# with no service: `podman info` against a throwaway vfs store. Run-only
# (needs the Linux engine toolchain + host userns); not wired as a test
# because nested user namespaces under the Bazel sandbox are environment-
# dependent.
podman_run(
    name = "daemonless",
    extra_args = ["info"],
    storage = "ephemeral",
)

# Hermetic smoke: `podman --version` exits 0 and reports the pinned
# version, offline — no service required. Verifies the toolchain resolves
# and the fetched binary (daemonless launcher on Linux, client elsewhere)
# executes on the host.
sh_test(
    name = "podman_version_test",
    srcs = ["version_smoke.sh"],
    args = [
        "$(rootpath @podman//:podman)",
        "5.8.2",
    ],
    data = ["@podman"],
)

# `bazel run //examples/smoke:image` — builds `rules_podman/smoke:latest`
# from the local Containerfile in a throwaway vfs store (daemonless on Linux).
podman_build(
    name = "image",
    srcs = [
        "Containerfile",
        "app.txt",
    ],
    image_tags = ["rules_podman/smoke:latest"],
    storage = "ephemeral",
)

# Tar the context into a stand-in archive so the load rule has a real
# file input to wire up. (A `FROM scratch` tarball isn't a loadable OCI
# image — running this needs a genuine archive; the build_test below only
# covers analysis + launcher generation.)
genrule(
    name = "sample_tar",
    srcs = ["app.txt"],
    outs = ["sample.tar"],
    cmd = "tar -cf $@ -C $$(dirname $(location app.txt)) app.txt",
)

# `bazel run //examples/smoke:load` — `podman load -i sample.tar`.
podman_image_load(
    name = "load",
    image = ":sample.tar",
)

# Daemon-free coverage for podman_build / podman_image_load: analyze the
# rules and build their launcher scripts without executing them.
build_test(
    name = "rules_build_test",
    targets = [
        ":image",
        ":load",
    ],
)

from docs/defs.md

User-facing Bazel rules for rules_podman.

Three bazel run-friendly wrappers around the Podman binary resolved through @rules_podman//podman:toolchain_type:

• podman_run: a thin launcher — exec podman with optional --connection/--url, an optional isolated storage root, and any baked-in extra_args, forwarding CLI arguments verbatim.
• podman_build: stage a tracked build context (the rule’s srcs) into a temp dir and podman build it. Inputs are real Bazel deps, so edits to the Containerfile / context invalidate the run.
• podman_image_load: podman load -i <tarball> an OCI/docker archive produced elsewhere in the graph (e.g. @rules_oci’s oci_load).

Daemonless on Linux: the default toolchain there is the static mgoltzsche/podman-static engine, so these rules run containers with no service — podman forks conmon → crun directly. On macOS/Windows the toolchain is the official client, which needs a podman machine; point it at one via CONTAINER_HOST, url/connection, or a running machine.

Storage isolation (storage = "ephemeral"|"workspace") injects --root/--runroot/--storage-driver=vfs so a run gets a clean, host-independent container store. It only applies to engine toolchains (those flags are server-side; a remote client ignores them).

For the bare binary depend directly on @podman//:podman.

podman_build

load("@rules_podman//podman:defs.bzl", "podman_build")

podman_build(name, srcs, build_args, connection, containerfile, extra_args, image_tags, storage,
             storage_dir, url)

Build an image from a tracked build context via bazel run. Stages srcs into a temp context and runs podman build (daemonless on Linux).

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
srcs	The build context: the Containerfile plus everything it COPYs/ADDs. Staged into the build context preserving each file’s path relative to this rule’s package.	List of labels	required
build_args	--build-arg KEY=VALUE pairs passed to podman build.	Dictionary: String -> String	optional	{}
connection	Named Podman system connection to target (--connection).	String	optional	""
containerfile	Path of the Containerfile within the staged context (i.e. relative to this rule’s package). Must be among srcs.	String	optional	"Containerfile"
extra_args	Flags appended after the rules_podman defaults but before any args passed on the CLI.	List of strings	optional	[]
image_tags	Image tags to apply (-t). (Named image_tags, not tags, which is Bazel’s reserved target-tags attribute.)	List of strings	optional	[]
storage	Container-store isolation (engine/daemonless toolchains only): * default: use podman’s standard rootless store (shared, persists). * ephemeral: a fresh $TMPDIR/podman_store.XXXXXX with --storage-driver=vfs, removed on exit. Hermetic, but images don’t persist across runs. * workspace: a persistent store under $BUILD_WORKSPACE_DIRECTORY/<storage_dir> (requires bazel run).	String	optional	"default"
storage_dir	Workspace-relative store path used when storage = "workspace". Defaults to .cache/rules_podman/<target name>.	String	optional	""
url	Podman service URL to target (--url), e.g. unix:///run/podman/podman.sock or an ssh:// endpoint. Overrides $CONTAINER_HOST for this invocation.	String	optional	""

podman_image_load

load("@rules_podman//podman:defs.bzl", "podman_image_load")

podman_image_load(name, connection, extra_args, image, storage, storage_dir, url)

podman load -i <tarball> an image archive into the target store via bazel run. Use storage = "workspace" to load into a persistent store.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
connection	Named Podman system connection to target (--connection).	String	optional	""
extra_args	Flags appended after the rules_podman defaults but before any args passed on the CLI.	List of strings	optional	[]
image	An OCI-archive or docker-archive tarball to podman load, e.g. the output of @rules_oci’s oci_load rule.	Label	required
storage	Container-store isolation (engine/daemonless toolchains only): * default: use podman’s standard rootless store (shared, persists). * ephemeral: a fresh $TMPDIR/podman_store.XXXXXX with --storage-driver=vfs, removed on exit. Hermetic, but images don’t persist across runs. * workspace: a persistent store under $BUILD_WORKSPACE_DIRECTORY/<storage_dir> (requires bazel run).	String	optional	"default"
storage_dir	Workspace-relative store path used when storage = "workspace". Defaults to .cache/rules_podman/<target name>.	String	optional	""
url	Podman service URL to target (--url), e.g. unix:///run/podman/podman.sock or an ssh:// endpoint. Overrides $CONTAINER_HOST for this invocation.	String	optional	""

podman_run

load("@rules_podman//podman:defs.bzl", "podman_run")

podman_run(name, connection, extra_args, storage, storage_dir, url)

Run Podman via bazel run. Daemonless on Linux; CLI arguments are forwarded verbatim (bazel run //:podman -- ps -a).

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
connection	Named Podman system connection to target (--connection).	String	optional	""
extra_args	Flags appended after the rules_podman defaults but before any args passed on the CLI.	List of strings	optional	[]
storage	Container-store isolation (engine/daemonless toolchains only): * default: use podman’s standard rootless store (shared, persists). * ephemeral: a fresh $TMPDIR/podman_store.XXXXXX with --storage-driver=vfs, removed on exit. Hermetic, but images don’t persist across runs. * workspace: a persistent store under $BUILD_WORKSPACE_DIRECTORY/<storage_dir> (requires bazel run).	String	optional	"default"
storage_dir	Workspace-relative store path used when storage = "workspace". Defaults to .cache/rules_podman/<target name>.	String	optional	""
url	Podman service URL to target (--url), e.g. unix:///run/podman/podman.sock or an ssh:// endpoint. Overrides $CONTAINER_HOST for this invocation.	String	optional	""

from docs/extensions.md

Module extension for rules_podman.

Hermetically fetches Podman for the host platform, pinned by sha256 (see private/known_versions.bzl), and exposes it as @podman//:podman plus a ready-to-register toolchain (@podman//:podman_toolchain_def).

On Linux it fetches the fully-static mgoltzsche/podman-static bundle and generates a launcher that wires podman to its bundled OCI runtime (crun), conmon, netavark, and configs — a real daemonless, rootless engine, no service to start. On macOS/Windows it fetches the official client binary (which talks to a podman machine).

Default usage:

podman = use_extension("@rules_podman//podman:extensions.bzl", "podman")
use_repo(podman, "podman")
register_toolchains("@podman//:podman_toolchain_def")

Pin a specific Podman version:

podman = use_extension("@rules_podman//podman:extensions.bzl", "podman")
podman.toolchain(version = "5.8.2")
use_repo(podman, "podman")

podman

podman = use_extension("@rules_podman//podman:extensions.bzl", "podman")
podman.toolchain(version)

Sets up @podman: a daemonless static engine on Linux, the official client on macOS/Windows.

TAG CLASSES

toolchain

Attributes

Name	Description	Type	Mandatory	Default
version	Override the Podman version. Defaults to the value in known_versions.bzl.	String	optional	""

from docs/machine.md

podman_machine — a self-managed Podman service VM for macOS.

On Linux, rules_podman is daemonless (the static engine forks the OCI runtime directly). macOS has no Linux kernel, so the podman service must run inside a Linux VM. This macro composes rules_macvm to provide that VM hermetically and reproducibly — the Docker-Desktop / podman machine architecture, but pinned and Bazel-native:

1. ignition_config renders provisioning (inject an SSH key, enable podman.socket) entirely from attrs.
2. vm EFI-boots a bootable Podman/Fedora-CoreOS image with that Ignition, exposing the Podman API socket over virtio-vsock and NAT networking.

bazel run //:<name> boots it; point the client at the socket (CONTAINER_HOST=unix://<socket>) and rules_podman’s podman_run / podman_build / podman_image_load drive containers inside it.

VALIDATION BOUNDARY: the rendered Ignition and the VM spec/argv are golden-tested. The live boot + connect path needs a real Mac and a bootable Podman image, and is NOT exercised in CI (Apple Virtualization.framework can’t run in cloud CI). Treat the boot path as unvalidated until run on hardware.

podman_machine

load("@rules_podman//podman/machine:machine.bzl", "podman_machine")

podman_machine(name, image, ssh_authorized_keys, enable_units, cpus, memory, rosetta, socket,
               extra_devices, provider, visibility, **kwargs)

Declare a self-managed Podman service VM.

PARAMETERS

Name	Description	Default Value
name	target name; bazel run //:<name> boots the VM.	none
image	a bootable Podman/FCOS disk image (EFI-booted as virtio-blk).	none
ssh_authorized_keys	SSH public keys to authorize in the guest.	[]
enable_units	systemd units to enable (default: podman.socket).	["podman.socket"]
cpus	virtual CPUs.	2
memory	guest RAM, e.g. “2GiB”.	"2GiB"
rosetta	expose Rosetta x86-64 translation (Apple Silicon).	True
socket	host path for the forwarded Podman API socket. Default is a per-boot ephemeral path; pass a stable path for a durable CONTAINER_HOST across boots.	"$VM_RUNTIME/podman.sock"
extra_devices	extra raw vfkit --device specs.	[]
provider	VMM backend override (defaults to the registered rules_macvm toolchain, i.e. @vfkit on macOS). Tests pass the mock.	None
visibility	target visibility.	None
kwargs	forwarded to the underlying vm rule.	none

from docs/toolchains.md

Toolchain rule for rules_podman.

podman_toolchain wraps a hermetically-fetched Podman binary as a single Bazel toolchain. The user-facing rules (podman_run, podman_build, podman_image_load) resolve their client through @rules_podman//podman:toolchain_type, so a custom Podman (a locally-built engine, a distro package, a different pinned version) can be swapped in via register_toolchains(...) without touching rule attributes.

The engine field tells the rules whether this is a real local engine (Linux daemonless bundle) or a remote client (macOS/Windows). Storage isolation (--root/--runroot/--storage-driver) is only injected for engine toolchains — those flags are server-side and ignored by a client.

The module extension at @rules_podman//podman:extensions.bzl generates a default toolchain (@podman//:podman_toolchain_def). Register it from MODULE.bazel:

register_toolchains("@podman//:podman_toolchain_def")

podman_toolchain

load("@rules_podman//podman:toolchains.bzl", "podman_toolchain")

podman_toolchain(name, engine, podman, version)

Declare a Podman binary as a Bazel toolchain.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
engine	True if this binary is a local daemonless engine; False for a remote client. Gates storage-isolation flag injection in the rules.	Boolean	optional	False
podman	The podman executable target.	Label	required
version	The Podman release version of this binary. Informational; surfaced on PodmanToolchainInfo for diagnostics.	String	optional	""

PodmanToolchainInfo

load("@rules_podman//podman:toolchains.bzl", "PodmanToolchainInfo")

PodmanToolchainInfo(podman, version, engine)

A Podman binary, resolved via a toolchain.

FIELDS

Name	Description
podman	Target: the podman executable (a daemonless launcher on Linux, the client binary on macOS/Windows).
version	String: the Podman release version this binary reports (e.g. “5.8.2”). Empty for custom toolchains that don’t set it.
engine	Bool: True if this is a local daemonless engine (forks the OCI runtime directly); False for a remote client that needs a podman machine / reachable service.