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
- Variables
- type BindMount
- type Capabilities
- type Client
- type ConfigInfo
- type ConfigObject
- type Container
- type ContainerConfig
- type ContainerMount
- type ContainerNetwork
- type DialFunc
- type DiskUsage
- type DiskUsageCategory
- type EngineEvent
- type ExecOptions
- type ExecStream
- type FileEntry
- type GPURequest
- type HealthcheckSpec
- type Image
- type ImageInspect
- type Info
- type LogLine
- type Network
- type NetworkSpec
- type Port
- type PortMapping
- type ProcessList
- type PruneImagesOptions
- type PruneReport
- type RegistryAuth
- type RunSpec
- type ServiceBind
- type ServiceConfig
- type ServiceMountDriver
- type ServiceSpec
- type ServiceStatus
- type StatsSample
- type SwarmInfo
- type SwarmInitRequest
- type SwarmJoinRequest
- type SwarmJoinTokens
- type SwarmNode
- type SwarmTask
- type TLSMaterial
- type Volume
- type VolumeSpec
- type VolumeUsage
Constants ¶
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.
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" )
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 RoleRegistry = stackdocker.RoleRegistry RoleRegistryGC = stackdocker.RoleRegistryGC ManagedByCompose = stackdocker.ManagedByCompose ManagedByMiabi = stackdocker.ManagedByMiabi ManagedByExternal = stackdocker.ManagedByExternal PartOfMiabi = stackdocker.PartOfMiabi ManagedLabel = stackdocker.ManagedLabel )
Variables ¶
var ( PlatformLabels = stackdocker.PlatformLabels IsPlatformStack = stackdocker.IsPlatformStack IsProtected = stackdocker.IsProtected ManagedBy = stackdocker.ManagedBy LabelValue = stackdocker.LabelValue IsManaged = stackdocker.IsManaged IsPlatformInfra = stackdocker.IsPlatformInfra IsReservedLabelKey = stackdocker.IsReservedLabelKey SanitizeUserLabels = stackdocker.SanitizeUserLabels WorkspaceID = stackdocker.WorkspaceID )
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.
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 ¶
This section is empty.
Types ¶
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)
// 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
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 ¶
New connects to the Docker engine using the standard environment (DOCKER_HOST etc.) with API version negotiation.
func NewRemote ¶
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 ¶
NewSocket connects to a Docker engine at a socket/host string (e.g. "unix:///var/run/docker.sock" or "tcp://host:2375" without TLS).
type ConfigInfo ¶ added in v1.8.1
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 ¶
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"`
}
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"`
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"`
// 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 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"`
}
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 ¶
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 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
buildSwarmServiceSpec maps a Miabi ServiceSpec to the Docker SDK spec. ServiceConfig attaches one docker config object at a path inside the task.
type ServiceMountDriver ¶
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 ¶
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 ¶
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
}
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.