Black Lives Matter
Support the Equal Justice Initiative

runc

package module
Version: v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Oct 20, 2020 License: Apache-2.0 Imports: 21 Imported by: 666

README

go-runc

Build Status codecov

This is a package for consuming the runc binary in your Go applications. It tries to expose all the settings and features of the runc CLI. If there is something missing then add it, its opensource!

This needs runc @ a9610f2c0 or greater.

Docs

Docs can be found at godoc.org.

Project details

The go-runc is a containerd sub-project, licensed under the Apache 2.0 license. As a containerd sub-project, you will find the:

information in our containerd/project repository.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrParseRuncVersion = errors.New("unable to parse runc version")

Functions

func LeaveRunning 

func LeaveRunning(args []string) []string

LeaveRunning keeps the container running after the checkpoint has been completed

func PreDump 

func PreDump(args []string) []string

PreDump allows a pre-dump of the checkpoint to be made and completed later

func ReadPidFile 

func ReadPidFile(path string) (int, error)

ReadPidFile reads the pid file at the provided path and returns the pid or an error if the read and conversion is unsuccessful

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

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

type CgroupMode 

type CgroupMode string
const (
	Soft   CgroupMode = "soft"
	Full   CgroupMode = "full"
	Strict CgroupMode = "strict"
)

type CheckpointAction 

type CheckpointAction func([]string) []string

type CheckpointOpts 

type CheckpointOpts struct {
	// ImagePath is the path for saving the criu image file
	ImagePath string
	// WorkDir is the working directory for criu
	WorkDir string
	// ParentPath is the path for previous image files from a pre-dump
	ParentPath string
	// AllowOpenTCP allows open tcp connections to be checkpointed
	AllowOpenTCP bool
	// AllowExternalUnixSockets allows external unix sockets to be checkpointed
	AllowExternalUnixSockets bool
	// AllowTerminal allows the terminal(pty) to be checkpointed with a container
	AllowTerminal bool
	// CriuPageServer is the address:port for the criu page server
	CriuPageServer string
	// FileLocks handle file locks held by the container
	FileLocks bool
	// Cgroups is the cgroup mode for how to handle the checkpoint of a container's cgroups
	Cgroups CgroupMode
	// EmptyNamespaces creates a namespace for the container but does not save its properties
	// Provide the namespaces you wish to be checkpointed without their settings on restore
	EmptyNamespaces []string
	// LazyPages uses userfaultfd to lazily restore memory pages
	LazyPages bool
	// StatusFile is the file criu writes \0 to once lazy-pages is ready
	StatusFile *os.File
}

type ConsoleSocket 

type ConsoleSocket interface {
	Path() string
}

type Container 

type Container struct {
	ID          string            `json:"id"`
	Pid         int               `json:"pid"`
	Status      string            `json:"status"`
	Bundle      string            `json:"bundle"`
	Rootfs      string            `json:"rootfs"`
	Created     time.Time         `json:"created"`
	Annotations map[string]string `json:"annotations"`
}

Container hold information for a runc container

type Cpu 

type Cpu struct {
	Usage      CpuUsage   `json:"usage,omitempty"`
	Throttling Throttling `json:"throttling,omitempty"`
}

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

type CreateOpts 

type CreateOpts struct {
	IO
	// PidFile is a path to where a pid file should be created
	PidFile       string
	ConsoleSocket ConsoleSocket
	Detach        bool
	NoPivot       bool
	NoNewKeyring  bool
	ExtraFiles    []*os.File
	Started       chan<- int
}

type DeleteOpts 

type DeleteOpts struct {
	Force bool
}

type Event 

type Event struct {
	// Type are the event type generated by runc
	// If the type is "error" then check the Err field on the event for
	// the actual error
	Type  string `json:"type"`
	ID    string `json:"id"`
	Stats *Stats `json:"data,omitempty"`
	// Err has a read error if we were unable to decode the event from runc
	Err error `json:"-"`
}

type ExecOpts 

type ExecOpts struct {
	IO
	PidFile       string
	ConsoleSocket ConsoleSocket
	Detach        bool
	Started       chan<- int
}

type Exit 

type Exit struct {
	Timestamp time.Time
	Pid       int
	Status    int
}

type ExitError 

type ExitError struct {
	Status int
}

func (*ExitError) Error 

func (e *ExitError) Error() string

type Format 

type Format string

Format is the type of log formatting options avaliable 

const (
	JSON Format = "json"
	Text Format = "text"
	// DefaultCommand is the default command for Runc
	DefaultCommand = "runc"
)

type Hugetlb 

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

type IO 

type IO interface {
	io.Closer
	Stdin() io.WriteCloser
	Stdout() io.ReadCloser
	Stderr() io.ReadCloser
	Set(*exec.Cmd)
}

func NewNullIO 

func NewNullIO() (IO, error)

NewNullIO returns IO setup for /dev/null use with runc

func NewPipeIO 

func NewPipeIO(uid, gid int, opts ...IOOpt) (i IO, err error)

NewPipeIO creates pipe pairs to be used with runc

func NewSTDIO 

func NewSTDIO() (IO, error)

type IOOpt 

type IOOpt func(*IOOption)

IOOpt sets I/O creation options

type IOOption 

type IOOption struct {
	OpenStdin  bool
	OpenStdout bool
	OpenStderr bool
}

IOOption holds I/O creation options

type KillOpts 

type KillOpts struct {
	All bool
}

KillOpts specifies options for killing a container and its processes

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

type MemoryEntry 

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

type Pids 

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

type ProcessMonitor 

type ProcessMonitor interface {
	Start(*exec.Cmd) (chan Exit, error)
	Wait(*exec.Cmd, chan Exit) (int, error)
}

ProcessMonitor is an interface for process monitoring

It allows daemons using go-runc to have a SIGCHLD handler to handle exits without introducing races between the handler and go's exec.Cmd These methods should match the methods exposed by exec.Cmd to provide a consistent experience for the caller 

var Monitor ProcessMonitor = &defaultMonitor{}

type RestoreOpts 

type RestoreOpts struct {
	CheckpointOpts
	IO

	Detach        bool
	PidFile       string
	NoSubreaper   bool
	NoPivot       bool
	ConsoleSocket ConsoleSocket
}

type Runc 

type Runc struct {
	//If command is empty, DefaultCommand is used
	Command       string
	Root          string
	Debug         bool
	Log           string
	LogFormat     Format
	PdeathSignal  unix.Signal
	Setpgid       bool
	Criu          string
	SystemdCgroup bool
	Rootless      *bool // nil stands for "auto"
}

Runc is the client to the runc cli

func (*Runc) Checkpoint 

func (r *Runc) Checkpoint(context context.Context, id string, opts *CheckpointOpts, actions ...CheckpointAction) error

Checkpoint allows you to checkpoint a container using criu

func (*Runc) Create 

func (r *Runc) Create(context context.Context, id, bundle string, opts *CreateOpts) error

Create creates a new container and returns its pid if it was created successfully

func (*Runc) Delete 

func (r *Runc) Delete(context context.Context, id string, opts *DeleteOpts) error

Delete deletes the container

func (*Runc) Events 

func (r *Runc) Events(context context.Context, id string, interval time.Duration) (chan *Event, error)

Events returns an event stream from runc for a container with stats and OOM notifications

func (*Runc) Exec 

func (r *Runc) Exec(context context.Context, id string, spec specs.Process, opts *ExecOpts) error

Exec executes an additional process inside the container based on a full OCI Process specification

func (*Runc) Kill 

func (r *Runc) Kill(context context.Context, id string, sig int, opts *KillOpts) error

Kill sends the specified signal to the container

func (*Runc) List 

func (r *Runc) List(context context.Context) ([]*Container, error)

List returns all containers created inside the provided runc root directory

func (*Runc) Pause 

func (r *Runc) Pause(context context.Context, id string) error

Pause the container with the provided id

func (*Runc) Ps 

func (r *Runc) Ps(context context.Context, id string) ([]int, error)

Ps lists all the processes inside the container returning their pids

func (*Runc) Restore 

func (r *Runc) Restore(context context.Context, id, bundle string, opts *RestoreOpts) (int, error)

Restore restores a container with the provide id from an existing checkpoint

func (*Runc) Resume 

func (r *Runc) Resume(context context.Context, id string) error

Resume the container with the provided id

func (*Runc) Run 

func (r *Runc) Run(context context.Context, id, bundle string, opts *CreateOpts) (int, error)

Run runs the create, start, delete lifecycle of the container and returns its exit status after it has exited

func (*Runc) Start 

func (r *Runc) Start(context context.Context, id string) error

Start will start an already created container

func (*Runc) State 

func (r *Runc) State(context context.Context, id string) (*Container, error)

State returns the state for the container provided by id

func (*Runc) Stats 

func (r *Runc) Stats(context context.Context, id string) (*Stats, error)

Stats return the stats for a container like cpu, memory, and io

func (*Runc) Top 

func (r *Runc) Top(context context.Context, id string, psOptions string) (*TopResults, error)

Top lists all the processes inside the container returning the full ps data

func (*Runc) Update 

func (r *Runc) Update(context context.Context, id string, resources *specs.LinuxResources) error

Update updates the current container with the provided resource spec

func (*Runc) Version 

func (r *Runc) Version(context context.Context) (Version, error)

Version returns the runc and runtime-spec versions

type Socket 

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

Socket is a unix socket that accepts the pty master created by runc

func NewConsoleSocket 

func NewConsoleSocket(path string) (*Socket, error)

NewConsoleSocket creates a new unix socket at the provided path to accept a pty master created by runc for use by the container

func NewTempConsoleSocket 

func NewTempConsoleSocket() (*Socket, error)

NewTempConsoleSocket returns a temp console socket for use with a container On Close(), the socket is deleted

func (*Socket) Close 

func (c *Socket) Close() error

Close closes the unix socket

func (*Socket) Path 

func (c *Socket) Path() string

Path returns the path to the unix socket on disk

func (*Socket) ReceiveMaster 

func (c *Socket) ReceiveMaster() (console.Console, error)

ReceiveMaster blocks until the socket receives the pty master

type StartCloser 

type StartCloser interface {
	CloseAfterStart() error
}

type Stats 

type Stats struct {
	Cpu     Cpu                `json:"cpu"`
	Memory  Memory             `json:"memory"`
	Pids    Pids               `json:"pids"`
	Blkio   Blkio              `json:"blkio"`
	Hugetlb map[string]Hugetlb `json:"hugetlb"`
}

type Throttling 

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

type TopResults 

type TopResults struct {
	// Processes running in the container, where each is process is an array of values corresponding to the headers
	Processes [][]string `json:"Processes"`

	// Headers are the names of the columns
	Headers []string `json:"Headers"`
}

TopBody represents the structured data of the full ps output

func ParsePSOutput 

func ParsePSOutput(output []byte) (*TopResults, error)

ParsePSOutput parses the runtime's ps raw output and returns a TopResults

type Version 

type Version struct {
	Runc   string
	Commit string
	Spec   string
}

Source Files

View all

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL