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:
ContainerSpec::ports—PortMappings published to the host. Loopback-only by default (127.0.0.1), so a service is never reachable from the network by accident; exposing a port on another interface is an explicitPortMapping::with_host_ip.ContainerSpec::network— attach to a user-defined bridge network (so containers resolve each other by name via dockerd’s embedded DNS).Lifecycle::ensure_networkcreates it idempotently.ContainerSpec::volumes— named Docker volumes (crate::mount::VolumeMount), optionally plugin-backed. No host bind mounts; see that type’s doc for why.
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.ioshort 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§
- Container
Spec - 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.
- Port
Mapping - One container port published to the host (
docker run -p).
Enums§
- Protocol
- Transport protocol of a published port.
- Restart
Policy - 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.