Skip to main content

Module lifecycle

Module lifecycle 

Source
Expand description

lifecycle — Container / process lifecycle over dockerd — create, start, stop, health, restart policy.

This is the piece principal.rs’s own module doc flags as deferred: “[r]esolving a real ContainerRef from a running container is lifecycle’s job, in a later slice.” Lifecycle::container_ref is that job — it inspects a running container over the real dockerd Engine API, resolves its uid from /proc, and composes cgroup’s and mount’s own resolvers to fill in ContainerRef::cgroup/mount_ns, so principal::embody can be called with real data end-to-end.

Scope boundary (hard constraint, same as every substrate-kit module): this is pure OS mechanics over dockerd. It never constructs a ServicePrincipal, never decides which principal a container belongs to, and never makes an authorization decision — see principal.rs’s module doc for the full hard-constraint statement.

§What “health” means here, deliberately, and what it doesn’t

Lifecycle::wait_until_running confirms a container reaches, and stays at, Docker’s own State.Running: true — a single “is it Running” read is a TOCTOU race against a container whose process crashes moments after starting, so this re-checks after a short grace period before declaring success. This does not prove the service inside the container is ready to take traffic (no HTTP readiness probe, no Docker HEALTHCHECK wiring) — that is a real, separate concern for whatever calls this crate, not this slice’s job. This keeps health at the layer dockerd itself reports.

§Restart-policy handling

RestartPolicy is a thin, OS-mechanics-only wrapper over dockerd’s own restart-policy enum (bollard::models::RestartPolicyNameEnum) — it carries no meaning beyond “what dockerd should do when this container’s process exits,” the same as docker run --restart.

§Networking and volumes

ContainerSpec carries three additive, opt-in fields:

All three default to empty/None, which produces exactly the container this module created before.

§Environment and credentials

ContainerSpec::env is not a credential channel. Anything in it is readable by docker inspect and shows up in dockerd’s own state. The rule is that no credential travels in an environment variable or a unit file. This crate therefore does not accept, read or log credentials: it never reads std::env, and ContainerSpec’s Debug impl prints env keys only, so a tracing::debug!(?spec) cannot leak a value. A credential-delivery seam (secret files mounted read-only, sourced from $CREDENTIALS_DIRECTORY by the caller) and registry-pull credentials are designed but not implemented here; both need a security review first.

§Deliberately out of scope, not oversights

  • No registry-credential handling in Lifecycle::pull_image — every image this crate’s own tests pull is public (docker.io short names); a private-registry credential seam is real, deferred follow-up.
  • No Docker-socket hardening. This talks to the raw local dockerd socket — socket.rs’s job is AF_UNIX hardening for services running on the substrate, not this crate’s own dockerd client connection.

Structs§

ContainerSpec
What to run.
Lifecycle
A connected handle to the local dockerd Engine API. Never a remote/TCP Docker endpoint — this always runs containers on the same host the substrate itself is running on, like any other service on the box.
PortMapping
One container port published to the host (docker run -p).

Enums§

Protocol
Transport protocol of a published port.
RestartPolicy
dockerd’s own restart-policy semantics, wrapped only so callers don’t need to reach into bollard’s model types directly. Carries no meaning beyond what dockerd itself gives --restart — see this module’s doc.

Constants§

LABEL_MANAGED
Every container this module creates carries this label, purely so a caller (or this crate’s own tests) can find/clean up what it started without keeping its own in-memory bookkeeping.