container

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
• type Config
• type Container
  • 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) Wait(ctx context.Context, cond WaitCondition) (int, error)
• type CreateOptions
• type Logs
• type Manager
  • func NewManager(opt Options) *Manager
  • func (m *Manager) Create(o CreateOptions) (*Container, 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) Remove(ctx context.Context, ref string, force bool) error
  • func (m *Manager) Shutdown(ctx context.Context)
  • func (m *Manager) Start(ctx context.Context, ref string) error
  • func (m *Manager) UsesImage(imageID string) []string
  • func (m *Manager) Wait(ctx context.Context, ref string, cond WaitCondition) (int, error)
• type Options
• type Record
• type Snapshot
  • func (s Snapshot) Command() []string
• type State
• type WaitCondition

Constants

const (
	Stdout byte = 1
	Stderr byte = 2
)

Stream numbers, as in the Docker multiplexed stream format.

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.

Types

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

Config is how a container runs, resolved from the image config and the run overrides.

type Container

type Container struct {
	// contains filtered or unexported fields
}

Container is one container. Read it through Snapshot.

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

func (m *Manager) Create(o CreateOptions) (*Container, error)

Create makes a container in the created state.

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

func (*Manager) UsesImage

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

UsesImage reports whether any container was created from imageID.

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

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

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

type WaitCondition

type WaitCondition string

WaitCondition is a /containers/{id}/wait condition.

const (
	WaitNotRunning WaitCondition = "not-running"
	WaitNextExit   WaitCondition = "next-exit"
	WaitRemoved    WaitCondition = "removed"
)