containerutil

package
v0.8.9 Latest Latest
Warning

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

Go to latest
Published: Apr 24, 2024 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"

	// DockerAddressFmt is the address at which the daemon is available when using a Docker Container directly
	DockerAddressFmt = "docker-container://%s-buildkitd"

	// PodmanAddressFmt is the address at which the daemon is available when using a Podman Container directly.
	// Currently unused due to image export issues
	PodmanAddressFmt = "podman-container://%s-buildkitd"

	// SatelliteAddress is the remote address when using a Satellite to execute your builds remotely.
	SatelliteAddress = "tcp://satellite.earthly.dev:8372"
)

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, installationName 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 {
	ID       string
	Name     string
	Platform string
	Created  time.Time
	Status   string
	IPs      map[string]string
	Ports    []string
	Image    string
	ImageID  string
	Labels   map[string]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 {
	NameOrID      string
	ImageRef      string
	Privileged    bool
	Envs          EnvMap
	Labels        LabelMap
	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
}

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

	InstallationName string
	DefaultPort      int

	Console conslogging.ConsoleLogger
}

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
	HostPort      int
	ContainerPort int
	Protocol      ProtocolType
}

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL