dockerutil

Documentation

Overview

Package dockerutil contains convenience functions for interacting with Docker.

Index

• Constants
• Variables
• func BootstrapContainer(ctx context.Context, client DockerClient, conf BootstrapConfig) error
• func BridgeIPFromCIDR(cidr string) (net.IP, int)
• func CreateContainer(ctx context.Context, client DockerClient, conf *ContainerConfig) (string, error)
• func DefaultLogImagePullFn(log buildlog.Logger) func(ImagePullEvent) error
• func ExecContainer(ctx context.Context, client DockerClient, config ExecConfig) ([]byte, error)
• func PruneImages(ctx context.Context, client DockerClient) (dockertypes.ImagesPruneReport, error)
• func PullImage(ctx context.Context, config *PullImageConfig) error
• func SetContainerQuota(ctx context.Context, containerID string, quota xunix.CPUQuota) error
• func WaitForDaemon(ctx context.Context, client DockerClient) error
• func WithClient(ctx context.Context, client DockerClient) context.Context
• func WriteCertsForRegistry(ctx context.Context, registryName, certsDir string) error
• type AuthConfig
  • func AuthConfigFromPath(path string, reg string) (AuthConfig, error)
  • func AuthConfigFromString(raw string, reg string) (AuthConfig, error)
  • func (a AuthConfig) Base64() (string, error)
• type BootstrapConfig
• type ContainerConfig
• type DockerClient
  • func Client(ctx context.Context) (DockerClient, error)
• type ExecConfig
• type ImageMetadata
  • func GetImageMetadata(ctx context.Context, client DockerClient, image, username string) (ImageMetadata, error)
• type ImagePullEvent
• type ImagePullProgressFn
• type PullImageConfig

Constants

const (

	// Default CPU period for containers.
	DefaultCPUPeriod uint64 = 1e5
)

Variables

var DefaultBridgeCIDR = "172.19.0.1/30"

Functions

func BootstrapContainer

func BootstrapContainer(ctx context.Context, client DockerClient, conf BootstrapConfig) error

BoostrapContainer runs a script inside the container as the provided user. If conf.Script is empty then it is a noop.

func BridgeIPFromCIDR

func BridgeIPFromCIDR(cidr string) (net.IP, int)

func CreateContainer

func CreateContainer(ctx context.Context, client DockerClient, conf *ContainerConfig) (string, error)

CreateContainer creates a sysbox-runc container.

func DefaultLogImagePullFn

func DefaultLogImagePullFn(log buildlog.Logger) func(ImagePullEvent) error

func ExecContainer

func ExecContainer(ctx context.Context, client DockerClient, config ExecConfig) ([]byte, error)

ExecContainer runs a command in a container. It returns the output and any error. If an error occurs during the execution of the command, the output is appended to the error.

func PruneImages

func PruneImages(ctx context.Context, client DockerClient) (dockertypes.ImagesPruneReport, error)

PruneImage runs a simple 'docker prune'.

func PullImage

func PullImage(ctx context.Context, config *PullImageConfig) error

PullImage pulls the provided image.

func SetContainerQuota

func SetContainerQuota(ctx context.Context, containerID string, quota xunix.CPUQuota) error

SetContainerQuota writes a quota to its correct location for the inner container. HACK: until https://github.com/nestybox/sysbox/issues/582 is resolved, we need to copy the CPU quota and period from the outer container to the inner container to ensure that applications inside the container know how much CPU they have to work with.

For cgroupv2: - /sys/fs/cgroup/<subpath>/init.scope/cpu.max

For cgroupv1: - /sys/fs/cgroup/cpu,cpuacct/<subpath>/syscont-cgroup-root/cpu.cfs_quota_us - /sys/fs/cgroup/cpu,cpuacct/<subpath>/syscont-cgroup-root/cpu.cfs_period_us

func WaitForDaemon

func WaitForDaemon(ctx context.Context, client DockerClient) error

WaitForDaemon waits for a Docker daemon to startup. It waits a max of 5m before giving up.

func WithClient

func WithClient(ctx context.Context, client DockerClient) context.Context

WithClient sets the provided DockerClient on the context. It should only be used for tests.

func WriteCertsForRegistry

func WriteCertsForRegistry(ctx context.Context, registryName, certsDir string) error

WriteCertsForRegistry writes the certificates found in the provided directory to the correct subdirectory that the Docker daemon uses when pulling images from the specified private registry.

Types

type AuthConfig

type AuthConfig dockertypes.AuthConfig

func AuthConfigFromPath

func AuthConfigFromPath(path string, reg string) (AuthConfig, error)

func AuthConfigFromString

func AuthConfigFromString(raw string, reg string) (AuthConfig, error)

func (AuthConfig) Base64

func (a AuthConfig) Base64() (string, error)

type BootstrapConfig

type BootstrapConfig struct {
	ContainerID string
	User        string
	Script      string
	Env         []string
	Detach      bool
	StdOutErr   io.Writer
}

type ContainerConfig

type ContainerConfig struct {
	Log        slog.Logger
	Mounts     []xunix.Mount
	Devices    []container.DeviceMapping
	Envs       []string
	Name       string
	Image      string
	WorkingDir string
	Hostname   string
	// HasInit dictates whether the entrypoint of the container is /sbin/init
	// or 'sleep infinity'.
	HasInit     bool
	CPUs        int64
	MemoryLimit int64
}

type DockerClient

type DockerClient interface {
	dockerclient.SystemAPIClient
	dockerclient.ContainerAPIClient
	dockerclient.ImageAPIClient
}

func Client

func Client(ctx context.Context) (DockerClient, error)

Client returns the DockerClient set on the context. If one can't be found a default client is returned.

type ExecConfig

type ExecConfig struct {
	ContainerID string
	User        string
	Cmd         string
	Args        []string
	Stdin       io.Reader
	StdOutErr   io.Writer
	Env         []string
	Detach      bool
}

type ImageMetadata

type ImageMetadata struct {
	UID     string
	GID     string
	HomeDir string
	HasInit bool
}

func GetImageMetadata

func GetImageMetadata(ctx context.Context, client DockerClient, image, username string) (ImageMetadata, error)

GetImageMetadata returns metadata about an image such as the UID/GID of the provided username and whether it contains an /sbin/init that we should run.

type ImagePullEvent

type ImagePullEvent struct {
	Status         string `json:"status"`
	Error          string `json:"error"`
	Progress       string `json:"progress"`
	ProgressDetail struct {
		Current int `json:"current"`
		Total   int `json:"total"`
	} `json:"progressDetail"`
}

type ImagePullProgressFn

type ImagePullProgressFn func(e ImagePullEvent) error

ImagePullProgressFn provides a way for a consumer to process image pull progress.

type PullImageConfig

type PullImageConfig struct {
	Client     DockerClient
	Image      string
	Auth       AuthConfig
	ProgressFn ImagePullProgressFn
}