Documentation
¶
Overview ¶
Package podman implements runtime.Runtime on Podman, adding CRIU-backed checkpoint/restore (runtime.CheckpointRuntime) — the one engine that does the full migration round trip (docker's restore is broken on current versions; see design/checkpoint-restore.md).
Transport (design/podman-backend.md, Option A): the standard Runtime surface (run/exec/inspect/pull/networks/…) is served by an embedded *docker.Runtime pointed at Podman's docker-compatible socket — Podman exposes the moby REST API there, so the existing, well-tested docker backend works unchanged. Two areas differ and are overridden here, both driven through the libpod REST API on the SAME socket (a thin stdlib HTTP client — no `podman` CLI subprocess, no heavy pkg/bindings dependency):
- Checkpoint/Restore: libpod-only, not in the docker-compat API.
- BuildImage: the docker backend's build is BuildKit-only, which Podman's docker-compat /build does not provide; we build with buildah via the libpod /build endpoint.
Index ¶
- type Options
- type Runtime
- func (r *Runtime) BuildImage(ctx context.Context, spec runtime.BuildSpec, events chan<- runtime.BuildEvent) (runtime.ImageRef, error)
- func (r *Runtime) Capabilities() runtime.Capabilities
- func (r *Runtime) Checkpoint(ctx context.Context, id string, spec runtime.CheckpointSpec) (runtime.CheckpointRef, error)
- func (r *Runtime) PreferSelfProbedHealth() bool
- func (r *Runtime) Restore(ctx context.Context, spec runtime.RestoreSpec) (*runtime.Container, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Options ¶
type Options struct {
// Socket is the Podman service socket serving both the
// docker-compatible and libpod APIs (e.g.
// "unix:///run/podman/podman.sock"). Required — Podman must be
// running `podman system service`.
Socket string
// CheckpointProbe optionally asserts CRIU availability on the host
// serving Socket. It gates Capabilities().Checkpoint together with
// libpod reachability, runs once at New, and its result is cached.
//
// The backend cannot verify CRIU itself: the libpod REST API has no
// `criu check` equivalent and /info doesn't report CRIU, and the
// backend is deliberately CLI-free (no `criu check` shell-out). But
// the deployer runs `podman system service` and knows the host, so
// they can supply a probe (exec `criu check`, read a provisioning
// marker, etc.).
//
// Nil means "don't probe": Capabilities().Checkpoint then reflects
// libpod reachability only, and a missing CRIU surfaces at Checkpoint
// time as a *runtime.CheckpointFailedError (callers fall back to a
// cold Up — workspace data on the volume is intact).
CheckpointProbe func(context.Context) bool
}
Options configure New.
type Runtime ¶
Runtime is the Podman backend. It embeds a *docker.Runtime (wired to Podman's docker-compatible socket) for the standard surface and adds the libpod-only checkpoint/restore + buildah build via a thin libpod HTTP client over the same socket.
func New ¶
New constructs a Podman runtime: wires the embedded docker.Runtime to the Podman service socket and a libpod client to the same socket.
func (*Runtime) BuildImage ¶
func (r *Runtime) BuildImage(ctx context.Context, spec runtime.BuildSpec, events chan<- runtime.BuildEvent) (runtime.ImageRef, error)
BuildImage builds an image with buildah via the libpod /build endpoint: streams the context as a tar request body, forwards the build log as BuildEventLog events, and returns the built image's reference.
func (*Runtime) Capabilities ¶
func (r *Runtime) Capabilities() runtime.Capabilities
Capabilities reports the Podman backend's feature profile. It does not delegate to the embedded docker.Runtime: Podman has its own profile, and Checkpoint is the bit that matters here.
func (*Runtime) Checkpoint ¶
func (r *Runtime) Checkpoint(ctx context.Context, id string, spec runtime.CheckpointSpec) (runtime.CheckpointRef, error)
Checkpoint exports a running container to a self-contained archive via the libpod checkpoint endpoint with export=true (the response body is the tar archive). Verified against podman 5.4:
POST /libpod/containers/{id}/checkpoint?export=true&tcpestablished=&leaverunning=
func (*Runtime) PreferSelfProbedHealth ¶
PreferSelfProbedHealth tells the compose orchestrator to run healthcheck probes itself (via Exec) rather than configuring Podman's native HEALTHCHECK. Podman runs the native healthcheck as root and fires the first probe immediately at container start — before the main process initializes — which breaks privilege-dropping images: e.g. rabbitmq's `rabbitmq-diagnostics` probe, run as root, creates a root-owned /var/lib/rabbitmq/.erlang.cookie that the gosu-dropped (uid 999) server then cannot read (eacces). Letting the orchestrator probe defers the first check until after the service is up, matching Docker's behavior. See design/compose-native-health.md.
func (*Runtime) Restore ¶
func (r *Runtime) Restore(ctx context.Context, spec runtime.RestoreSpec) (*runtime.Container, error)
Restore re-creates and resumes a container from a checkpoint archive, uploading the archive in the request body. Verified against podman 5.4:
POST /libpod/containers/import/restore?import=true&tcpestablished=&name= (body: the tar archive; "import" is the literal path segment)
Source Files