container

package
v1.222.0-rc.8 Latest Latest
Warning

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

Go to latest
Published: Jun 24, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// PullMissing pulls only after initial container creation fails.
	PullMissing = "missing"
	// PullAlways pulls the image before creating the container.
	PullAlways = "always"
	// PullNever never pulls the image.
	PullNever = "never"

	// CleanupAlways removes the container after execution, even on failure.
	CleanupAlways = "always"
	// CleanupOnSuccess removes the container only after successful execution.
	CleanupOnSuccess = "on_success"
	// CleanupNever leaves the container behind.
	CleanupNever = "never"
)
View Source
const (
	SandboxLabelType         = "com.atmos.type"
	SandboxLabelWorkflow     = "com.atmos.workflow"
	SandboxLabelWorkflowPath = "com.atmos.workflow.path"
	SandboxLabelRunID        = "com.atmos.run.id"
	SandboxLabelWorkspace    = "com.atmos.workspace"
	SandboxTypeWorkflow      = "workflow-sandbox"
)

Variables

This section is empty.

Functions

func BuildEphemeralPreview added in v1.222.0

func BuildEphemeralPreview(runtimeName string, config *EphemeralConfig) string

BuildEphemeralPreview builds a human-readable equivalent runtime command.

func BuildImageBuildPreview added in v1.222.0

func BuildImageBuildPreview(runtimeName string, config *BuildConfig) string

BuildImageBuildPreview builds a human-readable equivalent image build command.

func BuildImagePushPreview added in v1.222.0

func BuildImagePushPreview(runtimeName, image string) string

BuildImagePushPreview builds a human-readable equivalent image push command.

func BuildImageTagPreview added in v1.222.0

func BuildImageTagPreview(runtimeName, source, target string) string

BuildImageTagPreview builds a human-readable equivalent image tag command.

func ExitCode added in v1.222.0

func ExitCode(err error) int

ExitCode extracts a process exit code from an error.

func RuntimeStatusMessage

func RuntimeStatusMessage(status RuntimeStatus, runtimeType Type) string

RuntimeStatusMessage returns a user-friendly message describing the runtime status.

Types

type AttachOptions

type AttachOptions struct {
	Shell     string
	ShellArgs []string
	User      string

	// IO streams for input/output. If nil, defaults to os.Stdin and iolib.Data/UI.
	Stdin  io.Reader
	Stdout io.Writer
	Stderr io.Writer
}

AttachOptions represents options for attaching to containers.

type BakeConfig added in v1.222.0

type BakeConfig struct {
	File    string
	Files   []string
	Target  string
	Targets []string
	Set     []string
	Vars    map[string]string
	Load    bool
	Push    bool
	Print   bool
}

BakeConfig represents Docker Buildx Bake configuration.

type BuildConfig

type BuildConfig struct {
	Dockerfile string
	Context    string
	Engine     string
	Args       map[string]string
	Tags       []string
	Target     string
	NoCache    bool
	Pull       bool
	Bake       *BakeConfig
}

BuildConfig represents container image build configuration.

type CreateConfig

type CreateConfig struct {
	Name            string
	Image           string
	WorkspaceFolder string
	Mounts          []Mount
	Ports           []PortBinding
	Env             map[string]string
	User            string
	Labels          map[string]string

	// Runtime configuration
	RunArgs         []string
	OverrideCommand bool     // Whether to override default command with sleep infinity
	Init            bool     // Whether to use init process
	Privileged      bool     // Run in privileged mode
	CapAdd          []string // Linux capabilities to add
	SecurityOpt     []string // Security options
}

CreateConfig represents container creation configuration.

type DockerRuntime

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

DockerRuntime implements the Runtime interface for Docker.

func NewDockerRuntime

func NewDockerRuntime() *DockerRuntime

NewDockerRuntime creates a new Docker runtime.

func (*DockerRuntime) Attach

func (d *DockerRuntime) Attach(ctx context.Context, containerID string, opts *AttachOptions) error

Attach attaches to a running container with an interactive shell.

func (*DockerRuntime) Build

func (d *DockerRuntime) Build(ctx context.Context, config *BuildConfig) error

Build builds a container image from a Dockerfile.

func (*DockerRuntime) Create

func (d *DockerRuntime) Create(ctx context.Context, config *CreateConfig) (string, error)

Create creates a new container.

func (*DockerRuntime) Exec

func (d *DockerRuntime) Exec(ctx context.Context, containerID string, cmd []string, opts *ExecOptions) error

Exec executes a command in a running container.

func (*DockerRuntime) ImageInspect added in v1.222.0

func (d *DockerRuntime) ImageInspect(ctx context.Context, image string) (*ImageInfo, error)

ImageInspect returns metadata for a local container image.

func (*DockerRuntime) Info

func (d *DockerRuntime) Info(ctx context.Context) (*RuntimeInfo, error)

Info gets runtime information.

func (*DockerRuntime) Inspect

func (d *DockerRuntime) Inspect(ctx context.Context, containerID string) (*Info, error)

Inspect gets detailed information about a container.

func (*DockerRuntime) List

func (d *DockerRuntime) List(ctx context.Context, filters map[string]string) ([]Info, error)

List lists containers matching the given filters.

func (*DockerRuntime) Logs

func (d *DockerRuntime) Logs(ctx context.Context, containerID string, follow bool, tail string, stdout, stderr io.Writer) error

Logs shows logs from a container.

func (*DockerRuntime) Pull

func (d *DockerRuntime) Pull(ctx context.Context, image string) error

Pull pulls a container image.

func (*DockerRuntime) Push added in v1.222.0

func (d *DockerRuntime) Push(ctx context.Context, image string) (*PushResult, error)

Push pushes a container image.

func (*DockerRuntime) Remove

func (d *DockerRuntime) Remove(ctx context.Context, containerID string, force bool) error

Remove removes a container.

func (*DockerRuntime) SetEnv added in v1.222.0

func (d *DockerRuntime) SetEnv(env []string)

SetEnv sets the environment for docker CLI subprocesses launched by this runtime. See EnvSetter for the rationale.

func (*DockerRuntime) Start

func (d *DockerRuntime) Start(ctx context.Context, containerID string) error

Start starts a container.

func (*DockerRuntime) Stop

func (d *DockerRuntime) Stop(ctx context.Context, containerID string, timeout time.Duration) error

Stop stops a running container.

func (*DockerRuntime) Tag added in v1.222.0

func (d *DockerRuntime) Tag(ctx context.Context, source, target string) error

Tag tags a container image.

type EnvSetter added in v1.222.0

type EnvSetter interface {
	SetEnv(env []string)
}

EnvSetter is implemented by runtimes whose CLI subprocesses can be launched with a specific environment. The container step uses this to forward the identity-resolved environment (e.g. the DOCKER_CONFIG materialized by the aws/ecr auth integration, or AWS_* credentials) so build/push/run can reach private registries. Runtimes that do not implement it inherit os.Environ().

type EphemeralConfig added in v1.222.0

type EphemeralConfig struct {
	Name              string
	Image             string
	Command           []string
	WorkspaceHostPath string
	WorkspaceFolder   string
	WorkspaceReadOnly bool
	Mounts            []Mount
	Ports             []PortBinding
	Env               []string
	User              string
	Labels            map[string]string
	RunArgs           []string
	PullPolicy        string
	CleanupPolicy     string
	TTY               bool
	Interactive       bool
}

EphemeralConfig describes a one-shot container execution.

type EphemeralResult added in v1.222.0

type EphemeralResult struct {
	ContainerID string
	Stdout      string
	Stderr      string
	ExitCode    int
}

EphemeralResult is the result of a one-shot container execution.

func RunEphemeralContainer added in v1.222.0

func RunEphemeralContainer(ctx context.Context, runtime Runtime, config *EphemeralConfig) (*EphemeralResult, error)

RunEphemeralContainer creates, starts, execs, and optionally removes a container.

type ExecOptions

type ExecOptions struct {
	User         string
	WorkingDir   string
	Env          []string
	AttachStdin  bool
	AttachStdout bool
	AttachStderr bool
	Tty          bool

	// IO streams for input/output. If nil, defaults to iolib.Data/UI.
	Stdin  io.Reader
	Stdout io.Writer
	Stderr io.Writer
}

ExecOptions represents options for executing commands in containers.

type ImageInfo added in v1.222.0

type ImageInfo struct {
	ID           string
	RepoTags     []string
	RepoDigests  []string
	Size         int64
	Created      string
	Architecture string
	Os           string
	Author       string
	Labels       map[string]string
	Layers       int
}

ImageInfo contains metadata about a local container image.

type Info

type Info struct {
	ID      string
	Name    string
	Image   string
	Status  string // running, stopped, exited, etc.
	Created time.Time
	Ports   []PortBinding
	Labels  map[string]string
}

Info represents container state information.

type Mount

type Mount struct {
	Type     string // bind, volume, tmpfs
	Source   string
	Target   string
	ReadOnly bool
}

Mount represents a volume mount.

type PodmanRuntime

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

PodmanRuntime implements the Runtime interface for Podman.

func NewPodmanRuntime

func NewPodmanRuntime() *PodmanRuntime

NewPodmanRuntime creates a new Podman runtime.

func (*PodmanRuntime) Attach

func (p *PodmanRuntime) Attach(ctx context.Context, containerID string, opts *AttachOptions) error

Attach attaches to a running container with an interactive shell.

func (*PodmanRuntime) Build

func (p *PodmanRuntime) Build(ctx context.Context, config *BuildConfig) error

Build builds a container image from a Dockerfile.

func (*PodmanRuntime) Create

func (p *PodmanRuntime) Create(ctx context.Context, config *CreateConfig) (string, error)

Create creates a new container.

func (*PodmanRuntime) Exec

func (p *PodmanRuntime) Exec(ctx context.Context, containerID string, cmd []string, opts *ExecOptions) error

Exec executes a command in a running container.

func (*PodmanRuntime) ImageInspect added in v1.222.0

func (p *PodmanRuntime) ImageInspect(ctx context.Context, image string) (*ImageInfo, error)

ImageInspect returns metadata for a local container image.

func (*PodmanRuntime) Info

func (p *PodmanRuntime) Info(ctx context.Context) (*RuntimeInfo, error)

Info gets runtime information.

func (*PodmanRuntime) Inspect

func (p *PodmanRuntime) Inspect(ctx context.Context, containerID string) (*Info, error)

Inspect gets detailed information about a container.

func (*PodmanRuntime) List

func (p *PodmanRuntime) List(ctx context.Context, filters map[string]string) ([]Info, error)

List lists containers matching the given filters.

func (*PodmanRuntime) Logs

func (p *PodmanRuntime) Logs(ctx context.Context, containerID string, follow bool, tail string, stdout, stderr io.Writer) error

Logs shows logs from a container.

func (*PodmanRuntime) Pull

func (p *PodmanRuntime) Pull(ctx context.Context, image string) error

Pull pulls a container image.

func (*PodmanRuntime) Push added in v1.222.0

func (p *PodmanRuntime) Push(ctx context.Context, image string) (*PushResult, error)

Push pushes a container image.

func (*PodmanRuntime) Remove

func (p *PodmanRuntime) Remove(ctx context.Context, containerID string, force bool) error

Remove removes a container.

func (*PodmanRuntime) SetEnv added in v1.222.0

func (p *PodmanRuntime) SetEnv(env []string)

SetEnv sets the environment for podman CLI subprocesses launched by this runtime. See EnvSetter for the rationale.

func (*PodmanRuntime) Start

func (p *PodmanRuntime) Start(ctx context.Context, containerID string) error

Start starts a container.

func (*PodmanRuntime) Stop

func (p *PodmanRuntime) Stop(ctx context.Context, containerID string, timeout time.Duration) error

Stop stops a running container.

func (*PodmanRuntime) Tag added in v1.222.0

func (p *PodmanRuntime) Tag(ctx context.Context, source, target string) error

Tag tags a container image.

type PortBinding

type PortBinding struct {
	ContainerPort int
	HostPort      int
	Protocol      string // tcp, udp
}

PortBinding represents a port mapping.

type PushResult added in v1.222.0

type PushResult struct {
	Image  string
	Digest string
	Output string
}

PushResult contains metadata returned by a container image push.

type Runtime

type Runtime interface {
	// Lifecycle operations
	Build(ctx context.Context, config *BuildConfig) error
	Create(ctx context.Context, config *CreateConfig) (string, error)
	Start(ctx context.Context, containerID string) error
	Stop(ctx context.Context, containerID string, timeout time.Duration) error
	Remove(ctx context.Context, containerID string, force bool) error

	// State inspection
	Inspect(ctx context.Context, containerID string) (*Info, error)
	List(ctx context.Context, filters map[string]string) ([]Info, error)

	// Execution - IO streams configured via options structs
	Exec(ctx context.Context, containerID string, cmd []string, opts *ExecOptions) error
	Attach(ctx context.Context, containerID string, opts *AttachOptions) error

	// Image operations
	Pull(ctx context.Context, image string) error
	Tag(ctx context.Context, source, target string) error
	Push(ctx context.Context, image string) (*PushResult, error)
	ImageInspect(ctx context.Context, image string) (*ImageInfo, error)

	// Logs - methods that produce user-facing output accept io.Writer
	Logs(ctx context.Context, containerID string, follow bool, tail string, stdout, stderr io.Writer) error

	// Info
	Info(ctx context.Context) (*RuntimeInfo, error)
}

Runtime defines the interface for container runtime operations. This interface abstracts Docker and Podman operations for testability.

func DetectRuntime

func DetectRuntime(ctx context.Context) (Runtime, error)

DetectRuntime auto-detects the available container runtime. Priority order: 1. ATMOS_CONTAINER_RUNTIME environment variable 2. Docker (if available and running) 3. Podman (if available and running) Returns error if no runtime is available.

func DetectRuntimeWithPreference added in v1.222.0

func DetectRuntimeWithPreference(ctx context.Context, preferred string) (Runtime, error)

DetectRuntimeWithPreference detects a runtime, optionally requiring a specific runtime.

func DetectRuntimeWithPreferenceAndRecovery added in v1.222.0

func DetectRuntimeWithPreferenceAndRecovery(ctx context.Context, preferred string, autoStart bool) (Runtime, error)

DetectRuntimeWithPreferenceAndRecovery detects a runtime and optionally initializes/starts Podman when Podman is the selected runtime.

type RuntimeInfo

type RuntimeInfo struct {
	Type    string // docker, podman
	Version string
	Running bool
}

RuntimeInfo represents container runtime information.

type RuntimeStatus

type RuntimeStatus int

RuntimeStatus represents the availability status of a container runtime.

const (
	// RuntimeAvailable indicates the runtime is available and responsive.
	RuntimeAvailable RuntimeStatus = iota
	// RuntimeUnavailable indicates the runtime binary is not found.
	RuntimeUnavailable
	// RuntimeNotResponding indicates the runtime binary exists but is not responding.
	RuntimeNotResponding
	// RuntimeNeedsInit indicates Podman is present but needs machine initialization.
	RuntimeNeedsInit
	// RuntimeNeedsStart indicates Podman machine exists but needs to be started.
	RuntimeNeedsStart
)

func TryRecoverPodmanRuntime

func TryRecoverPodmanRuntime(ctx context.Context) RuntimeStatus

TryRecoverPodmanRuntime attempts to recover Podman by initializing/starting the machine. This is an opt-in operation that should only be called when the user explicitly requests it. Returns the new status after recovery attempt.

type Sandbox added in v1.222.0

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

Sandbox is a started or dry-run workflow sandbox.

func StartSandbox added in v1.222.0

func StartSandbox(ctx context.Context, config *SandboxConfig) (*Sandbox, error)

StartSandbox detects the runtime, cleans up stopped stale sandboxes, creates, and starts the workflow sandbox.

func (*Sandbox) Cleanup added in v1.222.0

func (s *Sandbox) Cleanup(success bool) error

Cleanup removes the sandbox according to the configured cleanup policy.

func (*Sandbox) Exec added in v1.222.0

func (s *Sandbox) Exec(ctx context.Context, command []string, opts *ExecOptions) error

Exec runs a command inside the sandbox.

func (*Sandbox) ID added in v1.222.0

func (s *Sandbox) ID() string

ID returns the runtime container ID. In dry run it returns the generated name.

func (*Sandbox) Name added in v1.222.0

func (s *Sandbox) Name() string

Name returns the generated sandbox container name.

type SandboxConfig added in v1.222.0

type SandboxConfig struct {
	Name              string
	Workflow          string
	WorkflowPath      string
	RunID             string
	RuntimeName       string
	RuntimeAutoStart  bool
	Image             string
	WorkspaceHostPath string
	WorkspaceFolder   string
	WorkspaceReadOnly bool
	Mounts            []Mount
	Ports             []PortBinding
	Env               []string
	RuntimeEnv        []string
	User              string
	Labels            map[string]string
	RunArgs           []string
	PullPolicy        string
	CleanupPolicy     string
	DryRun            bool
}

SandboxConfig describes a long-lived workflow sandbox container.

func NewWorkflowSandboxConfig added in v1.222.0

func NewWorkflowSandboxConfig(workflow, workflowPath, workspaceHostPath string) SandboxConfig

NewWorkflowSandboxConfig builds a sandbox config with stable labels and a unique container name for a workflow execution.

type Type

type Type string

Type represents the container runtime type.

const (
	// TypeDocker represents Docker runtime.
	TypeDocker Type = "docker"

	// TypePodman represents Podman runtime.
	TypePodman Type = "podman"
)

func GetRuntimeType

func GetRuntimeType(runtime Runtime) Type

GetRuntimeType returns the type of a runtime instance.

func (Type) String

func (t Type) String() string

Jump to

Keyboard shortcuts

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