sandbox

Documentation

Overview

Package sandbox creates and manipulates sandboxes.

Index

• func List(rootDir string) ([]string, error)
• func Run(id string, spec *specs.Spec, conf *boot.Config, ...) (syscall.WaitStatus, error)
• type Sandbox
  • func Create(id string, spec *specs.Spec, conf *boot.Config, ...) (*Sandbox, error)
  • func Load(rootDir, id string) (*Sandbox, error)
  • func (s *Sandbox) Destroy() error
  • func (s *Sandbox) Event() (*boot.Event, error)
  • func (s *Sandbox) Execute(e *control.ExecArgs) (syscall.WaitStatus, error)
  • func (s *Sandbox) Processes() ([]*control.Process, error)
  • func (s *Sandbox) Signal(sig syscall.Signal) error
  • func (s *Sandbox) Start(conf *boot.Config) error
  • func (s *Sandbox) State() specs.State
  • func (s *Sandbox) Wait() (syscall.WaitStatus, error)
• type Status
  • func (s Status) String() string

Functions

func List

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

List returns all sandbox ids in the given root directory.

func Run

func Run(id string, spec *specs.Spec, conf *boot.Config, bundleDir, consoleSocket, pidFile string, args []string) (syscall.WaitStatus, error)

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

Types

type Sandbox

type Sandbox struct {
	// ID is the sandbox ID.
	ID string `json:"id"`

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

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

	// SandboxRoot is the directory containing the sandbox metadata file.
	SandboxRoot string `json:"sandboxRoot"`

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

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

	// ConsoleSocket is the path to a unix domain socket that will receive
	// the console FD.  It is only used during create, so we don't need to
	// store it in the metadata.
	ConsoleSocket string `json:"-"`

	// Pid is the pid of the running sandbox.  Only valid if Status is
	// Created or Running.
	Pid int `json:"pid"`

	// GoferPid is the pid of the gofer running along side the sandbox. May be 0
	// if the gofer has been killed or it's not being used.
	GoferPid int `json:"goferPid"`

	// Status is the current sandbox Status.
	Status Status `json:"status"`
}

Sandbox wraps a child sandbox process, and is responsible for saving and loading sandbox metadata to disk.

Within a root directory, we maintain subdirectories for each sandbox named with the sandbox id. The sandbox metadata is is stored as json within the sandbox directoy in a file named "meta.json". This metadata format is defined by us, and is not part of the OCI spec.

Sandboxes must write this metadata file after any change to their internal state. The entire sandbox directory is deleted when the sandbox is destroyed.

TODO: Protect against concurrent changes to the sandbox metadata file.

func Create

func Create(id string, spec *specs.Spec, conf *boot.Config, bundleDir, consoleSocket, pidFile string, args []string) (*Sandbox, error)

Create creates the sandbox subprocess and writes the metadata file. Args are additional arguments that will be passed to the sandbox process.

func Load

func Load(rootDir, id string) (*Sandbox, error)

Load loads a sandbox from with the given id from a metadata file.

func (*Sandbox) Destroy

func (s *Sandbox) Destroy() error

Destroy frees all resources associated with the sandbox.

func (*Sandbox) Event

func (s *Sandbox) Event() (*boot.Event, error)

Event retrieves stats about the sandbox such as memory and CPU utilization.

func (*Sandbox) Execute

func (s *Sandbox) Execute(e *control.ExecArgs) (syscall.WaitStatus, error)

Execute runs the specified command in the sandbox.

func (*Sandbox) Processes

func (s *Sandbox) Processes() ([]*control.Process, error)

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

func (*Sandbox) Signal

func (s *Sandbox) Signal(sig syscall.Signal) error

Signal sends the signal to the sandbox.

func (*Sandbox) Start

func (s *Sandbox) Start(conf *boot.Config) error

Start starts running the containerized process inside the sandbox.

func (*Sandbox) State

func (s *Sandbox) State() specs.State

State returns the metadata of the sandbox.

func (*Sandbox) Wait

func (s *Sandbox) Wait() (syscall.WaitStatus, error)

Wait waits for the containerized process to exit, and returns its WaitStatus.

type Status

type Status int

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

TODO: Get precise about the transitions between statuses.

const (
	// Creating indicates "the container is being created".
	Creating Status = iota

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

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