container

Documentation

Overview

Package container creates and manipulates containers.

Index

• func List(rootDir string) ([]string, error)
• func Run(conf *boot.Config, args Args) (syscall.WaitStatus, error)
• type Args
• type Container
  • func Load(rootDir, partialID string) (*Container, error)
  • func New(conf *boot.Config, args Args) (*Container, error)
  • func (c *Container) Checkpoint(f *os.File) error
  • func (c *Container) Destroy() error
  • func (c *Container) Event() (*boot.Event, error)
  • func (c *Container) Execute(args *control.ExecArgs) (int32, error)
  • func (c *Container) ForwardSignals(pid int32, fgProcess bool) func()
  • func (c *Container) Pause() error
  • func (c *Container) Processes() ([]*control.Process, error)
  • func (c *Container) Restore(spec *specs.Spec, conf *boot.Config, restoreFile string) error
  • func (c *Container) Resume() error
  • func (c *Container) SandboxPid() int
  • func (c *Container) SignalContainer(sig syscall.Signal, all bool) error
  • func (c *Container) SignalProcess(sig syscall.Signal, pid int32) error
  • func (c *Container) Start(conf *boot.Config) error
  • func (c *Container) State() specs.State
  • func (c *Container) Wait() (syscall.WaitStatus, error)
  • func (c *Container) WaitPID(pid int32) (syscall.WaitStatus, error)
  • func (c *Container) WaitRootPID(pid int32) (syscall.WaitStatus, error)
• type StateFile
• type Status
  • func (s Status) String() string

Functions

func List

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

List returns all container ids in the given root directory.

func Run

func Run(conf *boot.Config, args Args) (syscall.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"`

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

func Load

func Load(rootDir, partialID string) (*Container, error)

Load loads a container with the given id from a metadata file. partialID may be an abbreviation of the full container id, in which case Load loads the container to which id unambiguously refers to. Returns ErrNotExist if container doesn't exist.

func New

func New(conf *boot.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) 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.Event, error)

Event returns events for the container.

func (*Container) Execute

func (c *Container) Execute(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) 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) Restore

func (c *Container) Restore(spec *specs.Spec, conf *boot.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 syscall.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 syscall.Signal, pid int32) error

SignalProcess sends sig to a specific process in the container.

func (*Container) Start

func (c *Container) Start(conf *boot.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) Wait

func (c *Container) Wait() (syscall.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) (syscall.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) (syscall.WaitStatus, error)

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

type StateFile

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

	// ID is the container ID.
	ID string `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}/${s.ID}.lock". The state file is located at: "${s.RootDir}/${s.ID}.state".

type Status

type Status int

Status enumerates container statuses. The statuses and their semantics are part of the runtime CLI spec.

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

	// Creating indicates "the container is being created".
	Creating

	// Paused indicates that the process within the container has been
	// suspended.
	Paused

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

	// Stopped indicates "the container process has exited".
	Stopped
)

func (Status) String

func (s Status) String() string

String converts a Status to a string. These strings are part of the runtime CLI spec and should not be changed.