sandbox

package
v0.0.0-...-73a4147 Latest Latest
Warning

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

 Go to latest Published: Aug 5, 2024 License: Apache-2.0, MIT Imports: 48 Imported by: 0

Documentation

Overview

Package sandbox creates and manipulates sandboxes.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ConfigureCmdForRootless 

func ConfigureCmdForRootless(cmd *exec.Cmd, donations *donation.Agency) (*os.File, error)

ConfigureCmdForRootless configures cmd to donate a socket FD that can be used to synchronize userns configuration.

func SetUserMappings 

func SetUserMappings(spec *specs.Spec, pid int) error

SetUserMappings uses newuidmap/newgidmap programs to set up user ID mappings for process pid.

Types

type Args 

type Args struct {
	// ID is the sandbox 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

	// UserLog is the filename to send user-visible logs to. It may be empty.
	UserLog string

	// IOFiles is the list of files that connect to a gofer endpoint for the
	// mounts points using Gofers. They must be in the same order as mounts
	// appear in the spec.
	IOFiles []*os.File

	// OverlayFilestoreFiles are the regular files that will back the tmpfs upper
	// mount in the overlay mounts.
	OverlayFilestoreFiles []*os.File

	// OverlayMediums contains information about how the gofer mounts have been
	// overlaid. The first entry is for rootfs and the following entries are for
	// bind mounts in Spec.Mounts (in the same order).
	OverlayMediums []boot.OverlayMedium

	// MountHints provides extra information about containers mounts that apply
	// to the entire pod.
	MountHints *boot.PodMountHints

	// MountsFile is a file container mount information from the spec. It's
	// equivalent to the mounts from the spec, except that all paths have been
	// resolved to their final absolute location.
	MountsFile *os.File

	// Gcgroup is the cgroup that the sandbox is part of.
	Cgroup cgroup.Cgroup

	// Attached indicates that the sandbox lifecycle is attached with the caller.
	// If the caller exits, the sandbox should exit too.
	Attached bool

	// SinkFiles is the an ordered array of files to be used by seccheck sinks
	// configured from the --pod-init-config file.
	SinkFiles []*os.File

	// PassFiles are user-supplied files from the host to be exposed to the
	// sandboxed app.
	PassFiles map[int]*os.File

	// ExecFile is the file from the host used for program execution.
	ExecFile *os.File
}

Args is used to configure a new sandbox.

type Sandbox 

type Sandbox struct {
	// ID is the id of the sandbox (immutable). By convention, this is the same
	// ID as the first container run in the sandbox.
	ID string `json:"id"`

	// PodName is the name of the Kubernetes Pod (if any) that this sandbox
	// represents. Unset if not running under containerd or Kubernetes.
	PodName string `json:"podName"`

	// Namespace is the Kubernetes namespace (if any) of the pod that this
	// sandbox represents. Unset if not running under containerd or Kubernetes.
	Namespace string `json:"namespace"`

	// Pid is the pid of the running sandbox. May be 0 if the sandbox
	// is not running.
	Pid pid `json:"pid"`

	// UID is the user ID in the parent namespace that the sandbox is running as.
	UID int `json:"uid"`
	// GID is the group ID in the parent namespace that the sandbox is running as.
	GID int `json:"gid"`

	// CgroupJSON contains the cgroup configuration that the sandbox is part of
	// and allow serialization of the configuration into json
	CgroupJSON cgroup.CgroupJSON `json:"cgroup"`

	// OriginalOOMScoreAdj stores the value of oom_score_adj when the sandbox
	// started, before it may be modified.
	OriginalOOMScoreAdj int `json:"originalOomScoreAdj"`

	// RegisteredMetrics is the set of metrics registered in the sandbox.
	// Used for verifying metric data integrity after containers are started.
	// Only populated if exporting metrics was requested when the sandbox was
	// created.
	RegisteredMetrics *metricpb.MetricRegistration `json:"registeredMetrics"`

	// MetricMetadata are key-value pairs that are useful to export about this
	// sandbox, but not part of the set of labels that uniquely identify it.
	// They are static once initialized, and typically contain high-level
	// configuration information about the sandbox.
	MetricMetadata map[string]string `json:"metricMetadata"`

	// MetricServerAddress is the address of the metric server that this sandbox
	// intends to export metrics for.
	// Only populated if exporting metrics was requested when the sandbox was
	// created.
	MetricServerAddress string `json:"metricServerAddress"`

	// ControlAddress is the uRPC address used to connect to the sandbox.
	ControlAddress string `json:"control_address"`

	// MountHints provides extra information about container mounts that apply
	// to the entire pod.
	MountHints *boot.PodMountHints `json:"mountHints"`
	// contains filtered or unexported fields
}

Sandbox wraps a sandbox process.

It is used to start/stop sandbox process (and associated processes like gofers), as well as for running and manipulating containers inside a running sandbox.

Note: Sandbox must be immutable because a copy of it is saved for each container and changes would not be synchronized to all of them.

func New 

func New(conf *config.Config, args *Args) (*Sandbox, error)

New creates the sandbox process. The caller must call Destroy() on the sandbox.

func (*Sandbox) BlockProfile 

func (s *Sandbox) BlockProfile(f *os.File, duration time.Duration) error

BlockProfile writes a block profile to the given file.

func (*Sandbox) CPUProfile 

func (s *Sandbox) CPUProfile(f *os.File, duration time.Duration) error

CPUProfile collects a CPU profile.

func (*Sandbox) CgroupsReadControlFile 

func (s *Sandbox) CgroupsReadControlFile(file control.CgroupControlFile) (string, error)

CgroupsReadControlFile reads a single cgroupfs control file in the sandbox.

func (*Sandbox) CgroupsWriteControlFile 

func (s *Sandbox) CgroupsWriteControlFile(file control.CgroupControlFile, value string) error

CgroupsWriteControlFile writes a single cgroupfs control file in the sandbox.

func (*Sandbox) ChangeLogging 

func (s *Sandbox) ChangeLogging(args control.LoggingArgs) error

ChangeLogging changes logging options.

func (*Sandbox) Checkpoint 

func (s *Sandbox) Checkpoint(cid string, f *os.File) error

Checkpoint sends the checkpoint call for a container in the sandbox. The statefile will be written to f.

func (*Sandbox) CreateSubcontainer 

func (s *Sandbox) CreateSubcontainer(conf *config.Config, cid string, tty *os.File) error

CreateSubcontainer creates a container inside the sandbox.

func (*Sandbox) CreateTraceSession 

func (s *Sandbox) CreateTraceSession(config *seccheck.SessionConfig, force bool) error

CreateTraceSession creates a new trace session.

func (*Sandbox) DeleteTraceSession 

func (s *Sandbox) DeleteTraceSession(name string) error

DeleteTraceSession deletes an existing trace session.

func (*Sandbox) DestroyContainer 

func (s *Sandbox) DestroyContainer(cid string) error

DestroyContainer destroys the given container. If it is the root container, then the entire sandbox is destroyed.

func (*Sandbox) Event 

func (s *Sandbox) Event(cid string) (*boot.EventOut, error)

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

func (*Sandbox) Execute 

func (s *Sandbox) Execute(conf *config.Config, args *control.ExecArgs) (int32, error)

Execute runs the specified command in the container. It returns the PID of the newly created process.

func (*Sandbox) ExportMetrics 

func (s *Sandbox) ExportMetrics(opts control.MetricsExportOpts) (*prometheus.Snapshot, error)

ExportMetrics returns a snapshot of metric values from the sandbox in Prometheus format.

func (*Sandbox) GetRegisteredMetrics 

func (s *Sandbox) GetRegisteredMetrics() (*metricpb.MetricRegistration, error)

GetRegisteredMetrics returns metric registration data from the sandbox. This data is meant to be used as a way to sanity-check any exported metrics data during the lifetime of the sandbox in order to avoid a compromised sandbox from being able to produce bogus metrics. This returns an error if the sandbox has not requested instrumentation during creation time.

func (*Sandbox) Getpid 

func (s *Sandbox) Getpid() int

Getpid returns the process ID of the sandbox process.

func (*Sandbox) HeapProfile 

func (s *Sandbox) HeapProfile(f *os.File, delay time.Duration) error

HeapProfile writes a heap profile to the given file.

func (*Sandbox) IsRootContainer 

func (s *Sandbox) IsRootContainer(cid string) bool

IsRootContainer returns true if the specified container ID belongs to the root container.

func (*Sandbox) IsRunning 

func (s *Sandbox) IsRunning() bool

IsRunning returns true if the sandbox or gofer process is running.

func (*Sandbox) ListTraceSessions 

func (s *Sandbox) ListTraceSessions() ([]seccheck.SessionConfig, error)

ListTraceSessions lists all trace sessions.

func (*Sandbox) MutexProfile 

func (s *Sandbox) MutexProfile(f *os.File, duration time.Duration) error

MutexProfile writes a mutex profile to the given file.

func (*Sandbox) NewCGroup 

func (s *Sandbox) NewCGroup() (cgroup.Cgroup, error)

NewCGroup returns the sandbox's Cgroup, or an error if it does not have one.

func (*Sandbox) Pause 

func (s *Sandbox) Pause(cid string) error

Pause sends the pause call for a container in the sandbox.

func (*Sandbox) PortForward 

func (s *Sandbox) PortForward(opts *boot.PortForwardOpts) error

PortForward starts port forwarding to the sandbox.

func (*Sandbox) Processes 

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

Processes retrieves the list of processes and associated metadata for a given container in this sandbox.

func (*Sandbox) ProcfsDump 

func (s *Sandbox) ProcfsDump() ([]procfs.ProcessProcfsDump, error)

ProcfsDump collects and returns a procfs dump for the sandbox.

func (*Sandbox) Restore 

func (s *Sandbox) Restore(conf *config.Config, cid string, filename string) error

Restore sends the restore call for a container in the sandbox.

func (*Sandbox) Resume 

func (s *Sandbox) Resume(cid string) error

Resume sends the resume call for a container in the sandbox.

func (*Sandbox) SignalContainer 

func (s *Sandbox) SignalContainer(cid string, sig unix.Signal, all bool) error

SignalContainer sends the signal to a container in the sandbox. If all is true and signal is SIGKILL, then waits for all processes to exit before returning.

func (*Sandbox) SignalProcess 

func (s *Sandbox) SignalProcess(cid string, pid int32, sig unix.Signal, fgProcess bool) error

SignalProcess sends the signal to a particular process in the container. If fgProcess is true, then the signal is sent to the foreground process group in the same session that PID belongs to. This is only valid if the process is attached to a host TTY.

func (*Sandbox) Stacks 

func (s *Sandbox) Stacks() (string, error)

Stacks collects and returns all stacks for the sandbox.

func (*Sandbox) StartRoot 

func (s *Sandbox) StartRoot(conf *config.Config) error

StartRoot starts running the root container process inside the sandbox.

func (*Sandbox) StartSubcontainer 

func (s *Sandbox) StartSubcontainer(spec *specs.Spec, conf *config.Config, cid string, stdios, goferFiles, overlayFilestoreFiles []*os.File, overlayMediums []boot.OverlayMedium) error

StartSubcontainer starts running a sub-container inside the sandbox.

func (*Sandbox) Trace 

func (s *Sandbox) Trace(f *os.File, duration time.Duration) error

Trace collects an execution trace.

func (*Sandbox) Usage 

func (s *Sandbox) Usage(Full bool) (control.MemoryUsage, error)

Usage sends the collect call for a container in the sandbox.

func (*Sandbox) UsageFD 

func (s *Sandbox) UsageFD() (*control.MemoryUsageRecord, error)

UsageFD sends the usagefd call for a container in the sandbox.

func (*Sandbox) Wait 

func (s *Sandbox) Wait(cid string) (unix.WaitStatus, error)

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

func (*Sandbox) WaitPID 

func (s *Sandbox) WaitPID(cid string, pid int32) (unix.WaitStatus, error)

WaitPID waits for process 'pid' in the container's sandbox and returns its WaitStatus.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.