Documentation
¶
Overview ¶
Package container is the container lifecycle: created, running, exited; its root filesystem, its logs, its exit code. It runs modules through a runtime.Executor and knows nothing of images beyond the frozen lower filesystem and the run configuration it is handed.
Index ¶
- Constants
- Variables
- func DNSName(name, id string) string
- func DecodeRecord(v []byte) (*record, error)
- func ParseDetachKeys(s string) ([]byte, error)
- func ValidNetworkName(s string) bool
- type Attachment
- type Config
- type Container
- func (c *Container) Attach(ctx context.Context, logs bool, fn func(Record) error) error
- func (c *Container) AttachStdin(ctx context.Context, in io.Reader, detachKeys []byte) error
- func (c *Container) FS() *rootfs.FS
- func (c *Container) ID() string
- func (c *Container) Logs(ctx context.Context, follow bool, fn func(Record) error) error
- func (c *Container) Resize(h, w uint16) error
- func (c *Container) Snapshot() Snapshot
- func (c *Container) Stats() Stats
- func (c *Container) Wait(ctx context.Context, cond WaitCondition) (int, error)
- type CreateOptions
- type Exec
- type ExecConfig
- type ExecIO
- type ExecInfo
- type Health
- type HealthConfig
- type HealthResult
- type Logs
- type Manager
- func (m *Manager) AutoStart(ctx context.Context) []error
- func (m *Manager) Connect(ctx context.Context, ref string, a Attachment) error
- func (m *Manager) Create(o CreateOptions) (*Container, error)
- func (m *Manager) CreateExec(ref string, cfg ExecConfig) (*Exec, error)
- func (m *Manager) DefaultMemoryLimit() int64
- func (m *Manager) Disconnect(ref, network string) error
- func (m *Manager) Flush(ctx context.Context) error
- func (m *Manager) Get(ref string) (*Container, error)
- func (m *Manager) GetExec(id string) (*Exec, error)
- func (m *Manager) Kill(ref string) error
- func (m *Manager) List(all bool) []Snapshot
- func (m *Manager) Logs(ctx context.Context, ref string, follow bool, fn func(Record) error) error
- func (m *Manager) PersistError() error
- func (m *Manager) Prune() ([]string, int64)
- func (m *Manager) Remove(ctx context.Context, ref string, force bool) error
- func (m *Manager) Restart(ctx context.Context, ref string) error
- func (m *Manager) Restore(lower func(imageID string) (*rootfs.FS, error), lim rootfs.Limits) (RestoreReport, error)
- func (m *Manager) Shutdown(ctx context.Context)
- func (m *Manager) Start(ctx context.Context, ref string) error
- func (m *Manager) StartExec(ctx context.Context, x *Exec, sio ExecIO) error
- func (m *Manager) Stop(ctx context.Context, ref string) error
- func (m *Manager) Touched(c *Container)
- func (m *Manager) UsesImage(imageID string) []string
- func (m *Manager) UsesNetwork(name string) bool
- func (m *Manager) UsesVolume(name string) []string
- func (m *Manager) Wait(ctx context.Context, ref string, cond WaitCondition) (int, error)
- type Mount
- type NetworkInfo
- type Options
- type Record
- type RestartPolicy
- type RestoreReport
- type Sanction
- type Snapshot
- type State
- type Stats
- type WaitCondition
Constants ¶
const ( HealthNone = "none" HealthStarting = "starting" HealthHealthy = "healthy" HealthUnhealthy = "unhealthy" )
Health statuses.
const ( DefaultHealthInterval = 30 * time.Second DefaultHealthTimeout = 30 * time.Second DefaultHealthStartInterval = 5 * time.Second DefaultHealthRetries = 3 MinHealthInterval = 100 * time.Millisecond MaxHealthRetries = 1 << 16 HealthLogSize = 5 HealthOutputBytes = 4096 )
Defaults and bounds of a health check (Docker's defaults; the minimum interval is this engine's: each probe is a process to compile and run).
const ( Stdout byte = 1 Stderr byte = 2 )
Stream numbers, as in the Docker multiplexed stream format.
const ( RestartFirstDelay = 100 * time.Millisecond RestartMaxDelay = time.Minute RestartReset = 10 * time.Second // MaxRetryCount bounds on-failure:N. MaxRetryCount = 1 << 20 )
Delays between automatic restarts.
const DefaultDetachKeys = "ctrl-p,ctrl-q"
DefaultDetachKeys are Docker's: Ctrl-P Ctrl-Q.
const MaxAttachments = 8
MaxAttachments bounds the networks one container joins (each datagram socket it opens costs a reader per network: see netdriver.Multi).
const MaxExecs = 256
MaxExecs bounds the exec instances kept per manager; the oldest ended ones go first.
const MaxLine = 4096
MaxLine bounds a line being edited.
const NoNetwork = "none"
NoNetwork is the network that is none.
Variables ¶
var ( ErrNotFound = errors.New("no such container") ErrNameConflict = errors.New("container name already in use") ErrRunning = errors.New("container is running") ErrNotRunning = errors.New("container is not running") ErrAlreadyStarted = errors.New("container already started") ErrInvalid = errors.New("invalid container configuration") ErrTooMany = errors.New("too many containers") ErrAmbiguous = errors.New("multiple containers match") )
Errors the API layer maps to HTTP statuses.
var ( ErrNoSuchExec = errors.New("no such exec instance") ErrExecStarted = errors.New("exec instance already started") ErrExecNotRunning = errors.New("exec instance is not running") )
Errors of exec.
var ( ErrNoStdin = errors.New("container has no stdin (create it with OpenStdin, run -i)") ErrNoTerminal = errors.New("container has no terminal (create it with Tty, run -t)") // ErrDetached ends an attach whose input carried the detach keys. ErrDetached = errors.New("detached") )
Errors of attach and resize.
var ErrNoPublish = errors.New("this engine cannot publish ports")
ErrNoPublish is a container that asks for published ports from an engine that has nowhere to listen.
Functions ¶
func DNSName ¶ added in v0.10.0
DNSName is the name a container is reachable by on its network: its name when that is a DNS label, its short ID otherwise.
func DecodeRecord ¶ added in v0.4.0
DecodeRecord reads a stored container record; it is exported for the fuzzer and for tools that inspect a data root.
func ParseDetachKeys ¶ added in v0.30.0
ParseDetachKeys reads a detach sequence as Docker does (moby/term ToBytes): comma-separated keys, each one character or ctrl-@, ctrl-a … ctrl-z, ctrl-[, ctrl-\, ctrl-], ctrl-^, ctrl-_. "" is the default; at most 16 keys.
func ValidNetworkName ¶ added in v0.10.0
ValidNetworkName reports a network name Docker would accept.
Types ¶
type Attachment ¶ added in v0.14.0
type Attachment struct {
// Network is the network's name; "" is the engine's default.
Network string `json:"network"`
Aliases []string `json:"aliases,omitempty"`
}
Attachment is a network a container joins and the extra names it answers to there (run --network-alias, network connect --alias).
type Config ¶
type Config struct {
Image string `json:"Image"`
ImageID string `json:"-"`
Entrypoint []string `json:"Entrypoint"`
Cmd []string `json:"Cmd"`
Env []string `json:"Env"`
WorkingDir string `json:"WorkingDir"`
Labels map[string]string `json:"Labels"`
// MemoryLimitBytes bounds linear memory (0 = manager default).
MemoryLimitBytes int64 `json:"-"`
// AutoRemove removes the container when it exits (run --rm).
AutoRemove bool `json:"-"`
// Mounts are the volumes it mounts (run -v NAME:/path[:ro]).
Mounts []Mount `json:"-"`
// Networks are the networks it joins (run --network and
// --network-alias, network connect), the first one its primary: empty
// for the engine's default, [{none}] for no network.
Networks []Attachment `json:"-"`
// Caps are device capabilities granted to it (run --gpu: "gpu").
Caps []string `json:"-"`
// Ports are its exposed ports and their host bindings (run -p,
// --expose, the image's ExposedPorts); PublishAll gives each exposed
// port without a binding one the system picks (run -P).
Ports portmap.Map `json:"-"`
PublishAll bool `json:"-"`
// Restart is its restart policy (run --restart; see restart.go).
Restart RestartPolicy `json:"-"`
// Tty gives its first process a terminal (run -t); OpenStdin a stdin
// that attached clients write into (run -i); StdinOnce closes that
// stdin when the first attached client's input ends (stdio.go).
// ConsoleSize is the terminal's first size, height then width (0, 0:
// 80x24).
Tty bool `json:"-"`
OpenStdin bool `json:"-"`
StdinOnce bool `json:"-"`
ConsoleSize [2]uint16 `json:"-"`
// Healthcheck is its health check (the image's, or run --health-*;
// see health.go); nil or NONE for none.
Healthcheck *HealthConfig `json:"-"`
}
Config is how a container runs, resolved from the image config and the run overrides.
func (Config) PrimaryNetwork ¶ added in v0.14.0
PrimaryNetwork is the first network the container joins ("" = the engine's default, NoNetwork = none).
type Container ¶
type Container struct {
// contains filtered or unexported fields
}
Container is one container. Read it through Snapshot.
func (*Container) Attach ¶ added in v0.5.0
Attach streams to fn what the container writes from now on (with logs, what it wrote before too) until its next exit — of the run in progress, or of the next start when it is not running — or its removal.
func (*Container) AttachStdin ¶ added in v0.30.0
AttachStdin copies in to the container's running process until in ends, the process ends, ctx is done, or in carries the detach keys (then it returns ErrDetached). With StdinOnce, the end of in closes the process's stdin, as the first attached client's hang-up does in Docker.
func (*Container) Logs ¶
Logs streams the container's output to fn: everything kept so far and, with follow, everything written until the container stops running.
func (*Container) Resize ¶ added in v0.30.0
Resize sets the size of the container's terminal (run -t) while it runs.
type CreateOptions ¶
type CreateOptions struct {
Name string
Config Config
// Lower is the image's frozen root filesystem.
Lower *rootfs.FS
}
CreateOptions describes a new container.
type Exec ¶ added in v0.20.0
type Exec struct {
ID string
ContainerID string
Config ExecConfig
// contains filtered or unexported fields
}
Exec is one exec instance.
type ExecConfig ¶ added in v0.20.0
type ExecConfig struct {
Cmd []string
Env []string
WorkingDir string
// User must be empty, "root" or "0": a WebAssembly container has no
// users.
User string
Tty bool
AttachStdin, AttachStdout, AttachStderr bool
// ConsoleSize is the initial terminal size, height then width (0, 0:
// 80x24).
ConsoleSize [2]uint16
}
ExecConfig is an exec instance as created.
type ExecIO ¶ added in v0.20.0
ExecIO is where a started instance reads and writes. With a terminal, Stderr is not used: the terminal carries both outputs, as Docker does.
type ExecInfo ¶ added in v0.20.0
type ExecInfo struct {
ID, ContainerID string
Config ExecConfig
Running bool
ExitCode int
// Started reports whether a start was asked; Ended, that it has
// ended (or failed to start): ExitCode is meaningful then.
Started, Ended bool
Pid uint32
}
ExecInfo is an instance's state (GET /exec/{id}/json).
type Health ¶ added in v0.28.0
type Health struct {
Status string
FailingStreak int
Log []HealthResult
}
Health is a container's health state (inspect's State.Health).
type HealthConfig ¶ added in v0.28.0
type HealthConfig struct {
Test []string `json:"test,omitempty"`
Interval time.Duration `json:"interval,omitempty"`
Timeout time.Duration `json:"timeout,omitempty"`
StartPeriod time.Duration `json:"startPeriod,omitempty"`
StartInterval time.Duration `json:"startInterval,omitempty"`
Retries int `json:"retries,omitempty"`
}
HealthConfig is a container's health check.
func (*HealthConfig) Enabled ¶ added in v0.28.0
func (h *HealthConfig) Enabled() bool
Enabled reports a check that runs (a test other than NONE).
type HealthResult ¶ added in v0.28.0
HealthResult is one probe.
type Logs ¶
type Logs struct {
// contains filtered or unexported fields
}
Logs is a container's bounded, append-only output. When it exceeds its byte bound the oldest records are dropped, so a chatty container cannot exhaust the daemon's memory.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager owns every container of a daemon.
func NewManager ¶
NewManager returns a manager running modules on opt.Executor.
func (*Manager) AutoStart ¶ added in v0.25.0
AutoStart starts, when the engine starts, the containers whose policy says so: always, and unless-stopped unless a user had stopped it.
func (*Manager) Connect ¶ added in v0.14.0
Connect puts a container on another network (network connect). A running container is attached at once: its open listeners listen there too. Connecting it again to a network it is on replaces its aliases there only when it is not running (as Docker refuses it otherwise).
func (*Manager) Create ¶
func (m *Manager) Create(o CreateOptions) (*Container, error)
Create makes a container in the created state.
func (*Manager) CreateExec ¶ added in v0.20.0
func (m *Manager) CreateExec(ref string, cfg ExecConfig) (*Exec, error)
CreateExec prepares cmd to run in container ref, which must be running.
func (*Manager) DefaultMemoryLimit ¶ added in v0.7.0
DefaultMemoryLimit is the memory limit of containers that set none.
func (*Manager) Disconnect ¶ added in v0.14.0
Disconnect takes a container off a network (network disconnect); a container taken off its last network has none.
func (*Manager) GetExec ¶ added in v0.20.0
GetExec finds an instance by its full ID or a unique prefix.
func (*Manager) PersistError ¶ added in v0.4.0
PersistError is the last checkpoint's failure, nil when the store holds every container's latest state.
func (*Manager) Prune ¶ added in v0.4.0
Prune removes every container that is not running and returns their IDs and the bytes their writable layers held.
func (*Manager) Restore ¶ added in v0.4.0
func (m *Manager) Restore(lower func(imageID string) (*rootfs.FS, error), lim rootfs.Limits) (RestoreReport, error)
Restore loads every stored container. lower returns the frozen root filesystem of an image by ID; lim bounds reading a stored writable layer. A record that fails its seal or its checks is deleted and reported; a blob that does, is dropped (the container keeps its configuration and loses its logs or its writes), and so is a container whose image is gone.
func (*Manager) Start ¶
Start runs a created or exited container (a user's start: its restart policy acts again, counting from zero).
func (*Manager) StartExec ¶ added in v0.20.0
StartExec runs instance x. ctx bounds the run: cancelling it kills the process (an attached client that hangs up), so a detached start passes a context that is never cancelled.
func (*Manager) Stop ¶ added in v0.5.0
Stop ends a running container and waits until it has exited. A wasm guest has no signal to catch, so there is no grace period: stopping is killing (docker stop's SIGKILL after the timeout, at once).
func (*Manager) Touched ¶ added in v0.12.0
Touched stores c after a change made from outside it (an archive extracted into its files).
func (*Manager) UsesNetwork ¶ added in v0.10.0
UsesNetwork reports whether a container, in any state, joins a network.
func (*Manager) UsesVolume ¶ added in v0.8.0
UsesVolume lists the containers, in any state, that mount a volume.
type Mount ¶ added in v0.8.0
type Mount struct {
Volume string `json:"volume"`
Target string `json:"target"`
ReadOnly bool `json:"readOnly,omitempty"`
}
Mount is a volume mounted at Target.
type NetworkInfo ¶ added in v0.14.0
type NetworkInfo struct {
Network string
Aliases []string
// IPAddress is its address there while it runs.
IPAddress netip.Addr
}
NetworkInfo is a container's place on one network, as inspect shows it.
type Options ¶
type Options struct {
Executor runtime.Executor
// MemoryLimitBytes is the default linear-memory bound per container.
MemoryLimitBytes int64
// Timeout is the wall-clock bound of one run (0 = none).
Timeout time.Duration
// Quota bounds what one container may write to its filesystem.
Quota rootfs.Quota
// MaxLogBytes bounds one container's kept output (default 8 MiB).
MaxLogBytes int
// MaxContainers bounds how many containers exist (default 256).
MaxContainers int
// Store, when set, keeps containers across restarts: their state,
// logs and writable layers (see Restore).
Store state.Store
// CheckpointEvery is how often a running container's changes are
// stored (default 2s; negative: only at state changes).
CheckpointEvery time.Duration
// Events, when set, receives create, start, die, kill, stop, restart,
// destroy and prune, with Docker's attributes (image, name, labels,
// exitCode).
Events *events.Bus
// Volume finds a volume's tree by name, for Config.Mounts.
Volume func(name string) (*rootfs.FS, error)
// Network attaches a container to one of Config.Networks under its DNS
// name and aliases; nil means containers have no network.
Network func(ctx context.Context, network, name string, aliases []string) (netdriver.Endpoint, error)
// Ports is where published ports listen (wctrd: portmap.OS); nil
// means this engine cannot publish them, and a container that asks
// is refused at start.
Ports portmap.Host
// PortLimits bound each published port (zero: portmap.DefaultLimits).
PortLimits portmap.Limits
}
Options configures a Manager.
type RestartPolicy ¶ added in v0.25.0
type RestartPolicy struct {
Name string `json:"name,omitempty"`
MaximumRetryCount int `json:"maximumRetryCount,omitempty"`
}
RestartPolicy is a container's restart policy.
func ParseRestartPolicy ¶ added in v0.25.0
func ParseRestartPolicy(s string) (RestartPolicy, error)
ParseRestartPolicy reads run --restart: no, always, unless-stopped, on-failure or on-failure:N.
func (RestartPolicy) None ¶ added in v0.25.0
func (p RestartPolicy) None() bool
None reports a policy that never restarts.
type RestoreReport ¶ added in v0.4.0
type RestoreReport struct {
// Restored containers, of which Stopped were running when the engine
// stopped and are now exited with status 137.
Restored, Stopped int
// Removed are --rm containers that had run, removed as they would
// have been.
Removed []string
// Repaired describes what was found corrupted and dropped.
Repaired []string
}
RestoreReport says what Restore did.
type Sanction ¶ added in v0.34.0
Sanction is what a host module reported with wasi.Proc.Emit with the action "sanction": the module, when, and its attributes (for the GPU: the submit's measured time and the budget it overran).
type Snapshot ¶
type Snapshot struct {
ID string
Name string
Created time.Time
Config Config
State State
ExitCode int
Error string
TimedOut bool
StartedAt time.Time
FinishedAt time.Time
// Path is the resolved module path (empty until the first start).
Path string
// SizeRw is the bytes the container wrote to its filesystem.
SizeRw int64
// IPAddress is its address on its primary network while it runs.
IPAddress netip.Addr
// Networks are its networks, with their addresses while it runs.
Networks []NetworkInfo
// Ports are the published ports while it runs, as bound (a picked
// host port as picked); nil otherwise.
Ports portmap.Map
// RestartCount is how many times its policy restarted it since a user
// last started it.
RestartCount int
// Health is its health state, nil without a check.
Health *Health
// Sanction is the last sanction a host module applied to it (a GPU
// overrun), nil if none.
Sanction *Sanction
}
Snapshot is a consistent copy of a container's state.
type State ¶
type State string
State is a container's lifecycle state.
const Restarting State = "restarting"
Restarting is the state of a container waiting for its automatic restart.
type Stats ¶ added in v0.7.0
type Stats struct {
Read time.Time
Running bool
// MemoryBytes is the guest's linear memory (0 when not running);
// MemoryLimitBytes the most it may grow to.
MemoryBytes, MemoryLimitBytes int64
// WrittenBytes is everything written to its filesystem, ever;
// SizeRw what its writable layer holds now.
WrittenBytes, SizeRw int64
// LogBytes is the output kept.
LogBytes int64
}
Stats is what a container uses now. CPU time is not in it: a wasm guest gives the engine no CPU accounting (its wall-clock time includes the time it waits on the host), and an estimate would be a guess.
type WaitCondition ¶
type WaitCondition string
WaitCondition is a /containers/{id}/wait condition.
const ( WaitNotRunning WaitCondition = "not-running" WaitNextExit WaitCondition = "next-exit" WaitRemoved WaitCondition = "removed" )