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 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) 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) Snapshot() Snapshot
- func (c *Container) Stats() Stats
- func (c *Container) Wait(ctx context.Context, cond WaitCondition) (int, error)
- type CreateOptions
- type Logs
- type Manager
- func (m *Manager) Connect(ctx context.Context, ref string, a Attachment) error
- func (m *Manager) Create(o CreateOptions) (*Container, 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) 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) 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 RestoreReport
- type Snapshot
- type State
- type Stats
- type WaitCondition
Constants ¶
const ( Stdout byte = 1 Stderr byte = 2 )
Stream numbers, as in the Docker multiplexed stream format.
const MaxAttachments = 8
MaxAttachments bounds the networks one container joins (each datagram socket it opens costs a reader per network: see netdriver.Multi).
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.
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 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:"-"`
}
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) Logs ¶
Logs streams the container's output to fn: everything kept so far and, with follow, everything written until the container stops running.
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 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) 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) 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) 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) 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)
}
Options configures a Manager.
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 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
}
Snapshot is a consistent copy of a container's state.
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" )