Help us shape the future of Go! Take the 2026 Go Developer Survey

container

package
v0.28.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 29, 2026 License: BSD-3-Clause Imports: 26 Imported by: 0

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

View Source
const (
	HealthNone      = "none"
	HealthStarting  = "starting"
	HealthHealthy   = "healthy"
	HealthUnhealthy = "unhealthy"
)

Health statuses.

View Source
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).

View Source
const (
	Stdout byte = 1
	Stderr byte = 2
)

Stream numbers, as in the Docker multiplexed stream format.

View Source
const (
	RestartFirstDelay = 100 * time.Millisecond
	RestartMaxDelay   = time.Minute
	RestartReset      = 10 * time.Second
	// MaxRetryCount bounds on-failure:N.
	MaxRetryCount = 1 << 20
)

Delays between automatic restarts.

View Source
const MaxAttachments = 8

MaxAttachments bounds the networks one container joins (each datagram socket it opens costs a reader per network: see netdriver.Multi).

View Source
const MaxExecs = 256

MaxExecs bounds the exec instances kept per manager; the oldest ended ones go first.

View Source
const MaxLine = 4096

MaxLine bounds a line being edited.

View Source
const NoNetwork = "none"

NoNetwork is the network that is none.

Variables

View Source
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.

View Source
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.

View Source
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

func DNSName(name, id string) string

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

func DecodeRecord(v []byte) (*record, error)

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

func ValidNetworkName(s string) bool

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:"-"`
	// 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

func (cfg Config) PrimaryNetwork() string

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

func (c *Container) Attach(ctx context.Context, logs bool, fn func(Record) error) error

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) FS

func (c *Container) FS() *rootfs.FS

FS returns the container's root filesystem.

func (*Container) ID

func (c *Container) ID() string

ID returns the container's ID.

func (*Container) Logs

func (c *Container) Logs(ctx context.Context, follow bool, fn func(Record) error) error

Logs streams the container's output to fn: everything kept so far and, with follow, everything written until the container stops running.

func (*Container) Snapshot

func (c *Container) Snapshot() Snapshot

Snapshot returns the container's current state.

func (*Container) Stats added in v0.7.0

func (c *Container) Stats() Stats

Stats measures the container now.

func (*Container) Wait

func (c *Container) Wait(ctx context.Context, cond WaitCondition) (int, error)

Wait blocks until the condition holds and returns the exit code.

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.

func (*Exec) Done added in v0.20.0

func (x *Exec) Done() <-chan struct{}

Done is closed when the instance has ended (or failed to start).

func (*Exec) Info added in v0.20.0

func (x *Exec) Info() ExecInfo

Info is the instance's state.

func (*Exec) Kill added in v0.20.0

func (x *Exec) Kill()

Kill stops a running instance.

func (*Exec) Resize added in v0.20.0

func (x *Exec) Resize(h, w uint16) error

Resize changes the terminal size of a running exec -t.

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

type ExecIO struct {
	Stdin          io.Reader
	Stdout, Stderr io.Writer
}

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

type HealthResult struct {
	Start, End time.Time
	ExitCode   int
	Output     string
}

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

func NewManager(opt Options) *Manager

NewManager returns a manager running modules on opt.Executor.

func (*Manager) AutoStart added in v0.25.0

func (m *Manager) AutoStart(ctx context.Context) []error

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

func (m *Manager) Connect(ctx context.Context, ref string, a Attachment) error

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

func (m *Manager) DefaultMemoryLimit() int64

DefaultMemoryLimit is the memory limit of containers that set none.

func (*Manager) Disconnect added in v0.14.0

func (m *Manager) Disconnect(ref, network string) error

Disconnect takes a container off a network (network disconnect); a container taken off its last network has none.

func (*Manager) Flush added in v0.4.0

func (m *Manager) Flush(ctx context.Context) error

Flush waits until every change made so far is stored.

func (*Manager) Get

func (m *Manager) Get(ref string) (*Container, error)

Get finds a container by full ID, name, or unique ID prefix.

func (*Manager) GetExec added in v0.20.0

func (m *Manager) GetExec(id string) (*Exec, error)

GetExec finds an instance by its full ID or a unique prefix.

func (*Manager) Kill

func (m *Manager) Kill(ref string) error

Kill ends a running container.

func (*Manager) List

func (m *Manager) List(all bool) []Snapshot

List returns containers, newest first; all includes stopped ones.

func (*Manager) Logs

func (m *Manager) Logs(ctx context.Context, ref string, follow bool, fn func(Record) error) error

Logs streams a container's output; see Container.Logs.

func (*Manager) PersistError added in v0.4.0

func (m *Manager) PersistError() error

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

func (m *Manager) Prune() ([]string, int64)

Prune removes every container that is not running and returns their IDs and the bytes their writable layers held.

func (*Manager) Remove

func (m *Manager) Remove(ctx context.Context, ref string, force bool) error

Remove deletes a container; a running one only with force, which kills it.

func (*Manager) Restart added in v0.5.0

func (m *Manager) Restart(ctx context.Context, ref string) error

Restart stops the container if it runs, then starts it.

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) Shutdown

func (m *Manager) Shutdown(ctx context.Context)

Shutdown kills every running container and waits for them.

func (*Manager) Start

func (m *Manager) Start(ctx context.Context, ref string) error

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

func (m *Manager) StartExec(ctx context.Context, x *Exec, sio ExecIO) error

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

func (m *Manager) Stop(ctx context.Context, ref string) error

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

func (m *Manager) Touched(c *Container)

Touched stores c after a change made from outside it (an archive extracted into its files).

func (*Manager) UsesImage

func (m *Manager) UsesImage(imageID string) []string

UsesImage reports whether any container was created from imageID.

func (*Manager) UsesNetwork added in v0.10.0

func (m *Manager) UsesNetwork(name string) bool

UsesNetwork reports whether a container, in any state, joins a network.

func (*Manager) UsesVolume added in v0.8.0

func (m *Manager) UsesVolume(name string) []string

UsesVolume lists the containers, in any state, that mount a volume.

func (*Manager) Wait

func (m *Manager) Wait(ctx context.Context, ref string, cond WaitCondition) (int, error)

Wait blocks until the condition holds and returns the exit code.

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 Record

type Record struct {
	Stream byte
	Data   []byte
	Time   time.Time
}

Record is one write of a container to stdout or stderr.

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 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
}

Snapshot is a consistent copy of a container's state.

func (Snapshot) Command

func (s Snapshot) Command() []string

Command is argv as configured.

type State

type State string

State is a container's lifecycle state.

const (
	Created State = "created"
	Running State = "running"
	Exited  State = "exited"
)
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"
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL