containerutil

package
v0.8.17 Latest Latest
Warning

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

 Go to latest Published: Feb 11, 2026 License: MPL-2.0 Imports: 18 Imported by: 0

Documentation

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 (
	// ProtocolTCP is the TCP protocol type.
	ProtocolTCP = ProtocolType("tcp")

	// ProtocolUDP is the UDP protocol type.
	ProtocolUDP = ProtocolType("udp")
)
View Source 
const (
	// FrontendAuto is automatic frontend detection.
	FrontendAuto = "auto"

	// FrontendDocker forces usage of the (future, currently unimplemented) docker API for container operations.
	FrontendDocker = "docker"

	// FrontendDockerShell forces usage of the docker binary for container operations.
	FrontendDockerShell = "docker-shell"

	// FrontendPodman forces usage of the (future, currently unimplemented) podman API for container operations.
	FrontendPodman = "podman"

	// FrontendPodmanShell forces usage of the podman binary for container operations.
	FrontendPodmanShell = "podman-shell"

	// FrontendStub is for when there is no valid provider but attempting to run anyways is desired;
	// like integration tests, or the earthly/earthly image when NO_DOCKER is set.
	FrontendStub = "stub"
)
View Source 
const (
	// FrontendTypeShell signifies that a given frontend is using an external binary via shell.
	FrontendTypeShell = "shell"

	// FrontendTypeAPI signifies that a given frontend is using an API, typically through some external daemon.
	FrontendTypeAPI = "api"
)
View Source 
const (
	// TCPAddressFmt is the address at which the daemon is available when using TCP.
	TCPAddressFmt = "tcp://127.0.0.1:%d"

	// DockerSchemePrefix is used to construct the buildkit address for local docker-based connections.
	DockerSchemePrefix = "docker-container://"
)
View Source 
const (
	SchemeDockerContainer = "docker-container"
	SchemePodmanContainer = "podman-container"
)

Variables

View Source 
var ErrFrontendNotInitialized = errors.New("frontend (e.g. docker/podman) not initialized")

ErrFrontendNotInitialized is returned when the frontend is not initialized.

Functions

func DefaultAddressForSetting 

func DefaultAddressForSetting(setting string, localContainerName string, defaultPort int) (string, error)

DefaultAddressForSetting returns an address (signifying the desired/default transport) for a given frontend specified by setting.

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.

Types

type ContainerFrontend 

type ContainerFrontend interface {
	Scheme() string

	IsAvailable(ctx context.Context) bool
	Config() *CurrentFrontend
	Information(ctx context.Context) (*FrontendInfo, error)

	ContainerList(ctx context.Context) ([]*ContainerInfo, error)
	ContainerInfo(ctx context.Context, namesOrIDs ...string) (map[string]*ContainerInfo, error)
	ContainerRemove(ctx context.Context, force bool, namesOrIDs ...string) error
	ContainerStop(ctx context.Context, timeoutSec uint, namesOrIDs ...string) error
	ContainerLogs(ctx context.Context, namesOrIDs ...string) (map[string]*ContainerLogs, error)
	ContainerRun(ctx context.Context, containers ...ContainerRun) error

	ImageInfo(ctx context.Context, refs ...string) (map[string]*ImageInfo, error)
	ImagePull(ctx context.Context, refs ...string) error
	ImageRemove(ctx context.Context, force bool, refs ...string) error
	ImageTag(ctx context.Context, tags ...ImageTag) error
	ImageLoad(ctx context.Context, image ...io.Reader) error
	ImageLoadFromFileCommand(filename string) string

	VolumeInfo(ctx context.Context, volumeNames ...string) (map[string]*VolumeInfo, error)
}

ContainerFrontend is an interface specifying all the container options Earthly needs to do.

func FrontendForSetting 

func FrontendForSetting(ctx context.Context, feType string, cfg *FrontendConfig) (ContainerFrontend, error)

FrontendForSetting returns a frontend given a setting. This includes automatic detection.

func NewDockerShellFrontend 

func NewDockerShellFrontend(ctx context.Context, cfg *FrontendConfig) (ContainerFrontend, error)

NewDockerShellFrontend constructs a new Frontend using the docker binary installed on the host. It also ensures that the binary is functional for our needs and collects compatibility information.

func NewPodmanShellFrontend 

func NewPodmanShellFrontend(ctx context.Context, cfg *FrontendConfig) (ContainerFrontend, error)

NewPodmanShellFrontend constructs a new Frontend using the podman binary installed on the host. It also ensures that the binary is functional for our needs and collects compatibility information.

func NewStubFrontend 

func NewStubFrontend(ctx context.Context, cfg *FrontendConfig) (ContainerFrontend, error)

NewStubFrontend creates a stubbed frontend. Useful in cases where a frontend could not be detected, but we still need a frontend. Examples include earthly/earthly, or integration tests. It is currently only used as a fallback when docker or other frontends are missing.

type ContainerInfo 

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

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

type ContainerLogs 

type ContainerLogs struct {
	Stdout string
	Stderr string
}

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

type ContainerRun 

type ContainerRun struct {
	Envs          EnvMap
	Labels        LabelMap
	NameOrID      string
	ImageRef      string
	Mounts        MountOpt
	Ports         PortOpt
	ContainerArgs []string
	// We would like to shift to the non-shell providers. However, we do provide an option for supplying
	// additional arguments to the CLI when starting buildkit. While this allowed great flexibility, we
	// also do not know what or how it is being used. This gives us the option to support those users until
	// we decide to pull the plug. This argument is ignored by non-shell providers.
	AdditionalArgs []string
	Privileged     bool
}

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

type CurrentFrontend 

type CurrentFrontend struct {
	*FrontendURLs

	Setting string
	Binary  string
	Type    string
}

CurrentFrontend contains information about the current container frontend. Useful when the frontend was configured using FrontendAuto for deciding transport.

type EnvMap 

type EnvMap map[string]string

EnvMap is a map of environment variable names (key) to values. Values must be strings.

type FrontendConfig 

type FrontendConfig struct {
	BuildkitHostCLIValue       string
	BuildkitHostFileValue      string
	LocalRegistryHostFileValue string
	LocalContainerName         string
	Console                    conslogging.ConsoleLogger
	DefaultPort                int
}

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

type FrontendInfo 

type FrontendInfo struct {
	ClientVersion    string
	ClientAPIVersion string
	ClientPlatform   string

	ServerVersion    string
	ServerAPIVersion string
	ServerPlatform   string
	ServerAddress    string
}

FrontendInfo contains the client and server information for a frontend.

type FrontendURLs 

type FrontendURLs struct {
	BuildkitHost      *url.URL
	LocalRegistryHost *url.URL
}

FrontendURLs is a struct containing the relevant URLs to contact a container, if it is a buildkit container.

type ImageInfo 

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

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

type ImageTag 

type ImageTag struct {
	SourceRef string
	TargetRef string
}

ImageTag contains a source and target ref, used for tagging an image. It means that the SourceRef is tagged as the value in TargetRef.

type LabelMap 

type LabelMap map[string]string

LabelMap is a map of label names (key) to values. Values must be strings.

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

type MountOpt 

type MountOpt []Mount

MountOpt is a list of Mounts to perform.

type MountType 

type MountType string

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

type Port 

type Port struct {
	IP            string
	Protocol      ProtocolType
	HostPort      int
	ContainerPort int
}

Port contains the needed data to publish a port for a given container in a given frontend.

type PortOpt 

type PortOpt []Port

PortOpt is a list of Ports to publish.

type ProtocolType 

type ProtocolType string

ProtocolType constrains the kinds of protocols the frontend API needs to support. Current valid values are tcp and udp.

type VolumeInfo 

type VolumeInfo struct {
	Name       string
	Mountpoint string
	SizeBytes  uint64
}

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