Help us shape the future of Go! Take the 2026 Go Developer Survey

engine

package
v0.8.20-rc-0 Latest Latest
Warning

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

 Go to latest Published: Oct 22, 2026 License: MPL-2.0 Imports: 20 Imported by: 0

Documentation

Overview

Package engine provides container engine abstractions and implementations.

Index

Constants

View Source 
const (
	// StatusMissing signifies that a container is not present.
	StatusMissing = "missing"

	// StatusCreated signifies that a container has been created, but not started.
	StatusCreated = "created"

	// StatusRestarting signifies that a container has started, stopped, and is currently restarting.
	StatusRestarting = "restarting"

	// StatusRunning signifies that a container is currently running.
	StatusRunning = "running"

	// StatusRemoving signifies that a container has exited and is currently being removed.
	StatusRemoving = "removing"

	// StatusPaused means a container has been suspended.
	StatusPaused = "paused"

	// StatusExited means that a container was running and has been stopped, but not removed.
	StatusExited = "exited"

	// StatusDead means that a container was killed for some reason and has not yet been restarted.
	StatusDead = "dead"
)
View Source 
const (
	// MountBind is the bind MountType.
	MountBind = MountType("bind")

	// MountVolume is the volume MountType.
	MountVolume = MountType("volume")
)
View Source 
const (
	// DefaultLocalRegistryPort is the standard network port used by the embedded local registry for image exports.
	DefaultLocalRegistryPort = 8371

	// DefaultBuildkitPort is the standard network port used by the buildkit daemon.
	DefaultBuildkitPort = 8372

	// DockerSchemePrefix is used to construct the buildkit address for local docker-based connections.
	DockerSchemePrefix = "docker-container://"

	// AppleSchemePrefix is used to construct the buildkit address for local apple-container-based connections.
	AppleSchemePrefix = "apple-container://"

	// PodmanSchemePrefix is used to construct the buildkit address for local podman-container-based connections.
	PodmanSchemePrefix = "podman-container://"
)

Variables

View Source 
var ErrNotInitialized = errors.New("container engine not initialized")

ErrNotInitialized is returned when the container engine is not initialized.

Functions

func IsLocal 

func IsLocal(addr string) bool

IsLocal parses a URL and returns whether it is considered a local buildkit host + port that we need to manage ourselves.

func IsMemoryPressured 

func IsMemoryPressured() bool

IsMemoryPressured returns true if the host is experiencing elevated memory pressure.

func UsesTCP 

func UsesTCP(scheme string) bool

UsesTCP returns true if the given URL scheme communicates with BuildKit over TCP (e.g. "tcp", "apple-container").

Types

type Addrs 

type Addrs struct {
	Buildkit      *url.URL
	LocalRegistry *url.URL
}

Addrs contains the network addresses to contact a container engine or buildkit daemon.

func ResolveAddrs 

func ResolveAddrs(driver Driver, cfg *Config) (Addrs, error)

ResolveAddrs calculates and validates buildkit and registry URLs based on the given configuration.

func (Addrs) IsLocalRegistry 

func (a Addrs) IsLocalRegistry(ref string) bool

IsLocalRegistry reports whether the given reference points to the local registry.

type Client 

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

Client is the concrete struct used for interacting with the container engine.

func New 

func New(ctx context.Context, driver Driver, cfg *Config) (*Client, error)

New returns a container client given a driver. This includes automatic detection.

func NewStub 

func NewStub(cfg *Config) (*Client, error)

NewStub creates a stub engine instance for fallback/tests.

func NewTestClient 

func NewTestClient(meta Metadata) *Client

NewTestClient creates a *Client for testing with custom metadata.

func (*Client) ContainerAddr 

func (c *Client) ContainerAddr(ctx context.Context, containerName string, port int) (string, error)

ContainerAddr returns the reachable address for a given port on a container.

func (*Client) ContainerLogs 

func (c *Client) ContainerLogs(ctx context.Context, nameOrID string) (Logs, error)

ContainerLogs returns stdout and stderr logs for a single container.

func (*Client) ContainersLogs 

func (c *Client) ContainersLogs(ctx context.Context, namesOrIDs ...string) ([]Logs, error)

ContainersLogs returns logs for specified containers in 1:1 order.

func (*Client) DefaultAddr 

func (c *Client) DefaultAddr(cfg *Config) (string, error)

DefaultAddr returns the default address for the container engine given a config.

func (*Client) ImageLoadCommand 

func (c *Client) ImageLoadCommand(filename string) string

ImageLoadCommand returns the shell command used to load an image archive.

func (*Client) InspectContainer 

func (c *Client) InspectContainer(ctx context.Context, nameOrID string) (Container, error)

InspectContainer returns metadata for a single container.

func (*Client) InspectContainers 

func (c *Client) InspectContainers(ctx context.Context, namesOrIDs ...string) ([]Container, error)

InspectContainers returns metadata for multiple containers in 1:1 order.

func (*Client) InspectImage 

func (c *Client) InspectImage(ctx context.Context, ref string) (Image, error)

InspectImage retrieves image metadata for a single reference.

func (*Client) InspectImages 

func (c *Client) InspectImages(ctx context.Context, refs ...string) ([]Image, error)

InspectImages retrieves image metadata for multiple references in 1:1 order.

func (*Client) InspectVolume 

func (c *Client) InspectVolume(ctx context.Context, volumeName string) (Volume, error)

InspectVolume retrieves metadata for a single volume.

func (*Client) InspectVolumes 

func (c *Client) InspectVolumes(ctx context.Context, volumeNames ...string) ([]Volume, error)

InspectVolumes retrieves metadata for multiple volume names in 1:1 order.

func (*Client) IsAvailable 

func (c *Client) IsAvailable(ctx context.Context) bool

IsAvailable returns true if the container engine is installed and accessible.

func (*Client) ListContainers 

func (c *Client) ListContainers(ctx context.Context) ([]Container, error)

ListContainers lists running or existing containers.

func (*Client) LoadImage 

func (c *Client) LoadImage(ctx context.Context, images ...io.Reader) error

LoadImage loads images from tar streams into the container engine.

func (*Client) Metadata 

func (c *Client) Metadata() Metadata

Metadata returns engine metadata and endpoints.

func (*Client) PullImage 

func (c *Client) PullImage(ctx context.Context, refs ...string) error

PullImage pulls images from a registry.

func (*Client) RemoveContainer 

func (c *Client) RemoveContainer(ctx context.Context, force bool, namesOrIDs ...string) error

RemoveContainer removes one or more containers.

func (*Client) RemoveImage 

func (c *Client) RemoveImage(ctx context.Context, force bool, refs ...string) error

RemoveImage removes images.

func (*Client) RemoveVolumes 

func (c *Client) RemoveVolumes(ctx context.Context, force bool, volumeNames ...string) error

RemoveVolumes removes one or more volumes.

func (*Client) RunContainer 

func (c *Client) RunContainer(ctx context.Context, specs ...ContainerSpec) error

RunContainer starts containers according to the given configurations.

func (*Client) StopContainer 

func (c *Client) StopContainer(ctx context.Context, timeout time.Duration, namesOrIDs ...string) error

StopContainer stops one or more running containers.

func (*Client) TagImage 

func (c *Client) TagImage(ctx context.Context, source, target string) error

TagImage tags a source image with a target reference.

func (*Client) Version 

func (c *Client) Version(ctx context.Context) (Version, error)

Version returns version information for the container engine.

type Config 

type Config struct {
	Log               *conslogging.ConsoleLogger
	BuildkitHost      string
	LocalRegistryHost string
	ContainerName     string
	DefaultPort       int
}

Config is the configuration needed to bring up a given container engine. Includes logging and needed information to calculate URLs to reach the container.

type Container 

type Container struct {
	Created  time.Time
	IPs      map[string]string
	Labels   map[string]string
	ID       string
	Name     string
	Platform string
	Status   string
	Image    string
	ImageID  string
}

Container contains things we may care about from inspect output for a given container.

type ContainerSpec 

type ContainerSpec struct {
	Envs          map[string]string
	Labels        map[string]string
	NameOrID      string
	ImageRef      string
	Mounts        []Mount
	PortMappings  []PortMapping
	ContainerArgs []string
	// AdditionalArgs holds extra CLI arguments forwarded to the container engine's run command
	// (e.g. from the buildkit_additional_args user configuration).
	AdditionalArgs []string
	Privileged     bool
}

ContainerSpec contains the information needed to create and run a container.

type Driver 

type Driver string

Driver identifies a supported container backend driver. 

const (
	// Auto specifies automatic engine detection.
	Auto Driver = "auto"

	// Docker specifies the docker driver.
	Docker Driver = "docker"

	// DockerShell is an alias for Docker for backwards compatibility.
	DockerShell Driver = "docker-shell"

	// Podman specifies the podman driver.
	Podman Driver = "podman"

	// PodmanShell is an alias for Podman for backwards compatibility.
	PodmanShell Driver = "podman-shell"

	// AppleContainer specifies the apple container driver.
	AppleContainer Driver = "apple-container"

	// Stub is for when there is no valid container provider (e.g. tests or satellite builds).
	Stub Driver = "stub"
)

type Image 

type Image struct {
	ID           string
	OS           string
	Architecture string
	Tags         []string
}

Image contains information about a given image ref, including all relevant tags.

type Logs 

type Logs struct {
	Stdout string
	Stderr string
}

Logs contains the stdout and stderr logs of a given container.

type Metadata 

type Metadata struct {
	// Addrs holds network addresses for communicating with the engine.
	Addrs Addrs

	// Name is the display name of the engine (e.g. "Docker", "Podman", "Apple Container").
	Name string

	// Scheme is the connection protocol scheme used by the engine (e.g. SchemeDocker).
	Scheme Scheme
}

Metadata contains information describing an engine implementation.

type Mount 

type Mount struct {
	Type     MountType
	Source   string
	Dest     string
	ReadOnly bool
}

Mount contains the needed data to construct a mount for a container in a given engine.

type MountType 

type MountType string

MountType constrains the kinds of mounts the Engine API needs to support. Current valid values are bind and volume.

type PortMapping 

type PortMapping struct {
	HostIP        string
	HostPort      int
	ContainerPort int
}

PortMapping describes a published container port.

func (PortMapping) String 

func (m PortMapping) String() string

String returns the port mapping formatted for CLI flags ([host-ip:][host-port:]container-port).

type Scheme 

type Scheme int

Scheme represents a supported container connection protocol. 

const (
	// SchemeInvalid indicates an uninitialized or unsupported scheme.
	SchemeInvalid Scheme = iota

	// SchemeTCP is the TCP protocol scheme.
	SchemeTCP

	// SchemeDocker is the scheme used for docker-container addresses.
	SchemeDocker

	// SchemePodman is the scheme used for podman-container addresses.
	SchemePodman

	// SchemeApple is the scheme used for apple-container addresses.
	SchemeApple
)

func (Scheme) RequiresTLSByDefault 

func (s Scheme) RequiresTLSByDefault() bool

RequiresTLSByDefault reports whether the scheme requires TLS certificates by default.

func (Scheme) String 

func (s Scheme) String() string

String implements fmt.Stringer for URI construction and formatting.

func (Scheme) SupportsRegistryProxy 

func (s Scheme) SupportsRegistryProxy() bool

SupportsRegistryProxy reports whether the scheme supports the local registry proxy.

func (Scheme) UsesTCP 

func (s Scheme) UsesTCP() bool

UsesTCP returns true if the scheme uses a TCP network transport.

type Version 

type Version struct {
	ClientVersion    string
	ClientAPIVersion string
	ClientPlatform   string

	ServerVersion    string
	ServerAPIVersion string
	ServerPlatform   string
	ServerAddress    string
}

Version contains the client and server information for a container engine.

type Volume 

type Volume struct {
	Name       string
	Mountpoint string
	SizeBytes  uint64
}

Volume contains information about a given volume, including its name, where its mounted from, and the size of the volume.

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.