Documentation
¶
Overview ¶
Package docker is the stack engine's Docker seam; no Docker SDK types cross it.
Index ¶
- Constants
- Variables
- func IsManaged(labels map[string]string) bool
- func IsPlatformInfra(labels map[string]string) bool
- func IsPlatformNetwork(labels map[string]string) bool
- func IsPlatformStack(labels map[string]string) bool
- func IsProtected(labels map[string]string) bool
- func IsReservedLabelKey(key string) bool
- func IsRootless(securityOptions []string) bool
- func LabelValue(labels map[string]string, key string) (value string, ok bool)
- func ManagedBy(labels map[string]string) string
- func PlatformLabels(role, managedBy string, extra map[string]string) map[string]string
- func SanitizeUserLabels(in map[string]string) map[string]string
- func WorkspaceID(labels map[string]string) (id uint, ok bool)
- type BindMount
- type Client
- type Container
- type ContainerConfig
- type ContainerMount
- type ContainerNetwork
- type FileEntry
- type GPURequest
- type HealthcheckSpec
- type NetworkSpec
- type NetworkState
- type Port
- type PortMapping
- type RegistryAuth
- type RunSpec
- type Volume
Constants ¶
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.
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 )
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.
const ManagedLabel = LabelManaged
const PartOfMiabi = "miabi"
Variables ¶
var ErrNotFound = errors.New("docker: resource not found")
Functions ¶
func IsPlatformInfra ¶
func IsPlatformNetwork ¶ added in v1.10.6
The labels are the test, never the name; name-only callers must resolve and match the id too.
func IsPlatformStack ¶
func IsProtected ¶
Infra means "do not reclaim as an orphan"; protected means "do not let a human break it by accident".
func IsReservedLabelKey ¶
func IsRootless ¶ added in v1.10.22
IsRootless reports whether a daemon's `docker info` security options mark it rootless.
func PlatformLabels ¶
Use it so a component can never be half-labeled; extra may not override the four keys set here.
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 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 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
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 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.