runtime

Documentation

Index

• Constants
• Variables
• type Blkio
• type BlkioEntry
• type CPU
• type CPUUsage
• type Checkpoint
• type Container
  • func Load(root, id, shimName string, timeout time.Duration) (Container, error)
  • func New(opts ContainerOpts) (Container, error)
• type ContainerOpts
• type Hugetlb
• type Memory
• type MemoryEntry
• type OOM
• type Pids
• type PlatformProcessState
• type Process
• type ProcessState
• type Resource
• type Stat
• type State
• type Stdio
  • func NewStdio(stdin, stdout, stderr string) Stdio
• type Throttling

Constants

const (
	// ExitFile holds the name of the pipe used to monitor process
	// exit
	ExitFile = "exit"
	// ExitStatusFile holds the name of the file where the container
	// exit code is to be written
	ExitStatusFile = "exitStatus"
	// StateFile holds the name of the file where the container state
	// is written
	StateFile = "state.json"
	// ControlFile holds the name of the pipe used to control the shim
	ControlFile = "control"
	// InitProcessID holds the special ID used for the very first
	// container's process
	InitProcessID = "init"
	// StartTimeFile holds the name of the file in which the process
	// start time is saved
	StartTimeFile = "starttime"

	// UnknownStatus is the value returned when a process exit
	// status cannot be determined
	UnknownStatus = 255
)

const (
	Paused  = State("paused")
	Stopped = State("stopped")
	Running = State("running")
)

Possible container states

Variables

var (
	// ErrContainerExited is returned when access to an exited
	// container is attempted
	ErrContainerExited = errors.New("containerd: container has exited")
	// ErrProcessNotExited is returned when trying to retrieve the exit
	// status of an alive process
	ErrProcessNotExited = errors.New("containerd: process has not exited")
	// ErrContainerNotStarted is returned when a container fails to
	// start without error from the shim or the OCI runtime
	ErrContainerNotStarted = errors.New("containerd: container not started")
	// ErrContainerStartTimeout is returned if a container takes too
	// long to start
	ErrContainerStartTimeout = errors.New("containerd: container did not start before the specified timeout")
	// ErrShimExited is returned if the shim or the contianer's init process
	// exits before completing
	ErrShimExited = errors.New("containerd: shim exited before container process was started")
)

Types

type Blkio

type Blkio struct {
	IoServiceBytesRecursive []BlkioEntry `json:"ioServiceBytesRecursive,omitempty"`
	IoServicedRecursive     []BlkioEntry `json:"ioServicedRecursive,omitempty"`
	IoQueuedRecursive       []BlkioEntry `json:"ioQueueRecursive,omitempty"`
	IoServiceTimeRecursive  []BlkioEntry `json:"ioServiceTimeRecursive,omitempty"`
	IoWaitTimeRecursive     []BlkioEntry `json:"ioWaitTimeRecursive,omitempty"`
	IoMergedRecursive       []BlkioEntry `json:"ioMergedRecursive,omitempty"`
	IoTimeRecursive         []BlkioEntry `json:"ioTimeRecursive,omitempty"`
	SectorsRecursive        []BlkioEntry `json:"sectorsRecursive,omitempty"`
}

Blkio regroups all the Blkio related stats

type BlkioEntry

type BlkioEntry struct {
	Major uint64 `json:"major,omitempty"`
	Minor uint64 `json:"minor,omitempty"`
	Op    string `json:"op,omitempty"`
	Value uint64 `json:"value,omitempty"`
}

BlkioEntry represents a single record for a Blkio stat

type CPU

type CPU struct {
	Usage      CPUUsage   `json:"usage,omitempty"`
	Throttling Throttling `json:"throttling,omitempty"`
}

CPU regroups both a CPU usage and throttling information

type CPUUsage

type CPUUsage struct {
	// Units: nanoseconds.
	Total  uint64   `json:"total,omitempty"`
	Percpu []uint64 `json:"percpu,omitempty"`
	Kernel uint64   `json:"kernel"`
	User   uint64   `json:"user"`
}

CPUUsage holds information regarding cpu usage

type Checkpoint

type Checkpoint struct {
	// Timestamp is the time that checkpoint happened
	Created time.Time `json:"created"`
	// Name is the name of the checkpoint
	Name string `json:"name"`
	// TCP checkpoints open tcp connections
	TCP bool `json:"tcp"`
	// UnixSockets persists unix sockets in the checkpoint
	UnixSockets bool `json:"unixSockets"`
	// Shell persists tty sessions in the checkpoint
	Shell bool `json:"shell"`
	// Exit exits the container after the checkpoint is finished
	Exit bool `json:"exit"`
	// EmptyNS tells CRIU to omit a specified namespace
	EmptyNS []string `json:"emptyNS,omitempty"`
}

Checkpoint holds information regarding a container checkpoint

type Container

type Container interface {
	// ID returns the container ID
	ID() string
	// Path returns the path to the bundle
	Path() string
	// Start starts the init process of the container
	Start(ctx context.Context, checkpointPath string, s Stdio) (Process, error)
	// Exec starts another process in an existing container
	Exec(context.Context, string, specs.ProcessSpec, Stdio) (Process, error)
	// Delete removes the container's state and any resources
	Delete() error
	// Processes returns all the containers processes that have been added
	Processes() ([]Process, error)
	// State returns the containers runtime state
	State() State
	// Resume resumes a paused container
	Resume() error
	// Pause pauses a running container
	Pause() error
	// RemoveProcess removes the specified process from the container
	RemoveProcess(string) error
	// Checkpoints returns all the checkpoints for a container
	Checkpoints(checkpointDir string) ([]Checkpoint, error)
	// Checkpoint creates a new checkpoint
	Checkpoint(checkpoint Checkpoint, checkpointDir string) error
	// DeleteCheckpoint deletes the checkpoint for the provided name
	DeleteCheckpoint(name string, checkpointDir string) error
	// Labels are user provided labels for the container
	Labels() []string
	// Pids returns all pids inside the container
	Pids() ([]int, error)
	// Stats returns realtime container stats and resource information
	Stats() (*Stat, error)
	// Name or path of the OCI compliant runtime used to execute the container
	Runtime() string
	// OOM signals the channel if the container received an OOM notification
	OOM() (OOM, error)
	// UpdateResource updates the containers resources to new values
	UpdateResources(*Resource) error

	// Status return the current status of the container.
	Status() (State, error)
}

Container defines the operations allowed on a container

func Load

func Load(root, id, shimName string, timeout time.Duration) (Container, error)

Load return a new container from the matchin state file on disk.

func New

func New(opts ContainerOpts) (Container, error)

New returns a new container

type ContainerOpts

type ContainerOpts struct {
	Root        string
	ID          string
	Bundle      string
	Runtime     string
	RuntimeArgs []string
	Shim        string
	Labels      []string
	NoPivotRoot bool
	Timeout     time.Duration
}

ContainerOpts keeps the options passed at container creation

type Hugetlb

type Hugetlb struct {
	Usage   uint64 `json:"usage,omitempty"`
	Max     uint64 `json:"max,omitempty"`
	Failcnt uint64 `json:"failcnt"`
}

Hugetlb holds information regarding a container huge tlb usage

type Memory

type Memory struct {
	Cache     uint64            `json:"cache,omitempty"`
	Usage     MemoryEntry       `json:"usage,omitempty"`
	Swap      MemoryEntry       `json:"swap,omitempty"`
	Kernel    MemoryEntry       `json:"kernel,omitempty"`
	KernelTCP MemoryEntry       `json:"kernelTCP,omitempty"`
	Raw       map[string]uint64 `json:"raw,omitempty"`
}

Memory holds information regarding the different type of memories available

type MemoryEntry

type MemoryEntry struct {
	Limit   uint64 `json:"limit"`
	Usage   uint64 `json:"usage,omitempty"`
	Max     uint64 `json:"max,omitempty"`
	Failcnt uint64 `json:"failcnt"`
}

MemoryEntry regroups statistic about a given type of memory

type OOM

type OOM interface {
	io.Closer
	FD() int
	ContainerID() string
	Flush()
	Removed() bool
}

OOM wraps a container OOM.

type Pids

type Pids struct {
	Current uint64 `json:"current,omitempty"`
	Limit   uint64 `json:"limit,omitempty"`
}

Pids holds the stat of the pid usage of the machine

type PlatformProcessState

type PlatformProcessState struct {
	Checkpoint string `json:"checkpoint"`
	RootUID    int    `json:"rootUID"`
	RootGID    int    `json:"rootGID"`
}

PlatformProcessState container platform-specific fields in the ProcessState structure

type Process

type Process interface {
	io.Closer

	// ID of the process.
	// This is either "init" when it is the container's init process or
	// it is a user provided id for the process similar to the container id
	ID() string
	// Start unblocks the associated container init process.
	// This should only be called on the process with ID "init"
	Start() error
	CloseStdin() error
	Resize(int, int) error
	// ExitFD returns the fd the provides an event when the process exits
	ExitFD() int
	// ExitStatus returns the exit status of the process or an error if it
	// has not exited
	ExitStatus() (uint32, error)
	// Spec returns the process spec that created the process
	Spec() specs.ProcessSpec
	// Signal sends the provided signal to the process
	Signal(os.Signal) error
	// Container returns the container that the process belongs to
	Container() Container
	// Stdio of the container
	Stdio() Stdio
	// SystemPid is the pid on the system
	SystemPid() int
	// State returns if the process is running or not
	State() State
	// Wait reaps the shim process if avaliable
	Wait()
}

Process holds the operation allowed on a container's process

type ProcessState

type ProcessState struct {
	specs.ProcessSpec
	Exec        bool     `json:"exec"`
	Stdin       string   `json:"containerdStdin"`
	Stdout      string   `json:"containerdStdout"`
	Stderr      string   `json:"containerdStderr"`
	RuntimeArgs []string `json:"runtimeArgs"`
	NoPivotRoot bool     `json:"noPivotRoot"`

	PlatformProcessState
}

ProcessState holds the process OCI specs along with various fields required by containerd

type Resource

type Resource struct {
	CPUShares         int64
	BlkioWeight       uint16
	CPUPeriod         int64
	CPUQuota          int64
	CpusetCpus        string
	CpusetMems        string
	KernelMemory      int64
	KernelTCPMemory   int64
	Memory            int64
	MemoryReservation int64
	MemorySwap        int64
}

Resource regroups the various container limits that can be updated

type Stat

type Stat struct {
	// Timestamp is the time that the statistics where collected
	Timestamp time.Time
	CPU       CPU                `json:"cpu"`
	Memory    Memory             `json:"memory"`
	Pids      Pids               `json:"pids"`
	Blkio     Blkio              `json:"blkio"`
	Hugetlb   map[string]Hugetlb `json:"hugetlb"`
}

Stat holds a container statistics

type State

type State string

State represents a container state

type Stdio

type Stdio struct {
	Stdin  string
	Stdout string
	Stderr string
}

Stdio holds the path to the 3 pipes used for the standard ios.

func NewStdio

func NewStdio(stdin, stdout, stderr string) Stdio

NewStdio wraps the given standard io path into an Stdio struct. If a given parameter is the empty string, it is replaced by "/dev/null"

type Throttling

type Throttling struct {
	Periods          uint64 `json:"periods,omitempty"`
	ThrottledPeriods uint64 `json:"throttledPeriods,omitempty"`
	ThrottledTime    uint64 `json:"throttledTime,omitempty"`
}

Throttling holds a cpu throttling information