docker

package
v1.10.17 Latest Latest
Warning

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

Go to latest
Published: Oct 12, 2026 License: AGPL-3.0 Imports: 33 Imported by: 0

Documentation

Overview

Package docker is the sole adapter over the Docker Engine SDK. Services depend on the Client interface (not the SDK), keeping the rest of the codebase free of Docker SDK types.

Index

Constants

View Source
const (
	ConfigWorkspaceLabel = "io.miabi.workspace"
	ConfigNameLabel      = "io.miabi.config"
	ConfigKeyLabel       = "io.miabi.config-key"
	ConfigDigestLabel    = "io.miabi.digest"
)

Config object labels. Ownership is recorded on the object itself so GC and a re-import can identify what a config belongs to without consulting the DB.

View Source
const (
	// MinAPIVersion is the lowest Docker Engine API version the moby SDK client
	// can negotiate at all; a daemon below it is refused by the client itself.
	// This is the hard technical floor, distinct from the product minimum below.
	MinAPIVersion = "1.40"
	// MinEngineVersion is the minimum Docker Engine release Miabi SUPPORTS — the
	// number quoted by the README, installer, admin UI and changelog, and the
	// threshold the Nodes warning badge uses. It is the floor of the tested CI
	// engine matrix (25-29). The SDK's own floor (MinAPIVersion / Docker
	// 19.03) is well below it, so the client never limits a supported node.
	MinEngineVersion = "25.0"
)
View Source
const (
	LabelPrefix            = stackdocker.LabelPrefix
	LabelApp               = stackdocker.LabelApp
	LabelDeployment        = stackdocker.LabelDeployment
	LabelDatabase          = stackdocker.LabelDatabase
	LabelStack             = stackdocker.LabelStack
	LabelVolume            = stackdocker.LabelVolume
	LabelJob               = stackdocker.LabelJob
	LabelRole              = stackdocker.LabelRole
	LabelNode              = stackdocker.LabelNode
	LabelWorkspace         = stackdocker.LabelWorkspace
	LabelManaged           = stackdocker.LabelManaged
	LabelPipelineRun       = stackdocker.LabelPipelineRun
	LabelSizeBytes         = stackdocker.LabelSizeBytes
	LabelPartOf            = stackdocker.LabelPartOf
	LabelManagedBy         = stackdocker.LabelManagedBy
	LabelProtected         = stackdocker.LabelProtected
	LabelSpecHash          = stackdocker.LabelSpecHash
	RoleControlPlane       = stackdocker.RoleControlPlane
	RolePlatformDB         = stackdocker.RolePlatformDB
	RolePlatformCache      = stackdocker.RolePlatformCache
	RoleGateway            = stackdocker.RoleGateway
	RoleAgent              = stackdocker.RoleAgent
	RoleControlPlaneWorker = stackdocker.RoleControlPlaneWorker
	RoleNodeGateway        = stackdocker.RoleNodeGateway
	RoleNodeGatewayRedis   = stackdocker.RoleNodeGatewayRedis
	RolePlatformInternal   = stackdocker.RolePlatformInternal
	RoleProxyNetwork       = stackdocker.RoleProxyNetwork
	RoleMetadataGuard      = stackdocker.RoleMetadataGuard
	RoleRegistry           = stackdocker.RoleRegistry
	RoleRegistryGC         = stackdocker.RoleRegistryGC
	ManagedByCompose       = stackdocker.ManagedByCompose
	ManagedByMiabi         = stackdocker.ManagedByMiabi
	ManagedByExternal      = stackdocker.ManagedByExternal
	PartOfMiabi            = stackdocker.PartOfMiabi
	ManagedLabel           = stackdocker.ManagedLabel
)
View Source
const SwarmServiceNameLabel = "com.docker.swarm.service.name"

SwarmServiceNameLabel is Docker's own label on a swarm task's container, naming the service that owns it. Swarm recreates such a container the moment it is removed, so it is the handle onto the only thing that can actually be reclaimed: the service.

Variables

View Source
var (
	PlatformLabels     = stackdocker.PlatformLabels
	IsPlatformStack    = stackdocker.IsPlatformStack
	IsProtected        = stackdocker.IsProtected
	ManagedBy          = stackdocker.ManagedBy
	LabelValue         = stackdocker.LabelValue
	IsManaged          = stackdocker.IsManaged
	IsPlatformInfra    = stackdocker.IsPlatformInfra
	IsPlatformNetwork  = stackdocker.IsPlatformNetwork
	IsReservedLabelKey = stackdocker.IsReservedLabelKey
	SanitizeUserLabels = stackdocker.SanitizeUserLabels
	WorkspaceID        = stackdocker.WorkspaceID
)
View Source
var ErrEngineTooOld = errors.New("docker: engine too old")

ErrEngineTooOld is returned when the daemon's API version is below the minimum the Docker SDK client supports (MinAPIVersion). The client cannot talk to such a daemon at all, so this is surfaced as a clear Miabi error rather than an obscure SDK "invalid argument" deep in a deploy log.

View Source
var ErrNotFound = stackdocker.ErrNotFound

ErrNotFound is returned when a container/image/volume does not exist. ErrNotFound is owned by the stack seam so both sides compare against one value.

Functions

func NetworkRefMatches added in v1.10.6

func NetworkRefMatches(n Network, ref string) bool

NetworkRefMatches reports whether ref names this network: its name, its full id, or the short id Docker prints. A guard that compares the name alone is bypassed by passing the id, which the engine accepts everywhere a name is accepted.

Types

type Attached added in v1.10.9

type Attached interface {
	io.ReadWriter
	// CloseWrite ends the container's stdin, which is how a consumer like pg_restore learns the input is done.
	CloseWrite() error
	// Wait blocks until the container exits and returns its exit code.
	Wait(ctx context.Context) (int, error)
	// Stderr is the tail of what the container wrote to stderr.
	Stderr() string
	// Close detaches and removes the container.
	Close() error
}

Attached is a container whose stdio is wired to the caller: writes go to its stdin, reads come from its demultiplexed stdout, and stderr is kept (bounded) for error messages.

type BindMount

type BindMount = stackdocker.BindMount

The types the stack engine also speaks are owned by the stack module and aliased here, so both sides use one definition — Go's structural typing needs identical named types for Client to satisfy stackdocker.Client. Aliases are transparent, so every call site is unaffected.

type Capabilities added in v1.9.6

type Capabilities struct {
	// APIVersion is the Docker Engine API version the client negotiated with this
	// daemon (e.g. "1.51"). A daemon below MinAPIVersion is refused before this.
	APIVersion string `json:"api_version"`
	// EngineVersion is the daemon's reported server version (e.g. "27.5.1").
	EngineVersion string `json:"engine_version"`
	// OS / Arch are the daemon's platform ("linux", "x86_64"/"aarch64").
	OS   string `json:"os"`
	Arch string `json:"arch"`
	// SwarmActive is true when the engine is in swarm mode; SwarmManager is true
	// when it is also a reachable manager (can drive cluster operations).
	SwarmActive  bool `json:"swarm_active"`
	SwarmManager bool `json:"swarm_manager"`
}

Capabilities is a snapshot of what the connected engine supports, derived from Ping + Info. It is what the node engine-version preflight reads to decide whether a daemon is too old, GPU-capable, or a reachable swarm manager.

type Client

type Client interface {
	// Ping verifies the daemon is reachable.
	Ping(ctx context.Context) error
	// Info returns engine information.
	Info(ctx context.Context) (Info, error)
	// Capabilities reports what the connected engine supports (API/engine
	// version, OS/arch, swarm state), derived from Ping + Info in one round-trip.
	// Returns ErrEngineTooOld if the daemon is below MinAPIVersion.
	Capabilities(ctx context.Context) (Capabilities, error)

	ListContainers(ctx context.Context, all bool) ([]Container, error)
	InspectContainer(ctx context.Context, id string) (Container, error)
	// InspectContainerConfig returns the full runtime configuration of a container
	// (env, mounts, command, limits, restart policy) for adopting it as an app.
	InspectContainerConfig(ctx context.Context, id string) (ContainerConfig, error)
	RunContainer(ctx context.Context, spec RunSpec) (string, error)
	StartContainer(ctx context.Context, id string) error
	StopContainer(ctx context.Context, id string, timeoutSeconds int) error
	RestartContainer(ctx context.Context, id string, timeoutSeconds int) error
	RemoveContainer(ctx context.Context, id string, force bool) error

	// RunOneShot runs a container to completion and returns its exit code and
	// combined logs, then removes it. Used for backup/restore jobs.
	RunOneShot(ctx context.Context, spec RunSpec) (exitCode int, logs string, err error)

	// RunOneShotStream runs a container to completion like RunOneShot, but streams
	// its combined output to sink line-by-line as it runs (live logs) instead of
	// returning the buffered logs. Used by the buildpack build provider.
	RunOneShotStream(ctx context.Context, spec RunSpec, sink func(LogLine) error) (exitCode int, err error)

	// ReadContainerFile reads a single file at path from inside a container's
	// filesystem (size-capped). Used to copy an imported gateway's config.
	ReadContainerFile(ctx context.Context, containerID, path string) ([]byte, error)

	// CopyFileFromVolume reads a single file from a named volume by mounting it into a short-lived
	// (never started) helper container created from image. The returned reader must be closed by the
	// caller; closing it also removes the helper container.
	CopyFileFromVolume(ctx context.Context, volume, image, file string) (rc io.ReadCloser, size int64, err error)

	// CopyToVolume streams content (a tar-able single file of the given size) into
	// name inside a named volume, by mounting it into a short-lived helper. Used
	// to land an uploaded dump on a node's backup volume. image must be present.
	CopyToVolume(ctx context.Context, volume, image, name string, content io.Reader, size int64) error

	// DialNetwork opens a raw TCP byte stream to host:port as reachable from containers on the given
	// Docker network, via an ephemeral socat relay bridged over the engine connection — so it works
	// the same locally and tunneled, with no published host port. Closing the conn removes the relay.
	DialNetwork(ctx context.Context, network, image, host string, port int) (net.Conn, error)

	// RunAttached starts a container with its stdin, stdout and stderr wired to the returned stream, for
	// piping data between engines without buffering it. Close removes the container.
	RunAttached(ctx context.Context, spec RunSpec) (Attached, error)

	// Images. auth may be nil for anonymous (public) pulls.
	PullImage(ctx context.Context, ref string, auth *RegistryAuth) error
	// TagImage adds target as an additional tag for the local source image.
	TagImage(ctx context.Context, source, target string) error
	// PushImage pushes a local image ref to its registry. auth may be nil.
	PushImage(ctx context.Context, ref string, auth *RegistryAuth) error
	// BuildImage builds an image from a local context directory, streaming
	// build output to sink, and tags it.
	BuildImage(ctx context.Context, contextDir, dockerfile, tag string, sink func(LogLine) error) error
	// InspectImage returns a local image's identity (ID + digest) and size.
	InspectImage(ctx context.Context, ref string) (ImageInspect, error)
	// ImageExists reports whether ref is present locally (no pull).
	ImageExists(ctx context.Context, ref string) (bool, error)
	// RemoveImage deletes a local image by reference (tag or id). force removes
	// it even if tagged/referenced; a not-found image is treated as success.
	RemoveImage(ctx context.Context, ref string, force bool) error

	// Housekeeping (reclaim & report). ListImages enumerates local images with usage signals;
	// DiskUsage is a `docker system df`-style breakdown. The Prune* calls target only the safe set
	// (dangling images, build cache); callers apply their own managed-resource guards on top.
	ListImages(ctx context.Context) ([]Image, error)
	DiskUsage(ctx context.Context) (DiskUsage, error)
	VolumeUsage(ctx context.Context) ([]VolumeUsage, error)
	PruneImages(ctx context.Context, opts PruneImagesOptions) (PruneReport, error)
	PruneBuildCache(ctx context.Context) (PruneReport, error)

	// StreamEvents streams Docker daemon events for Miabi-managed
	// containers until the context is cancelled or an error occurs.
	StreamEvents(ctx context.Context, sink func(EngineEvent) error) error

	// Exec starts an interactive command inside a running container and returns
	// a bidirectional stream to it (used for the in-panel shell). Callers must
	// Close the returned stream.
	Exec(ctx context.Context, containerID string, opts ExecOptions) (ExecStream, error)

	// Top lists the running processes in a container (the "docker top" view).
	// psArgs are ps flags (e.g. "aux"); blank uses the daemon default. Read-only.
	Top(ctx context.Context, containerID, psArgs string) (ProcessList, error)

	// The sink is invoked per item; return a non-nil error to stop.
	StreamLogs(ctx context.Context, id string, follow bool, tail string, sink func(LogLine) error) error
	StreamStats(ctx context.Context, id string, sink func(StatsSample) error) error
	// StatsOnce returns a single resource-usage sample.
	StatsOnce(ctx context.Context, id string) (StatsSample, error)

	EnsureNetwork(ctx context.Context, name string) (string, error)
	CreateNetwork(ctx context.Context, name, driver string, internal bool) (string, error)
	// CreateNetworkSpec creates a managed network with explicit options, including an optional
	// Miabi-allocated IPAM Subnet/Gateway so creation does not draw from Docker's small built-in
	// pools. Always creates (errors if the name exists); EnsureNetworkSpec is the create-or-reuse variant.
	CreateNetworkSpec(ctx context.Context, spec NetworkSpec) (string, error)
	EnsureNetworkSpec(ctx context.Context, spec NetworkSpec) (string, error)
	RemoveNetwork(ctx context.Context, name string) error
	ListNetworks(ctx context.Context) ([]Network, error)
	// NetworkConnect attaches a running container to a network with optional DNS aliases;
	// NetworkDisconnect detaches it. Both are idempotent. Used to keep only route-exposed apps on
	// the shared reverse-proxy network.
	NetworkConnect(ctx context.Context, name, containerID string, aliases []string) error
	NetworkDisconnect(ctx context.Context, name, containerID string, force bool) error
	CreateVolume(ctx context.Context, name string, labels map[string]string, sizeBytes int64) (Volume, error)
	// CreateVolumeWith creates a managed volume with an explicit driver and driver
	// options (shared storage: nfs/cifs). An empty Driver uses the local default.
	CreateVolumeWith(ctx context.Context, spec VolumeSpec) (Volume, error)
	ListVolumes(ctx context.Context) ([]Volume, error)
	InspectVolume(ctx context.Context, name string) (Volume, error)
	RemoveVolume(ctx context.Context, name string, force bool) error

	// Swarm. Miabi drives Docker Swarm as an internal detail of cluster mode; users never run
	// docker swarm/service themselves. Swarm reads the engine's swarm state from `docker info`; the
	// rest require a reachable manager and are no-ops on plain Docker.
	Swarm(ctx context.Context) (SwarmInfo, error)
	SwarmInit(ctx context.Context, req SwarmInitRequest) (nodeID string, err error)
	SwarmJoin(ctx context.Context, req SwarmJoinRequest) error
	SwarmLeave(ctx context.Context, force bool) error
	SwarmJoinTokens(ctx context.Context) (SwarmJoinTokens, error)
	SwarmNodes(ctx context.Context) ([]SwarmNode, error)
	SwarmNodeRemove(ctx context.Context, nodeID string, force bool) error
	// SwarmNodeAvailability sets a node's scheduling availability (active | pause |
	// drain). Drain is what makes a node safe to reboot — it reschedules the node's
	// tasks away instead of letting Swarm keep placing onto a host that is going down.
	SwarmNodeAvailability(ctx context.Context, nodeID, availability string) error
	SwarmNodeSetLabel(ctx context.Context, nodeID, key, value string) error
	// SwarmTasks lists the swarm's tasks (all, or one node's). Only the manager can:
	// the containers live on the nodes, which Miabi may hold no Docker client for.
	SwarmTasks(ctx context.Context, nodeID string) ([]SwarmTask, error)

	// Swarm services (cluster apps). Require a reachable manager; cluster deploys
	// call these instead of RunContainer. CreateOverlayNetwork ensures the
	// per-workspace overlay an app's service attaches to.
	ServiceCreate(ctx context.Context, spec ServiceSpec) (id string, err error)
	ServiceUpdate(ctx context.Context, idOrName string, spec ServiceSpec) error
	ServiceRemove(ctx context.Context, idOrName string) error
	ServiceScale(ctx context.Context, idOrName string, replicas uint64) error
	ServiceSetEndpointMode(ctx context.Context, idOrName, mode string) error
	ServiceSetIngressNetwork(ctx context.Context, idOrName, network, alias string, attached bool) error
	ServiceInspect(ctx context.Context, idOrName string) (ServiceStatus, error)

	// Swarm config objects backing kind: Config on a replicated service.
	EnsureConfig(ctx context.Context, obj ConfigObject) (string, error)
	ListManagedConfigs(ctx context.Context) ([]ConfigInfo, error)
	RemoveConfig(ctx context.Context, id string) error
	ServiceList(ctx context.Context) ([]ServiceStatus, error)
	// ServiceRestart forces a rolling restart of a service's tasks in place.
	ServiceRestart(ctx context.Context, idOrName string) error
	// ServiceTaskContainerID resolves a running task container of the named
	// service on this engine, for logs/stats/exec/top. ErrNotFound if none here.
	ServiceTaskContainerID(ctx context.Context, serviceName string) (string, error)
	// ServiceEnv returns a service's environment. It can carry secrets, so it is for
	// the service layer to inspect — never to return to a client.
	ServiceEnv(ctx context.Context, idOrName string) ([]string, error)
	// StreamServiceLogs streams a swarm service's logs from the MANAGER, aggregated across every
	// task. This is the only way to read the logs of a task on a swarm node Miabi has no Docker
	// client for — the manager pulls them over the swarm control plane.
	StreamServiceLogs(ctx context.Context, serviceName string, follow bool, tail string, sink func(LogLine) error) error
	CreateOverlayNetwork(ctx context.Context, name string) (id string, err error)

	// Close releases the underlying connection.
	Close() error
}

Client is the abstraction the rest of the app depends on.

func New

func New() (Client, error)

New connects to the Docker engine using the standard environment (DOCKER_HOST etc.) with API version negotiation.

func NewRemote

func NewRemote(dial DialFunc) (Client, error)

NewRemote builds a Docker client that talks to a remote engine over an arbitrary transport (the agent tunnel), reusing engineClient so every service works against a remote node unchanged. The dummy "http://" host makes the SDK speak plain HTTP; the dialer returns a tunnel stream.

func NewSocket

func NewSocket(host string) (Client, error)

NewSocket connects to a Docker engine at a socket/host string (e.g. "unix:///var/run/docker.sock" or "tcp://host:2375" without TLS).

func NewTCP

func NewTCP(host string, tlsm *TLSMaterial) (Client, error)

NewTCP connects to a Docker engine over TCP. With tlsm == nil the connection is plaintext; otherwise it uses TLS (server verification, plus client auth if Cert+Key are present). host is e.g. "tcp://host:2376".

func Offline

func Offline(err error) Client

Offline returns a Client whose every operation fails with err, so a node-aware caller can resolve a client unconditionally: critical operations surface the error while best-effort cleanups simply no-op when a node's agent is disconnected.

type ConfigInfo added in v1.8.1

type ConfigInfo struct {
	ID        string
	Name      string
	Workspace string
	Config    string
	CreatedAt time.Time
}

ConfigInfo is a published config object, as GC sees it.

type ConfigObject added in v1.8.1

type ConfigObject struct {
	Workspace string // workspace uid
	Config    string // config resource name
	Key       string // file key within the config
	Digest    string // digest12 of the projected file (content + mode)
	Content   string
}

ConfigObject is one docker config to publish for a swarm task.

func (ConfigObject) ObjectName added in v1.8.1

func (c ConfigObject) ObjectName() string

ObjectName is the docker object name: content-addressed, so a content change yields a new object and the service update swaps it rather than mutating one in place (docker configs are immutable by design).

type Container

type Container = stackdocker.Container

The types the stack engine also speaks are owned by the stack module and aliased here, so both sides use one definition — Go's structural typing needs identical named types for Client to satisfy stackdocker.Client. Aliases are transparent, so every call site is unaffected.

type ContainerConfig

type ContainerConfig = stackdocker.ContainerConfig

The types the stack engine also speaks are owned by the stack module and aliased here, so both sides use one definition — Go's structural typing needs identical named types for Client to satisfy stackdocker.Client. Aliases are transparent, so every call site is unaffected.

type ContainerMount

type ContainerMount = stackdocker.ContainerMount

The types the stack engine also speaks are owned by the stack module and aliased here, so both sides use one definition — Go's structural typing needs identical named types for Client to satisfy stackdocker.Client. Aliases are transparent, so every call site is unaffected.

type ContainerNetwork

type ContainerNetwork = stackdocker.ContainerNetwork

The types the stack engine also speaks are owned by the stack module and aliased here, so both sides use one definition — Go's structural typing needs identical named types for Client to satisfy stackdocker.Client. Aliases are transparent, so every call site is unaffected.

type DialFunc

type DialFunc func(ctx context.Context) (net.Conn, error)

DialFunc opens a new connection to a remote Docker engine. For multi-node, it returns a fresh stream over the node's agent tunnel; each Docker API request gets its own stream so streaming endpoints (logs/stats/events/build) work.

type DiskUsage

type DiskUsage struct {
	Images     DiskUsageCategory `json:"images"`
	Containers DiskUsageCategory `json:"containers"`
	Volumes    DiskUsageCategory `json:"volumes"`
	BuildCache DiskUsageCategory `json:"build_cache"`
	// VolumeItems is the per-volume breakdown behind Volumes. The daemon walks the filesystem for
	// the totals either way, so it is free here; it is not serialized, as callers reporting a node's
	// disk want the totals, not a row per volume.
	VolumeItems []VolumeUsage `json:"-"`
}

DiskUsage is a `docker system df`-style breakdown for a node: per-category counts and total vs reclaimable bytes. It drives the housekeeping report.

type DiskUsageCategory

type DiskUsageCategory struct {
	Count       int   `json:"count"`
	Active      int   `json:"active"`
	TotalBytes  int64 `json:"total_bytes"`
	Reclaimable int64 `json:"reclaimable_bytes"`
}

DiskUsageCategory is one row of the disk-usage breakdown. Reclaimable is an upper-bound estimate (it ignores layer sharing between images), matching how `docker system df` reports it.

type EngineEvent

type EngineEvent struct {
	Action      string // start, die, oom, kill, stop, "health_status: healthy", ...
	ContainerID string
	Attributes  map[string]string
}

EngineEvent is a Docker daemon event for a managed container. Attributes carries the container's labels (e.g. "io.miabi.app") and event metadata (e.g. "exitCode").

type ExecOptions

type ExecOptions struct {
	Cmd []string // command + args; e.g. ["/bin/sh"]
	Tty bool     // allocate a pseudo-TTY (raw, un-multiplexed stream)
	Env []string // extra environment, "KEY=VALUE"
}

ExecOptions configures an interactive command run inside a running container.

type ExecStream

type ExecStream interface {
	Read(p []byte) (int, error)
	Write(p []byte) (int, error)
	Resize(ctx context.Context, height, width uint) error
	Close() error
}

ExecStream is a bidirectional stream attached to a running exec instance. With a TTY the byte stream is raw (no stdcopy multiplexing), so Read/Write move terminal bytes directly. Resize adjusts the pseudo-terminal; Close ends the session.

type FileEntry added in v1.8.1

type FileEntry = stackdocker.FileEntry

The types the stack engine also speaks are owned by the stack module and aliased here, so both sides use one definition — Go's structural typing needs identical named types for Client to satisfy stackdocker.Client. Aliases are transparent, so every call site is unaffected.

type GPURequest added in v1.2.0

type GPURequest = stackdocker.GPURequest

The types the stack engine also speaks are owned by the stack module and aliased here, so both sides use one definition — Go's structural typing needs identical named types for Client to satisfy stackdocker.Client. Aliases are transparent, so every call site is unaffected.

type HealthcheckSpec

type HealthcheckSpec = stackdocker.HealthcheckSpec

The types the stack engine also speaks are owned by the stack module and aliased here, so both sides use one definition — Go's structural typing needs identical named types for Client to satisfy stackdocker.Client. Aliases are transparent, so every call site is unaffected.

type Image

type Image struct {
	ID          string            `json:"id"`
	RepoTags    []string          `json:"repo_tags,omitempty"`
	RepoDigests []string          `json:"repo_digests,omitempty"`
	Size        int64             `json:"size"`
	SharedSize  int64             `json:"shared_size"`
	Created     int64             `json:"created"`
	Containers  int64             `json:"containers"` // -1 when the daemon did not compute it
	Dangling    bool              `json:"dangling"`   // untagged (<none>:<none>)
	Labels      map[string]string `json:"labels,omitempty"`
}

Image summarizes a local Docker image, with the references and usage signals the housekeeping report needs (whether a container uses it, whether it is dangling/untagged).

type ImageInspect

type ImageInspect struct {
	ID     string `json:"id"`     // content-addressable image ID (sha256:…)
	Digest string `json:"digest"` // repo digest when present, else the image ID
	Size   int64  `json:"size"`
}

ImageInspect is a built or pulled image's identity and size. Digest is the registry repo-digest when the image carries one; for a locally-built, never-pushed image it falls back to the content-addressable image ID, a stable local handle for deploy-by-digest on a single node.

type Info

type Info struct {
	// Name is the Docker host's hostname (the actual machine name, not the
	// Miabi container's), as reported by the daemon.
	Name          string `json:"name"`
	Version       string `json:"version"`
	APIVersion    string `json:"api_version"`
	OS            string `json:"os"`
	Arch          string `json:"arch"`
	Containers    int    `json:"containers"`
	ContainersRun int    `json:"containers_running"`
	Images        int    `json:"images"`
	CPUs          int    `json:"cpus"`
	MemTotal      int64  `json:"mem_total"`
	// DataRoot is where the daemon keeps images, containers and volumes. Sizing the filesystem
	// behind it is how a node's storage capacity is measured.
	DataRoot string `json:"data_root,omitempty"`
	// Runtimes are the container runtimes the daemon advertises (docker info). The "nvidia" key is
	// present exactly when the NVIDIA Container Toolkit is installed, so it is how the control plane
	// decides a node is GPU-capable before ever probing it.
	Runtimes []string `json:"runtimes,omitempty"`
}

Info summarizes the Docker engine.

type LogLine

type LogLine struct {
	Stream string `json:"stream"` // "stdout" | "stderr"
	Text   string `json:"text"`
}

LogLine is a single demultiplexed log line.

type Network

type Network struct {
	ID     string            `json:"id"`
	Name   string            `json:"name"`
	Driver string            `json:"driver"`
	Scope  string            `json:"scope"`
	Labels map[string]string `json:"labels,omitempty"`
	// Subnet is the network's first IPv4 IPAM subnet (CIDR), empty if unset. Used by the
	// subnet allocator to reserve pool subnets already in use by existing networks.
	Subnet  string `json:"subnet,omitempty"`
	Gateway string `json:"gateway,omitempty"`
	// IPv6Subnet and IPv6Gateway are the v6 half of a dual-stack network, empty on an IPv4-only one.
	// EnableIPv6 is what the daemon reports, which is the honest answer for a network created before
	// Miabi set the flag explicitly.
	IPv6Subnet  string `json:"ipv6_subnet,omitempty"`
	IPv6Gateway string `json:"ipv6_gateway,omitempty"`
	EnableIPv6  bool   `json:"enable_ipv6"`
}

Network summarizes a Docker network.

type NetworkSpec

type NetworkSpec = stackdocker.NetworkSpec

The types the stack engine also speaks are owned by the stack module and aliased here, so both sides use one definition — Go's structural typing needs identical named types for Client to satisfy stackdocker.Client. Aliases are transparent, so every call site is unaffected.

type Port

type Port = stackdocker.Port

The types the stack engine also speaks are owned by the stack module and aliased here, so both sides use one definition — Go's structural typing needs identical named types for Client to satisfy stackdocker.Client. Aliases are transparent, so every call site is unaffected.

type PortMapping

type PortMapping = stackdocker.PortMapping

The types the stack engine also speaks are owned by the stack module and aliased here, so both sides use one definition — Go's structural typing needs identical named types for Client to satisfy stackdocker.Client. Aliases are transparent, so every call site is unaffected.

type ProcessList

type ProcessList struct {
	Titles    []string   `json:"titles"`
	Processes [][]string `json:"processes"`
}

ProcessList is the running processes in a container (the "docker top" view): column titles and one row of cells per process. Sourced from the host's ps, so it works even for images that ship no ps binary.

type PruneImagesOptions

type PruneImagesOptions struct {
	Dangling bool
	Until    string
}

type PruneReport

type PruneReport struct {
	ItemsDeleted   []string `json:"items_deleted,omitempty"`
	SpaceReclaimed int64    `json:"space_reclaimed"`
}

PruneReport is the outcome of a prune: what was removed and the bytes freed.

type RegistryAuth

type RegistryAuth = stackdocker.RegistryAuth

The types the stack engine also speaks are owned by the stack module and aliased here, so both sides use one definition — Go's structural typing needs identical named types for Client to satisfy stackdocker.Client. Aliases are transparent, so every call site is unaffected.

type RunSpec

type RunSpec = stackdocker.RunSpec

The types the stack engine also speaks are owned by the stack module and aliased here, so both sides use one definition — Go's structural typing needs identical named types for Client to satisfy stackdocker.Client. Aliases are transparent, so every call site is unaffected.

type ServiceBind

type ServiceBind struct {
	Source   string // host path (present on every node)
	Target   string // container path
	ReadOnly bool
}

ServiceBind is a host-path bind mount for a swarm service task (mount.TypeBind).

type ServiceConfig added in v1.8.1

type ServiceConfig struct {
	ID   string
	Name string
	Path string
	Mode uint32
}

buildSwarmServiceSpec maps a Miabi ServiceSpec to the Docker SDK spec. ServiceConfig attaches one docker config object at a path inside the task.

type ServiceMountDriver

type ServiceMountDriver struct {
	Name    string
	Options map[string]string
}

ServiceMountDriver is the Docker volume driver config for a service mount, so every node a task lands on materializes the SAME backing volume rather than an empty local one. Name is the driver ("local" for Miabi's nfs/cifs); Options are the mount options (type, device, o, ...).

type ServiceSpec

type ServiceSpec struct {
	Name     string
	Image    string
	Env      []string // KEY=VALUE
	Cmd      []string // command args (ContainerSpec.Args); nil keeps the image default
	Replicas uint64   // 0 is treated as 1 (ignored when Global)
	// Global runs exactly one task on EVERY node the constraints allow, including
	// nodes that join later. It is how a per-node daemon is deployed to a swarm
	// without touching each host: the scheduler ships it, and keeps shipping it.
	Global         bool
	Networks       []string          // swarm-scoped (overlay) network names to attach
	NetworkAliases []string          // DNS aliases applied on each attached network
	Mounts         map[string]string // volume name -> container path
	// MountDrivers carries the volume driver config for a mount, keyed by source name. REQUIRED for
	// shared (nfs/cifs) volumes on a replicated service: without it a task on a node lacking the
	// volume makes an empty *local* one instead, so the "shared" storage silently diverges per node.
	MountDrivers map[string]ServiceMountDriver
	// Binds are host-path bind mounts for operator-managed storage present at the SAME path on every
	// node (a host-path volume under /mnt/*). Unlike Mounts they need no driver config — the path is
	// assumed present on each node the scheduler places a task on.
	Binds []ServiceBind
	// Configs are docker config objects attached as files. Swarm distributes them
	// over raft, so a task lands with its files on whichever node it schedules to.
	Configs     []ServiceConfig
	Labels      map[string]string
	MemoryBytes int64
	NanoCPUs    int64
	// Constraints are Swarm placement constraints, e.g. "node.role==worker" or
	// "node.id==abc" (pin to a node).
	Constraints []string
	Healthcheck *HealthcheckSpec
	User        string
	CapAdd      []string
	CapDrop     []string
	// NoNewPrivileges and ReadOnlyRootfs harden each task the way RunSpec hardens a container.
	NoNewPrivileges bool
	ReadOnlyRootfs  bool
	// Rolling update tuning (0 = Swarm defaults).
	UpdateParallelism uint64
	UpdateDelay       time.Duration
	// RegistryAuth authenticates the swarm to a private registry and is distributed to worker nodes
	// so their tasks can pull too (the daemon equivalent of --with-registry-auth). Required for the
	// built-in registry and any private one — without it a worker task fails to pull. nil if public.
	RegistryAuth *RegistryAuth
	// IngressNetwork is an additional attachable overlay the service joins with only IngressAlias
	// registered on it. Kept separate from Networks so tenant-scoped east-west aliases are NOT
	// registered on this shared network, where they would collide across workspaces. Empty disables it.
	IngressNetwork string
	IngressAlias   string
	// EndpointMode is "vip" (the default: one IPVS-balanced virtual IP) or "dnsrr" (the name resolves to the task
	// addresses, for hosts that cannot program IPVS).
	EndpointMode string
}

ServiceSpec describes a replicated Swarm service to create or update — the cluster-mode analogue of RunSpec: same image/env/mounts/limits, plus replicas, placement constraints and rolling-update tuning. Swarm schedules the tasks and load-balances a virtual IP across them.

type ServiceStatus

type ServiceStatus struct {
	ID           string `json:"id"`
	Name         string `json:"name"`
	Image        string `json:"image,omitempty"`
	Replicas     uint64 `json:"replicas"`      // desired
	RunningTasks uint64 `json:"running_tasks"` // currently running
	// Placement maps a swarm node id -> the count of this service's tasks running
	// on that node. Populated by ServiceInspect so callers can show where the
	// scheduler actually placed the replicas (nil until inspected).
	Placement map[string]int `json:"placement,omitempty"`
	// StartedAt (RFC3339) is when the service's longest-running task entered the running state. It
	// comes from the swarm control plane, so it is known even for a task on a node Miabi has no
	// Docker client for, where inspecting the container is impossible.
	StartedAt string `json:"started_at,omitempty"`
}

ServiceStatus summarizes a Swarm service: its identity, desired replica count, and how many tasks are currently running (used to gate a deploy on convergence).

type StatsSample

type StatsSample struct {
	CPUPercent     float64 `json:"cpu_percent"`
	MemoryUsage    uint64  `json:"memory_usage_bytes"`
	MemoryLimit    uint64  `json:"memory_limit_bytes"`
	MemoryPercent  float64 `json:"memory_percent"`
	NetworkRxBytes uint64  `json:"network_rx_bytes"`
	NetworkTxBytes uint64  `json:"network_tx_bytes"`
}

StatsSample is a point-in-time resource usage sample for a container.

type SwarmInfo

type SwarmInfo struct {
	// LocalNodeState is the engine's swarm state: inactive | pending | active |
	// error | locked. "inactive" means plain (non-swarm) Docker.
	LocalNodeState string `json:"local_node_state"`
	// ControlAvailable is true when this engine is a reachable swarm manager
	// (i.e. it can drive cluster operations).
	ControlAvailable bool `json:"control_available"`
	// NodeID / NodeAddr identify this engine within the swarm; NodeAddr is the
	// address it advertises to peers (used as the join remote-address).
	NodeID   string `json:"node_id"`
	NodeAddr string `json:"node_addr"`
	// Managers / Nodes are cluster-wide counts (manager-reported; 0 elsewhere).
	Managers int `json:"managers"`
	Nodes    int `json:"nodes"`
	// RemoteManagers are the advertised addresses of the swarm's managers.
	RemoteManagers []string `json:"remote_managers,omitempty"`
	// Error carries the engine's swarm error string when LocalNodeState == error.
	Error string `json:"error,omitempty"`
}

SwarmInfo summarizes an engine's participation in a Docker Swarm, as reported by `docker info`. It is available on any engine (no manager role required), so it is the cheap signal Miabi uses to auto-detect cluster mode.

type SwarmInitRequest

type SwarmInitRequest struct {
	// AdvertiseAddr is the address managers/workers reach this manager on
	// (host or host:port). Required.
	AdvertiseAddr string
	// ListenAddr is the management-plane bind; blank defaults to 0.0.0.0:2377.
	ListenAddr string
	// DataPathAddr is the address for overlay (VXLAN) data-plane traffic; blank
	// falls back to AdvertiseAddr.
	DataPathAddr string
}

SwarmInitRequest configures putting an engine into swarm mode as a manager.

type SwarmJoinRequest

type SwarmJoinRequest struct {
	// RemoteAddrs are the manager addresses to dial (host:port).
	RemoteAddrs []string
	// JoinToken is the worker or manager join token.
	JoinToken string
	// AdvertiseAddr is the address this node advertises to peers; blank lets the
	// engine auto-detect.
	AdvertiseAddr string
	// ListenAddr is the management-plane bind; blank defaults to 0.0.0.0:2377.
	ListenAddr string
}

SwarmJoinRequest configures joining an engine to an existing swarm.

type SwarmJoinTokens

type SwarmJoinTokens struct {
	Worker  string `json:"worker"`
	Manager string `json:"manager"`
}

SwarmJoinTokens are the secrets a node uses to join a swarm in either role.

type SwarmNode

type SwarmNode struct {
	ID            string `json:"id"`
	Hostname      string `json:"hostname"`
	Role          string `json:"role"`         // manager | worker
	Availability  string `json:"availability"` // active | pause | drain
	State         string `json:"state"`        // ready | down | unknown | disconnected
	Leader        bool   `json:"leader"`
	Reachability  string `json:"reachability,omitempty"` // reachable | unreachable (managers)
	Addr          string `json:"addr,omitempty"`
	EngineVersion string `json:"engine_version,omitempty"`
	// Capacity as the swarm scheduler sees it — what it packs tasks against. It comes from the node's
	// own report over the swarm control plane, so it is known even for a node Miabi has no Docker
	// client for, where host metrics are otherwise unavailable.
	NanoCPUs    int64  `json:"nano_cpus,omitempty"`    // 1e9 == one core
	MemoryBytes int64  `json:"memory_bytes,omitempty"` // total, not used
	OS          string `json:"os,omitempty"`           // linux | windows
	Arch        string `json:"arch,omitempty"`         // x86_64 | aarch64 | …
	// Tasks is how many service tasks the scheduler currently runs here — the node's
	// load. Populated by SwarmNodes; 0 for an idle node.
	Tasks int `json:"tasks"`
}

SwarmNode is one node as seen from a swarm manager (`docker node ls`).

type SwarmTask added in v1.3.0

type SwarmTask struct {
	ID           string `json:"id"`
	ServiceName  string `json:"service_name"`
	NodeID       string `json:"node_id"`
	Image        string `json:"image,omitempty"`
	Slot         int    `json:"slot,omitempty"`
	State        string `json:"state"`         // running | preparing | failed | …
	DesiredState string `json:"desired_state"` // running | shutdown
	Message      string `json:"message,omitempty"`
	Err          string `json:"error,omitempty"`
	UpdatedAt    string `json:"updated_at,omitempty"` // RFC3339
}

SwarmTask is one task (a container the scheduler placed) of a service, as seen from a manager. It is how a node's real workload is enumerated: the container itself lives on the node, which Miabi may hold no Docker client for.

type TLSMaterial

type TLSMaterial struct {
	CACert []byte
	Cert   []byte
	Key    []byte
}

TLSMaterial holds PEM-encoded TLS material for a TCP Docker endpoint. A nil *TLSMaterial means a plaintext connection. CACert alone enables server verification; Cert+Key add client authentication (mTLS).

type Volume

type Volume = stackdocker.Volume

The types the stack engine also speaks are owned by the stack module and aliased here, so both sides use one definition — Go's structural typing needs identical named types for Client to satisfy stackdocker.Client. Aliases are transparent, so every call site is unaffected.

type VolumeSpec

type VolumeSpec struct {
	Name       string
	Labels     map[string]string
	SizeBytes  int64
	Driver     string
	DriverOpts map[string]string
	// DevicePath backs the volume with an operator-chosen host directory (a storage class) instead
	// of the engine's data root, using the local driver's bind options. The volume stays an
	// ordinary named, labelled Docker volume, so backup, housekeeping and mounts are unchanged.
	DevicePath string
}

VolumeSpec describes a managed volume to create, including an optional driver and driver options for shared storage (NFS/CIFS). An empty Driver uses Docker's default (local). DriverOpts are the backend mount options (e.g. NFS: type=nfs, o=addr=...,rw, device=:/export).

type VolumeUsage

type VolumeUsage struct {
	DockerName string `json:"docker_name"`
	Bytes      int64  `json:"bytes"`
	RefCount   int    `json:"ref_count"`
}

VolumeUsage is one Docker volume's measured on-disk size, keyed by name so it joins to a workspace's Volume rows. RefCount 0 = reclaimable.

Jump to

Keyboard shortcuts

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