Documentation
¶
Overview ¶
Package containerd runs steps as OCI containers on a containerd daemon.
It talks to containerd directly, with no Docker daemon anywhere in the picture: ADR 0006 ships containerd/OCI precisely so that the container backend is a client of the runtime rather than of another daemon that owns it. A sandbox is one container holding an idle init process, and commands are exec processes inside it. That shape is what makes the lease scopes mean something here — a step-scoped sandbox is a container deleted when the step ends, a pipeline-scoped one is the same container entered again for every step, carrying state no cache key can describe, which is why internal/cache refuses to cache such steps.
Nothing here asks the executor interface to grow a container shape. The container is an implementation detail behind Acquire, and everything this backend cannot honestly promise — privilege, a real network, secret delivery — is a capability it declines to advertise rather than a special case in the core.
Two things the container gets by default, and both are deliberate: an unprivileged uid, because a step that gets root in its sandbox gets root over every host resource that sandbox is given; and a lazily mounted image where the daemon can do it, decided by SelectPullMode in lazypull.go.
Index ¶
Constants ¶
const ( // StargzSnapshotter is the containerd snapshotter that mounts eStargz // images lazily, fetching chunks on demand. StargzSnapshotter = "stargz" // DefaultSnapshotter is the ordinary overlay snapshotter: correct // everywhere, and it pulls the whole image before the container starts. DefaultSnapshotter = "overlayfs" )
Lazy pull is one of the levers ADR 0006 names for making containers feel fast without adding a backend to work around a caching deficiency. With the stargz snapshotter plugged into containerd, a container starts on an eStargz image after fetching its table of contents and the few chunks the command actually touches, so a 500MB image running `true` reads a few megabytes. Without it, the runtime pulls and unpacks every layer first.
const Kind = "containerd"
Kind is this backend's stable identifier in configuration.
Variables ¶
This section is empty.
Functions ¶
func New ¶
New returns a containerd executor talking to the daemon cfg names.
It does not dial: containerd's client connects lazily, and that is worth keeping — a control plane that cannot construct its executor at startup because a node's daemon is briefly down is a worse failure than a step that fails when it runs.
Types ¶
type Config ¶
type Config struct {
// Address is the containerd socket. Empty means containerd's own default
// (/run/containerd/containerd.sock); a k3s node's is at
// /run/k3s/containerd/containerd.sock.
Address string
// Namespace is the containerd namespace sandboxes are created in. Empty
// means "dhole".
Namespace string
// Image is the sandbox image. Empty means defaultImage. A Spec may name
// its own, which then applies to that sandbox only.
Image string
// Snapshotter overrides the snapshotter to pull and run with. Empty lets
// SelectPullMode choose, which prefers lazy pull where the daemon has it.
Snapshotter string
// Privileged makes sandboxes run privileged and as root, and makes this
// executor advertise CAPABILITY_PRIVILEGED. It is off by default, and a
// spec requesting privilege against an executor without it is refused
// rather than quietly run unprivileged.
Privileged bool
// HostNetwork puts sandboxes in the host's network namespace, and makes
// this executor advertise CAPABILITY_NETWORK. Without it a container gets
// its own empty namespace — loopback and nothing else — so advertising
// network there would be a promise the scheduler would rely on.
HostNetwork bool
// InsecureRegistries are registry hosts ("host" or "host:port") reachable
// over plain HTTP. Anything not named here is contacted over HTTPS.
InsecureRegistries []string
// Logger receives the pull-mode decisions. Nil means slog.Default.
Logger *slog.Logger
}
Config is how a containerd executor is pointed at a daemon.
type Executor ¶
type Executor struct {
// contains filtered or unexported fields
}
Executor hands out sandboxes that are containerd containers.
func (*Executor) Capabilities ¶
func (e *Executor) Capabilities() []dholev1.Capability
Capabilities implements executor.Executor. Only what the configuration genuinely provides is advertised: a container with its own network namespace has loopback and nothing else, and an unprivileged container is not privileged however much a step would like it to be. Secret delivery is not implemented here at all.
func (*Executor) EnvironmentIdentity ¶
EnvironmentIdentity implements executor.Executor. It is the digest the sandbox image resolves to, never its tag: the same tag serves different content over time, so a cache keyed on one returns yesterday's answer for today's image (ADR 0021). An image that cannot be resolved yields ErrNoStableIdentity, and its steps stay uncached.
The identity describes the executor's configured image. A Spec naming its own image gets that image for its container; a caller mixing images on one executor needs a per-sandbox identity the interface does not yet carry.
type PullMode ¶
type PullMode struct {
// Snapshotter is the name to pass to containerd on pull and on container
// creation. Both must agree, or the container is created against a
// snapshot the puller never wrote.
Snapshotter string
// Lazy is true when the image is mounted on demand rather than pulled
// whole. Callers record it on the run so a slow start can be explained.
Lazy bool
}
PullMode is how images will be fetched: which snapshotter to ask containerd for, and whether that snapshotter fetches lazily.
func SelectPullMode ¶
SelectPullMode picks the snapshotter to pull with. It enables lazy pull when the daemon actually has the stargz snapshotter, and otherwise falls back to a full pull with a WARNING — the fallback is silent-by-nature otherwise, and a silent fallback presents as "the pipeline got slower for no reason", with nothing anywhere to read. The warning names what is missing so an operator can install it.
Anything short of a confirmed stargz snapshotter is a fallback, including a daemon that could not be asked: assuming lazy capability from an error would have containerd fail the pull with an unknown snapshotter instead.
type SnapshotterLister ¶
SnapshotterLister reports the snapshotters a containerd daemon has plugged in. It is a function rather than a client so this decision can be made — and tested — without a daemon, which matters because the daemon is exactly what is unavailable in some environments.
Source Files