sandbox

Documentation

Index

• func NewClient(client interface{}) (api.TTRPCSandboxService, error)
• func ToProto(sandbox *Sandbox) *types.Sandbox
• type Controller
• type ControllerInstance
• type ControllerStatus
• type CreateOpt
  • func WithNetNSPath(netNSPath string) CreateOpt
  • func WithOptions(options any) CreateOpt
  • func WithRootFS(m []*types.Mount) CreateOpt
• type CreateOptions
• type ExitStatus
• type RuntimeOpts
• type Sandbox
  • func FromProto(sandboxpb *types.Sandbox) Sandbox
  • func (s *Sandbox) AddExtension(name string, obj interface{}) error
  • func (s *Sandbox) AddLabel(name string, value string)
  • func (s *Sandbox) GetExtension(name string, obj interface{}) error
  • func (s *Sandbox) GetLabel(name string) (string, error)
• type StopOpt
  • func WithTimeout(timeout time.Duration) StopOpt
• type StopOptions
• type Store

Functions

func NewClient

func NewClient(client interface{}) (api.TTRPCSandboxService, error)

NewClient returns a new sandbox client that handles both GRPC and TTRPC clients.

func ToProto

func ToProto(sandbox *Sandbox) *types.Sandbox

ToProto will map Sandbox struct to it's protobuf definition

Types

type Controller

type Controller interface {
	// Create is used to initialize sandbox environment. (mounts, any)
	Create(ctx context.Context, sandboxID string, opts ...CreateOpt) error
	// Start will start previously created sandbox.
	Start(ctx context.Context, sandboxID string) (ControllerInstance, error)
	// Platform returns target sandbox OS that will be used by Controller.
	// containerd will rely on this to generate proper OCI spec.
	Platform(_ctx context.Context, _sandboxID string) (imagespec.Platform, error)
	// Stop will stop sandbox instance
	Stop(ctx context.Context, sandboxID string, opts ...StopOpt) error
	// Wait blocks until sandbox process exits.
	Wait(ctx context.Context, sandboxID string) (ExitStatus, error)
	// Status will query sandbox process status. It is heavier than Ping call and must be used whenever you need to
	// gather metadata about current sandbox state (status, uptime, resource use, etc).
	Status(ctx context.Context, sandboxID string, verbose bool) (ControllerStatus, error)
	// Shutdown deletes and cleans all tasks and sandbox instance.
	Shutdown(ctx context.Context, sandboxID string) error
}

Controller is an interface to manage sandboxes at runtime. When running in sandbox mode, shim expected to implement `SandboxService`. Shim lifetimes are now managed manually via sandbox API by the containerd's client.

type ControllerInstance

type ControllerInstance struct {
	SandboxID string
	Pid       uint32
	CreatedAt time.Time
	Labels    map[string]string
}

type ControllerStatus

type ControllerStatus struct {
	SandboxID string
	Pid       uint32
	State     string
	Info      map[string]string
	CreatedAt time.Time
	ExitedAt  time.Time
	Extra     typeurl.Any
}

type CreateOpt

type CreateOpt func(*CreateOptions) error

func WithNetNSPath

func WithNetNSPath(netNSPath string) CreateOpt

WithNetNSPath used to assign network namespace path of a sandbox.

func WithOptions

func WithOptions(options any) CreateOpt

WithOptions allows passing arbitrary options when creating a new sandbox.

func WithRootFS

func WithRootFS(m []*types.Mount) CreateOpt

WithRootFS is used to create a sandbox with the provided rootfs mount TODO: Switch to mount.Mount once target added

type CreateOptions

type CreateOptions struct {
	Rootfs []*types.Mount
	// Options are used to pass arbitrary options to the shim when creating a new sandbox.
	// CRI will use this to pass PodSandboxConfig.
	// Don't confuse this with Runtime options, which are passed at shim instance start
	// to setup global shim configuration.
	Options   typeurl.Any
	NetNSPath string
}

type ExitStatus

type ExitStatus struct {
	ExitStatus uint32
	ExitedAt   time.Time
}

type RuntimeOpts

type RuntimeOpts struct {
	Name    string
	Options typeurl.Any
}

RuntimeOpts holds runtime specific information

type Sandbox

type Sandbox struct {
	// ID uniquely identifies the sandbox in a namespace
	ID string
	// Labels provide metadata extension for a sandbox
	Labels map[string]string
	// Runtime shim to use for this sandbox
	Runtime RuntimeOpts
	// Spec carries the runtime specification used to implement the sandbox
	Spec typeurl.Any
	// CreatedAt is the time at which the sandbox was created
	CreatedAt time.Time
	// UpdatedAt is the time at which the sandbox was updated
	UpdatedAt time.Time
	// Extensions stores client-specified metadata
	Extensions map[string]typeurl.Any
}

Sandbox is an object stored in metadata database

func FromProto

func FromProto(sandboxpb *types.Sandbox) Sandbox

FromProto map protobuf sandbox definition to Sandbox struct

func (*Sandbox) AddExtension

func (s *Sandbox) AddExtension(name string, obj interface{}) error

AddExtension is a helper function to add sandbox metadata extension.

func (*Sandbox) AddLabel

func (s *Sandbox) AddLabel(name string, value string)

AddLabel adds a label to sandbox's labels.

func (*Sandbox) GetExtension

func (s *Sandbox) GetExtension(name string, obj interface{}) error

GetExtension retrieves a sandbox extension by name.

func (*Sandbox) GetLabel

func (s *Sandbox) GetLabel(name string) (string, error)

GetLabel retrieves a sandbox label by name.

type StopOpt

type StopOpt func(*StopOptions)

func WithTimeout

func WithTimeout(timeout time.Duration) StopOpt

type StopOptions

type StopOptions struct {
	Timeout *time.Duration
}

type Store

type Store interface {
	// Create a sandbox record in the store
	Create(ctx context.Context, sandbox Sandbox) (Sandbox, error)

	// Update the sandbox with the provided sandbox object and fields
	Update(ctx context.Context, sandbox Sandbox, fieldpaths ...string) (Sandbox, error)

	// Get sandbox metadata using the id
	Get(ctx context.Context, id string) (Sandbox, error)

	// List returns sandboxes that match one or more of the provided filters
	List(ctx context.Context, filters ...string) ([]Sandbox, error)

	// Delete a sandbox from metadata store using the id
	Delete(ctx context.Context, id string) error
}

Store is a storage interface for sandbox metadata objects