container

Documentation

Overview

Package container creates and manipulates containers.

Index

• Constants
• func Run(conf *config.Config, args Args) (unix.WaitStatus, error)
• type Args
• type Container
  • func Load(rootDir string, id FullID, opts LoadOpts) (*Container, error)
  • func New(conf *config.Config, args Args) (*Container, error)
  • func (c *Container) Cat(files []string, out *os.File) error
  • func (c *Container) Checkpoint(f *os.File) error
  • func (c *Container) Destroy() error
  • func (c *Container) Event() (*boot.EventOut, error)
  • func (c *Container) Execute(conf *config.Config, args *control.ExecArgs) (int32, error)
  • func (c *Container) ForwardSignals(pid int32, fgProcess bool) func()
  • func (c *Container) IsSandboxRunning() bool
  • func (c *Container) Pause() error
  • func (c *Container) Processes() ([]*control.Process, error)
  • func (c *Container) Reduce(wait bool) error
  • func (c *Container) Restore(spec *specs.Spec, conf *config.Config, restoreFile string) error
  • func (c *Container) Resume() error
  • func (c *Container) SandboxPid() int
  • func (c *Container) SignalContainer(sig unix.Signal, all bool) error
  • func (c *Container) SignalProcess(sig unix.Signal, pid int32) error
  • func (c *Container) Start(conf *config.Config) error
  • func (c *Container) State() specs.State
  • func (c *Container) Stream(filters []string, out *os.File) error
  • func (c *Container) Usage(full bool) (control.MemoryUsage, error)
  • func (c *Container) UsageFD() (*control.MemoryUsageRecord, error)
  • func (c *Container) Wait() (unix.WaitStatus, error)
  • func (c *Container) WaitPID(pid int32) (unix.WaitStatus, error)
  • func (c *Container) WaitRootPID(pid int32) (unix.WaitStatus, error)
• type FullID
  • func List(rootDir string) ([]FullID, error)
  • func (f *FullID) String() string
• type LoadOpts
• type StateFile
• type Status

Constants

const (
	// Created indicates "the runtime has finished the create operation and
	// the container process has neither exited nor executed the
	// user-specified program"
	Created = specs.StateCreated

	// Creating indicates "the container is being created".
	Creating = specs.StateCreating

	// Running indicates "the container process has executed the
	// user-specified program but has not exited".
	Running = specs.StateRunning

	// Stopped indicates "the container process has exited".
	Stopped = specs.StateStopped

	// Paused indicates that the process within the container has been
	// suspended. This is a local status, not part of the spec.
	Paused = Status("paused")
)

Functions

func Run

func Run(conf *config.Config, args Args) (unix.WaitStatus, error)

Run is a helper that calls Create + Start + Wait.

Types

type Args

type Args struct {
	// ID is the container unique identifier.
	ID string

	// Spec is the OCI spec that describes the container.
	Spec *specs.Spec

	// BundleDir is the directory containing the container bundle.
	BundleDir string

	// ConsoleSocket is the path to a unix domain socket that will receive
	// the console FD. It may be empty.
	ConsoleSocket string

	// PIDFile is the filename where the container's root process PID will be
	// written to. It may be empty.
	PIDFile string

	// UserLog is the filename to send user-visible logs to. It may be empty.
	//
	// It only applies for the init container.
	UserLog string

	// Attached indicates that the sandbox lifecycle is attached with the caller.
	// If the caller exits, the sandbox should exit too.
	//
	// It only applies for the init container.
	Attached bool
}

Args is used to configure a new container.

type Container

type Container struct {
	// ID is the container ID.
	ID string `json:"id"`

	// Spec is the OCI runtime spec that configures this container.
	Spec *specs.Spec `json:"spec"`

	// BundleDir is the directory containing the container bundle.
	BundleDir string `json:"bundleDir"`

	// CreatedAt is the time the container was created.
	CreatedAt time.Time `json:"createdAt"`

	// Owner is the container owner.
	Owner string `json:"owner"`

	// ConsoleSocket is the path to a unix domain socket that will receive
	// the console FD.
	ConsoleSocket string `json:"consoleSocket"`

	// Status is the current container Status.
	Status Status `json:"status"`

	// GoferPid is the PID of the gofer running along side the sandbox. May
	// be 0 if the gofer has been killed.
	GoferPid int `json:"goferPid"`

	// Sandbox is the sandbox this container is running in. It's set when the
	// container is created and reset when the sandbox is destroyed.
	Sandbox *sandbox.Sandbox `json:"sandbox"`

	// CompatCgroup has the cgroup configuration for the container. For the single
	// container case, container cgroup is set in `c.Sandbox` only. CompactCgroup
	// is only set for multi-container, where the `c.Sandbox` cgroup represents
	// the entire pod.
	//
	// Note that CompatCgroup is created only for compatibility with tools
	// that expect container cgroups to exist. Setting limits here makes no change
	// to the container in question.
	CompatCgroup cgroup.CgroupJSON `json:"compatCgroup"`

	// Saver handles load from/save to the state file safely from multiple
	// processes.
	Saver StateFile `json:"saver"`
	// contains filtered or unexported fields
}

Container represents a containerized application. When running, the container is associated with a single Sandbox.

Container metadata can be saved and loaded to disk. Within a root directory, we maintain subdirectories for each container named with the container id. The container metadata is stored as a json within the container directory in a file named "meta.json". This metadata format is defined by us and is not part of the OCI spec.

Containers must write their metadata files after any change to their internal states. The entire container directory is deleted when the container is destroyed.

When the container is stopped, all processes that belong to the container must be stopped before Destroy() returns. containerd makes roughly the following calls to stop a container:

• First it attempts to kill the container process with 'runsc kill SIGTERM'. After some time, it escalates to SIGKILL. In a separate thread, it's waiting on the container. As soon as the wait returns, it moves on to the next step:
• It calls 'runsc kill --all SIGKILL' to stop every process that belongs to the container. 'kill --all SIGKILL' waits for all processes before returning.
• Containerd waits for stdin, stdout and stderr to drain and be closed.
• It calls 'runsc delete'. runc implementation kills --all SIGKILL once again just to be sure, waits, and then proceeds with remaining teardown.

Container is thread-unsafe.

func Load

func Load(rootDir string, id FullID, opts LoadOpts) (*Container, error)

Load loads a container with the given id from a metadata file. "id" may be an abbreviation of the full container id in case LoadOpts.Exact if not set. It also checks if the container is still running, in order to return an error to the caller earlier. This check is skipped if LoadOpts.SkipCheck is set.

Returns ErrNotExist if no container is found. Returns error in case more than one containers matching the ID prefix is found.

func New

func New(conf *config.Config, args Args) (*Container, error)

New creates the container in a new Sandbox process, unless the metadata indicates that an existing Sandbox should be used. The caller must call Destroy() on the container.

func (*Container) Cat

func (c *Container) Cat(files []string, out *os.File) error

Cat prints out the content of the files.

func (*Container) Checkpoint

func (c *Container) Checkpoint(f *os.File) error

Checkpoint sends the checkpoint call to the container. The statefile will be written to f, the file at the specified image-path.

func (*Container) Destroy

func (c *Container) Destroy() error

Destroy stops all processes and frees all resources associated with the container.

func (*Container) Event

func (c *Container) Event() (*boot.EventOut, error)

Event returns events for the container.

func (*Container) Execute

func (c *Container) Execute(conf *config.Config, args *control.ExecArgs) (int32, error)

Execute runs the specified command in the container. It returns the PID of the newly created process.

func (*Container) ForwardSignals

func (c *Container) ForwardSignals(pid int32, fgProcess bool) func()

ForwardSignals forwards all signals received by the current process to the container process inside the sandbox. It returns a function that will stop forwarding signals.

func (*Container) IsSandboxRunning

func (c *Container) IsSandboxRunning() bool

IsSandboxRunning returns true if the sandbox exists and is running.

func (*Container) Pause

func (c *Container) Pause() error

Pause suspends the container and its kernel. The call only succeeds if the container's status is created or running.

func (*Container) Processes

func (c *Container) Processes() ([]*control.Process, error)

Processes retrieves the list of processes and associated metadata inside a container.

func (*Container) Reduce

func (c *Container) Reduce(wait bool) error

Reduce requests that the sentry attempt to reduce its memory usage.

func (*Container) Restore

func (c *Container) Restore(spec *specs.Spec, conf *config.Config, restoreFile string) error

Restore takes a container and replaces its kernel and file system to restore a container from its state file.

func (*Container) Resume

func (c *Container) Resume() error

Resume unpauses the container and its kernel. The call only succeeds if the container's status is paused.

func (*Container) SandboxPid

func (c *Container) SandboxPid() int

SandboxPid returns the Pid of the sandbox the container is running in, or -1 if the container is not running.

func (*Container) SignalContainer

func (c *Container) SignalContainer(sig unix.Signal, all bool) error

SignalContainer sends the signal to the container. If all is true and signal is SIGKILL, then waits for all processes to exit before returning. SignalContainer returns an error if the container is already stopped. TODO(b/113680494): Distinguish different error types.

func (*Container) SignalProcess

func (c *Container) SignalProcess(sig unix.Signal, pid int32) error

SignalProcess sends sig to a specific process in the container.

func (*Container) Start

func (c *Container) Start(conf *config.Config) error

Start starts running the containerized process inside the sandbox.

func (*Container) State

func (c *Container) State() specs.State

State returns the metadata of the container.

func (*Container) Stream

func (c *Container) Stream(filters []string, out *os.File) error

Stream dumps all events to out.

func (*Container) Usage

func (c *Container) Usage(full bool) (control.MemoryUsage, error)

Usage displays memory used by the application.

func (*Container) UsageFD

func (c *Container) UsageFD() (*control.MemoryUsageRecord, error)

UsageFD shows application memory usage using two donated FDs.

func (*Container) Wait

func (c *Container) Wait() (unix.WaitStatus, error)

Wait waits for the container to exit, and returns its WaitStatus. Call to wait on a stopped container is needed to retrieve the exit status and wait returns immediately.

func (*Container) WaitPID

func (c *Container) WaitPID(pid int32) (unix.WaitStatus, error)

WaitPID waits for process 'pid' in the container's PID namespace and returns its WaitStatus.

func (*Container) WaitRootPID

func (c *Container) WaitRootPID(pid int32) (unix.WaitStatus, error)

WaitRootPID waits for process 'pid' in the sandbox's PID namespace and returns its WaitStatus.

type FullID

type FullID struct {
	SandboxID   string `json:"sandboxId"`
	ContainerID string `json:"containerId"`
}

FullID combines sandbox and container ID to identify a container. Sandbox ID is used to allow all containers for a given sandbox to be loaded by matching sandbox ID in the file name.

func List

func List(rootDir string) ([]FullID, error)

List returns all container ids in the given root directory.

func (*FullID) String

func (f *FullID) String() string

type LoadOpts

type LoadOpts struct {
	// Exact tells whether the search should be exact. See Load() for more.
	Exact bool

	// SkipCheck tells Load() to skip checking if container is runnning.
	SkipCheck bool
}

LoadOpts provides options for Load()ing a container.

type StateFile

type StateFile struct {
	// RootDir is the directory containing the container metadata file.
	RootDir string `json:"rootDir"`

	// ID is the sandbox+container ID.
	ID FullID `json:"id"`
	// contains filtered or unexported fields
}

StateFile handles load from/save to container state safely from multiple processes. It uses a lock file to provide synchronization between operations.

The lock file is located at: "${s.RootDir}/${containerd-id}_sand:{sandbox-id}.lock". The state file is located at: "${s.RootDir}/${containerd-id}_sand:{sandbox-id}.state".

type Status

type Status = specs.ContainerState

Status is a local type alias.