docker

package
v1.10.26 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 2026 License: AGPL-3.0, Apache-2.0 Imports: 5 Imported by: 0

Documentation

Overview

Package docker is the stack engine's Docker seam; no Docker SDK types cross it.

Index

Constants

View Source
const (
	// LabelPrefix namespaces every platform-applied Docker label.
	LabelPrefix = "io.miabi."

	LabelApp         = "io.miabi.app"          // application id
	LabelDeployment  = "io.miabi.deployment"   // deployment id
	LabelDatabase    = "io.miabi.database"     // database instance id
	LabelStack       = "io.miabi.stack"        // stack id
	LabelVolume      = "io.miabi.volume"       // volume id
	LabelJob         = "io.miabi.job"          // one-shot job container (transient)
	LabelRole        = "io.miabi.role"         // platform-infra role (node-gateway, …)
	LabelNode        = "io.miabi.node"         // node slug
	LabelWorkspace   = "io.miabi.workspace"    // owning workspace id
	LabelManaged     = "io.miabi.managed"      // "true" on managed raw resources/services
	LabelPipelineRun = "io.miabi.pipeline-run" // pipeline run id (transient)
	LabelSizeBytes   = "io.miabi.size_bytes"   // volume size hint

	// One exact-match key, so the whole stack is a single Docker label filter.
	LabelPartOf = "io.miabi.part-of"
	// Recreating a compose-owned container out-of-band is silently reverted by the next `docker compose up -d`.
	LabelManagedBy = "io.miabi.managed-by"
	// Declared, never inferred: not all infra is undeletable, and a role allowlist would drift.
	LabelProtected = "io.miabi.protected"
	// Lets `miabi install` detect changes without re-deriving Docker's normalization.
	LabelSpecHash = "io.miabi.spec-hash"
)

The single source of truth for io.miabi.* label keys; never hand-write the literals elsewhere.

View Source
const (
	// Platform stack (examples/compose/compose.yaml + the agent).
	RoleControlPlane       = "control-plane"
	RolePlatformDB         = "platform-db"
	RolePlatformCache      = "platform-cache"
	RoleGateway            = "gateway" // the central, compose-managed gateway
	RoleAgent              = "agent"
	RoleControlPlaneWorker = "worker" // a split-out `command: ["worker"]` service

	// Infrastructure Miabi provisions itself.
	RoleNodeGateway      = "node-gateway"
	RoleNodeGatewayRedis = "node-gateway-redis"
	// RoleMetadataGuard is the per-node helper that keeps containers off the cloud metadata service.
	RoleMetadataGuard = "metadata-guard"
	// The label, not the name, guards it, so renaming the network can't make it attachable from app APIs.
	RolePlatformInternal = "platform-internal"
	// Reuses the control-plane value because networks were labelled that way first and Docker can't relabel.
	RoleProxyNetwork = RoleControlPlane
	RoleRegistry     = "registry"
	RoleRegistryGC   = "registry-gc" // transient: deliberately NOT protected
)
View Source
const (
	// Version changes must also be written to the compose env, or `docker compose up -d` reverts them.
	ManagedByCompose = "compose"
	// ManagedByMiabi: Miabi created it and may freely recreate it.
	ManagedByMiabi    = "miabi"
	ManagedByExternal = "external"
)

Lifecycle owners for LabelManagedBy.

View Source
const ManagedLabel = LabelManaged
View Source
const PartOfMiabi = "miabi"

Variables

View Source
var ErrNotFound = errors.New("docker: resource not found")

Functions

func IsManaged

func IsManaged(labels map[string]string) bool

func IsPlatformInfra

func IsPlatformInfra(labels map[string]string) bool

func IsPlatformNetwork added in v1.10.6

func IsPlatformNetwork(labels map[string]string) bool

The labels are the test, never the name; name-only callers must resolve and match the id too.

func IsPlatformStack

func IsPlatformStack(labels map[string]string) bool

func IsProtected

func IsProtected(labels map[string]string) bool

Infra means "do not reclaim as an orphan"; protected means "do not let a human break it by accident".

func IsReservedLabelKey

func IsReservedLabelKey(key string) bool

func IsRootless added in v1.10.22

func IsRootless(securityOptions []string) bool

IsRootless reports whether a daemon's `docker info` security options mark it rootless.

func LabelValue

func LabelValue(labels map[string]string, key string) (value string, ok bool)

func ManagedBy

func ManagedBy(labels map[string]string) string

"" when unlabeled, e.g. a stack installed before platform labels existed.

func PlatformLabels

func PlatformLabels(role, managedBy string, extra map[string]string) map[string]string

Use it so a component can never be half-labeled; extra may not override the four keys set here.

func SanitizeUserLabels

func SanitizeUserLabels(in map[string]string) map[string]string

func WorkspaceID

func WorkspaceID(labels map[string]string) (id uint, ok bool)

Types

type BindMount

type BindMount struct {
	Source   string // host path
	Target   string // container path
	ReadOnly bool
	// An unmounted storage-class disk must fail loudly rather than get a directory on the root filesystem.
	NoCreate bool
}

BindMount is a host path bound into a container.

type Client

type Client interface {
	ListContainers(ctx context.Context, all bool) ([]Container, error)
	InspectContainer(ctx context.Context, id string) (Container, error)
	InspectContainerConfig(ctx context.Context, id string) (ContainerConfig, error)
	RunContainer(ctx context.Context, spec RunSpec) (string, error)
	RestartContainer(ctx context.Context, id string, timeoutSeconds int) error
	RemoveContainer(ctx context.Context, id string, force bool) error
	RunOneShot(ctx context.Context, spec RunSpec) (exitCode int, logs string, err error)

	PullImage(ctx context.Context, ref string, auth *RegistryAuth) error
	ImageExists(ctx context.Context, ref string) (bool, error)

	EnsureNetworkSpec(ctx context.Context, spec NetworkSpec) (string, error)
	// A network split can't be done by recreating: in between, the control plane would lose its database.
	NetworkConnect(ctx context.Context, name, containerID string, aliases []string) error
	NetworkDisconnect(ctx context.Context, name, containerID string, force bool) error
	// InspectNetwork returns ErrNotFound when the network does not exist.
	InspectNetwork(ctx context.Context, name string) (NetworkState, error)
	RemoveNetwork(ctx context.Context, name string) error

	// Rootless reports whether the daemon runs in rootless mode, which the stack does not support.
	Rootless(ctx context.Context) (bool, error)

	CreateVolume(ctx context.Context, name string, labels map[string]string, sizeBytes int64) (Volume, error)
	InspectVolume(ctx context.Context, name string) (Volume, error)
	RemoveVolume(ctx context.Context, name string, force bool) error
}

Deliberately narrow so neither the CLI's nor the control plane's Docker SDK appears in a signature.

type Container

type Container struct {
	ID           string             `json:"id"`
	Names        []string           `json:"names"`
	Image        string             `json:"image"`
	State        string             `json:"state"`
	Status       string             `json:"status"`
	Health       string             `json:"health,omitempty"` // "", "starting", "healthy", "unhealthy"
	Restarting   bool               `json:"restarting,omitempty"`
	RestartCount int                `json:"restart_count,omitempty"`
	ExitCode     int                `json:"exit_code,omitempty"`
	StartedAt    string             `json:"started_at,omitempty"` // RFC3339 from inspect
	Created      int64              `json:"created"`
	Ports        []Port             `json:"ports,omitempty"`
	Labels       map[string]string  `json:"labels,omitempty"`
	Networks     []ContainerNetwork `json:"networks,omitempty"` // populated by InspectContainer
}

Container is a summary of a Docker container.

type ContainerConfig

type ContainerConfig struct {
	ID            string            `json:"id"`
	Name          string            `json:"name"`
	Image         string            `json:"image"` // c.Config.Image (repo[:tag])
	State         string            `json:"state"`
	Command       []string          `json:"command,omitempty"`
	Entrypoint    []string          `json:"entrypoint,omitempty"`
	Env           []string          `json:"env,omitempty"`  // KEY=VALUE (effective)
	User          string            `json:"user,omitempty"` // c.Config.User: "uid[:gid]" or a name; "" = image default
	Labels        map[string]string `json:"labels,omitempty"`
	Ports         []PortMapping     `json:"ports,omitempty"`    // published host ports
	Mounts        []ContainerMount  `json:"mounts,omitempty"`   // volume + bind mounts
	Networks      []string          `json:"networks,omitempty"` // attached network names
	RestartPolicy string            `json:"restart_policy"`     // no|always|unless-stopped|on-failure[:N]
	MemoryBytes   int64             `json:"memory_bytes"`
	NanoCPUs      int64             `json:"nano_cpus"`
}

type ContainerMount

type ContainerMount struct {
	Type        string `json:"type"` // "volume" | "bind" | ...
	Name        string `json:"name,omitempty"`
	Source      string `json:"source,omitempty"`
	Destination string `json:"destination"`
	ReadOnly    bool   `json:"read_only"`
}

type ContainerNetwork

type ContainerNetwork struct {
	Name      string `json:"name"`
	IPAddress string `json:"ip_address"`
	// Shows whether a container actually got a v6 address; ones started before IPv6 was enabled have none.
	IPv6Address string `json:"ipv6_address,omitempty"`
	Gateway     string `json:"gateway,omitempty"`
	// The only stable address, so moving networks must carry aliases verbatim rather than recompute them.
	Aliases []string `json:"aliases,omitempty"`
}

IPs change on recreate; prefer the network alias for stable addressing.

type FileEntry added in v1.8.1

type FileEntry struct {
	Path    string
	Content string
	Mode    string
}

Mode is a 3- or 4-digit octal string; empty means 0644.

type GPURequest

type GPURequest struct {
	DeviceIDs    []string   // resolved GPU UUIDs; nil selects by Count instead
	Count        int        // used only when DeviceIDs is nil (-1 = all devices)
	Capabilities [][]string // e.g. [["gpu"]]
}

Count -1 means all; Capabilities is [["gpu"]] for NVIDIA.

type HealthcheckSpec

type HealthcheckSpec struct {
	Test        []string // e.g. ["CMD-SHELL", "curl -f http://localhost/ || exit 1"]
	Interval    time.Duration
	Timeout     time.Duration
	Retries     int
	StartPeriod time.Duration
}

HealthcheckSpec configures a container healthcheck (Docker HEALTHCHECK).

type NetworkSpec

type NetworkSpec struct {
	Name       string
	Driver     string // "" = bridge; "overlay" for swarm
	Internal   bool
	Attachable bool // overlay networks that standalone containers may join
	Encrypted  bool // overlay data-plane encryption
	Subnet     string
	Gateway    string
	Labels     map[string]string
	EnableIPv6 *bool
	IPv6Subnet string
}

Explicit IPAM so creation does not draw from Docker's default-address-pools.

type NetworkState added in v1.10.22

type NetworkState struct {
	ID         string
	EnableIPv6 bool
}

NetworkState is the part of an existing network the stack reconciles against its manifest.

type Port

type Port struct {
	PrivatePort uint16 `json:"private_port"`
	PublicPort  uint16 `json:"public_port,omitempty"`
	Protocol    string `json:"protocol"`
}

Port maps a container port to a host port.

type PortMapping

type PortMapping struct {
	ContainerPort int    `json:"container_port"`
	Protocol      string `json:"protocol"`
	HostPort      int    `json:"host_port,omitempty"`
}

type RegistryAuth

type RegistryAuth struct {
	Server   string // registry host, e.g. registry-1.docker.io, ghcr.io
	Username string
	Password string
}

RegistryAuth holds credentials for pulling from a private registry.

type RunSpec

type RunSpec struct {
	Name           string
	Image          string
	Hostname       string   // container hostname (uname -n); blank = Docker default
	Env            []string // KEY=VALUE
	Entrypoint     []string // optional entrypoint override
	Cmd            []string // optional command override
	WorkingDir     string
	Labels         map[string]string
	Networks       []string // networks to attach
	NetworkMode    string
	NetworkAliases []string
	// Exposes the service name on the stack network without leaking it onto the shared gateway network.
	AliasesByNetwork map[string][]string
	// Ports maps "containerPort/proto" -> "hostPort" (e.g. "80/tcp" -> "8080").
	Ports map[string]string
	// Keys match Ports; a missing or empty entry means all interfaces.
	PortBindIPs map[string]string
	// Mounts maps volume name -> container path.
	Mounts map[string]string
	// Copy-up would re-apply the image's ownership on every start, undoing the restricted-profile chown.
	NoCopyVolumes bool
	// A container that only reads the data it archives should not hold a writable handle to it.
	ReadOnlyMounts []string
	// Only for allow-listed privileged mounts; the source is server-resolved, never client input.
	Binds []BindMount
	// Resource limits (0 = unlimited).
	MemoryBytes int64
	NanoCPUs    int64
	// Count -1 means all GPUs (used by the inventory probe).
	GPUs []GPURequest
	// Empty defaults to "unless-stopped".
	RestartPolicy string
	// Healthcheck is the container health probe; nil disables it.
	Healthcheck     *HealthcheckSpec
	User            string
	NoNewPrivileges bool
	CapDrop         []string
	// Allow-listed before reaching here (models.NormalizeCapabilities / NormalizeDevices).
	CapAdd  []string
	Devices []string
	// ReadOnlyRootfs mounts the container's root filesystem read-only (--read-only).
	ReadOnlyRootfs bool
	// Needed for the docker group so a non-root control plane can read the socket, like compose's group_add.
	GroupAdd []string
	// Written between create and start, so no host path or distribution is needed; re-applied on every deploy.
	Files []FileEntry
}

RunSpec describes a container to create and start.

type Volume

type Volume struct {
	Name       string            `json:"name"`
	Driver     string            `json:"driver"`
	Mountpoint string            `json:"mountpoint"`
	CreatedAt  string            `json:"created_at,omitempty"`
	Labels     map[string]string `json:"labels,omitempty"`
}

Volume summarizes a Docker volume.

Jump to

Keyboard shortcuts

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