runtime

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Sep 15, 2026 License: Apache-2.0 Imports: 38 Imported by: 0

Documentation

Overview

Package runtime is the single Docker boundary: no other package may import the Docker SDK or shell out to docker. Everything speaks in Stackr terms (apps, deployments) so a Swarm backend can slot in later.

Index

Constants

View Source
const (
	NetworkName = "stkr"
	// PanelAlias is the DNS name the panel answers to on stkr, traefik's
	// route to it and the agent's way back to the panel are both this name.
	PanelAlias   = "stkr-panel"
	LabelApp     = "stackr.app"
	LabelDB      = "stackr.db"
	LabelManaged = "stackr.managed"
	LabelDeploy  = "stackr.deployment"
	// LabelRun marks a one-shot started for a cron_runs row; the value is the
	// run id. It is how the panel finds a run in flight to follow or kill.
	LabelRun = "stackr.run"

	// LabelAgentTask is the label the node agent's own service carries. Kept
	// here rather than read from infra/agent, which imports this package.
	// It marks the agent's container as one not to stop from the UI.
	LabelAgentTask = "stackr.agent"

	// LabelProxyRelay marks a forward-relay container; the value is the tile
	// id it relays to.
	LabelProxyRelay = "stackr.proxyrelay"

	// MoveAliasPrefix is what a move's receiving container answers to on the
	// stkr overlay, suffixed with the move id. MovePort is the rsync daemon
	// inside it, published nowhere: both ends are on the overlay.
	MoveAliasPrefix = "stkr-move-"
	MovePort        = 8873
	// TraefikService is the swarm service the shared proxy runs as. Named
	// here because netpool has to put a grown pool network into its spec and
	// must not import infra/proxy.
	TraefikService = "stkr-traefik"
	// ProxyRelayImage is built by `make proxyrelay` (and the deploy script),
	// never built or pulled from here.
	ProxyRelayImage = "stkr-proxyrelay:local"
	// ProxyRelayPort is the fixed port every relay listens on; each relay has
	// its own network namespace, so there is nothing to collide with.
	ProxyRelayPort = 15000
)
View Source
const NodeGroupLabel = "stackr.group"

NodeGroupLabel is the docker node label a node's group is stored in. The tile half is the node_group config key, turned into a placement constraint against this label (docs/plans/31-node-agent-open-questions.md, node groups).

Variables

View Source
var MoveImage = "alpine:3"

MoveImage is what both sides of a move run. It has to carry rsync, and it has to already be on both nodes: a move is not the moment to discover a worker has no internet. The agent's own image is both, every node is already running it, and it ships rsync for exactly this (docs/plans/31-node-agent-open-questions.md, transport). Set by the panel at boot from the image its own agent service runs.

View Source
var RestartPolicies = []string{"", "on-failure", "no"}

RestartPolicies are the accepted tile restart values, canonical form. "always" and "unless-stopped" from the container days are aliases of "".

View Source
var VolumeToolImage = "alpine:3"

VolumeToolImage is the throwaway container every volume op runs in. alpine on the manager, which pulls it once; the agent points it at its own image at startup, because a worker has no reason to have alpine and a volume browse is not the moment to pull one.

Functions

func FmtBytes

func FmtBytes(n int64) string

FmtBytes renders a byte count for the UI ("1.2 GB", "340 MB").

func NormalizeRestart

func NormalizeRestart(s string) (string, error)

NormalizeRestart maps any accepted spelling to its canonical value and rejects the rest. Every surface that takes the value (form, API, config) runs it through here so the stored column is always canonical.

func ParseDevice

func ParseDevice(line string) (container.DeviceMapping, error)

ParseDevice decodes one device line into docker's mapping. The container path defaults to the host path and permissions to rwm, matching compose.

func ParseFileMount

func ParseFileMount(line string) (repoPath, containerPath string, template bool, err error)

ParseFileMount decodes one tile files: line into its parts and validates the shape: a clean repo-relative source (no escape upward) and an absolute container path, with an optional trailing :template flag. Lives here beside ParseDevice so the deploy engine and the config layer share one grammar without an import cycle.

func SelfContainerID

func SelfContainerID(ctx context.Context, r *Runtime) string

SelfContainerID is the id of the container this process runs in, or "" when it is not in one.

The hostname is the usual answer and is wrong here: both the panel and the installer set --hostname stkr-panel so the overlay alias resolves, and a lookup by that name finds nothing. That failure is silent and expensive, it is what left the runtime key unmounted on the panel, so every call to a remote agent answered "no node agent on this install yet", and what would have let the encryption flip tear down the panel's own service instead of stepping over it. So: try the hostname, then read the id out of the binds docker gives every container.

func SelfImage

func SelfImage(ctx context.Context, r *Runtime) string

SelfImage is the image this process's own container runs. Empty outside a container.

Types

type ContainerDetail

type ContainerDetail struct {
	ID       string
	Name     string
	Image    string
	State    string
	Started  string
	Ports    []string
	Mounts   []string
	Networks []string
}

ContainerDetail is a curated inspect view.

type ContainerSpec

type ContainerSpec struct {
	Name        string
	Image       string
	Cmd         []string // override image CMD (nil = image default)
	Env         []string // KEY=VALUE
	Labels      map[string]string
	Volumes     []string          // "name-or-hostpath:/container/path"
	Ports       map[string]string // hostPort -> containerPort (published)
	Aliases     []string          // stable DNS names on the network
	NetworkName string            // defaults to stackr network
	CPULimit    float64           // cores, 0 = unlimited
	MemLimitMB  int               // MB, 0 = unlimited

	User          string   // docker --user, "uid[:gid]" ("" = image default)
	ShmSizeMB     int      // /dev/shm size, 0 = docker default (64MB)
	Privileged    bool     // full host access, the caller gates who may set it
	Devices       []string // "host[:container[:perms]]" per entry
	RestartPolicy string   // "" | "on-failure" | "no" (runtime.NormalizeRestart)

	// Docker-native HEALTHCHECK: HealthCmd runs as CMD-SHELL on the knobs
	// below (each 0 = docker default). Empty HealthCmd = no healthcheck.
	HealthCmd          string
	HealthIntervalS    int
	HealthTimeoutS     int
	HealthRetries      int
	HealthStartPeriodS int
}

ContainerSpec describes a container to run on the stackr network.

type ContainerStats

type ContainerStats struct {
	CPUPct   float64
	MemBytes uint64
	RxBytes  uint64
	TxBytes  uint64
}

ContainerStats is one instantaneous reading for a running container. RxBytes/TxBytes are cumulative since container start (all interfaces).

type HostInfo

type HostInfo struct {
	ServerVersion     string
	OS                string
	Arch              string
	NCPU              int
	MemTotal          int64
	Containers        int
	ContainersRunning int
	Images            int
}

HostInfo is a snapshot of the Docker daemon for the servers screen.

type ManagedContainer

type ManagedContainer struct {
	ID    string
	Name  string
	Image string
	State string
	// Health is docker's health-status word (healthy | unhealthy | starting),
	// "" when the container declares no HEALTHCHECK. Parsed from the list
	// summary's human status string, no extra inspect per container.
	Health string
	Labels map[string]string
	IPs    []string // current addresses across all attached networks
	// System marks infrastructure that must not be stopped/removed from the
	// UI: the panel itself ("panel"), the node agent ("agent"), the shared
	// Traefik proxy ("proxy") or the image registry ("registry"). Doing so
	// would lock the operator out, cut a node off, kill all routing, or break
	// the next deploy to a worker.
	System string

	// Swarm task identity, read off the labels docker puts on every task
	// container. Slot is the stable handle, replica 2 is slot 2 for the life
	// of the service, while TaskID and this container's ID change on every
	// restart. All zero/empty on a plain container.
	Slot   int
	TaskID string
	NodeID string
}

ManagedContainer is a summary of a container Stackr knows about.

type NetAttach

type NetAttach struct {
	Name    string
	Aliases []string
}

NetAttach is one network a service's tasks join, with the DNS names they answer to on it. Attachments are part of the spec on purpose: a running service cannot join a network without rolling every task, which is the whole reason the overlays come from a pool (infra/netpool).

type Node

type Node struct {
	ID       string
	Hostname string
	Addr     string
	Role     string // manager | worker
	// State is docker's own node state: ready, down, disconnected, unknown.
	State string
	// Availability is active, pause or drain. Draining is what the Drain
	// button sets; it is separate from State, and a draining node is still
	// ready.
	Availability  string
	EngineVersion string
	Arch          string
	OS            string
	NCPU          int
	MemBytes      int64
	Group         string
	Labels        map[string]string
	UpdatedAt     time.Time
	// Self marks the node this panel runs on.
	Self bool
}

Node is one swarm node as the panel needs it.

func (Node) IsManager

func (n Node) IsManager() bool

IsManager reports whether the node runs the control plane. The manager page has no Drain and no Remove: traefik and the registry are pinned there, so draining it kills 80, 443 and the panel.

func (Node) Status

func (n Node) Status() string

Status folds docker's state and availability into the one word the servers list shows (docs/plans/32-multi-node-ui.md). "pending" is not here: that is a row whose node has not appeared in the swarm at all, which is a fact about the table, not about a node.

type NodeTask

type NodeTask struct {
	ID           string
	NodeID       string
	Slot         int
	State        string
	DesiredState string
	ContainerID  string
	// Addr is the task's IP on the network asked for, without the mask.
	Addr string
	Err  string
}

NodeTask is one task of one service, with the node it landed on and the address it answers to on a network.

type NodeTaskInfo

type NodeTaskInfo struct {
	Service string
	Slot    int
	State   string
	TileID  string
}

NodeTaskInfo is one row of a node's "Running here" list.

type ProxyRelay

type ProxyRelay struct {
	TileID string // label value: the tile it relays into
	Port   int    // target port, parsed from the container name suffix
}

ProxyRelay is one live forward-relay container.

type Runtime

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

func New

func New() (*Runtime, error)

func (*Runtime) AttachServiceNetwork

func (r *Runtime) AttachServiceNetwork(ctx context.Context, name string, n NetAttach) (bool, error)

AttachServiceNetwork adds a network to a service's spec if it is not already there, reporting whether it changed anything.

func (*Runtime) AttachServiceNetworks

func (r *Runtime) AttachServiceNetworks(ctx context.Context, name string, ns []NetAttach) (bool, error)

AttachServiceNetworks adds every missing network in one spec update, reporting whether it changed anything. A running service cannot join a network the way a container can: the attachment is part of the task spec, so the update rolls every task, once for the whole batch, which is why pool growth adds all the new overlays together rather than one at a time. Callers holding a container id must re-read it after a true, and a service already on every network must cost nothing, which is what makes this safe to call on every reconcile.

func (*Runtime) BuildImage

func (r *Runtime) BuildImage(ctx context.Context, builder, dir, dockerfile, tag string, buildArgs, labels map[string]string, logW io.Writer) error

BuildImage builds dir with the given dockerfile into tag, streaming build output to logW. Shells out to the docker CLI for full BuildKit fidelity. Runs in the named builder and loads the result into the daemon, where the push that follows expects it.

func (*Runtime) ConnectContainer

func (r *Runtime) ConnectContainer(ctx context.Context, netName, containerID string, aliases []string) error

ConnectContainer joins containerID to netName with the given DNS aliases (nil = plain client join). Already-connected is not an error. Used for shared-instance networks: the instance joins with its alias so consumers can resolve it, consumers join with no alias.

func (*Runtime) ContainerIsSystem

func (r *Runtime) ContainerIsSystem(ctx context.Context, id string) bool

ContainerIsSystem reports whether stopping/removing the container would take down protected infrastructure. Used to guard the container actions.

func (*Runtime) CreateVolume

func (r *Runtime) CreateVolume(ctx context.Context, name string) error

CreateVolume creates a named docker volume (no-op if it exists).

func (*Runtime) CreateVolumeOpts

func (r *Runtime) CreateVolumeOpts(ctx context.Context, name, driver string, opts map[string]string) error

RemoveVolume deletes a named volume. Fails while a container uses it. CreateVolumeOpts creates a named volume with an explicit driver + opts, how storage sub-paths become nfs/cifs/bind mounts. NOT idempotent across differing opts: docker returns an existing volume unchanged, so edits are remove-then-recreate.

func (*Runtime) DeleteVolumeFile

func (r *Runtime) DeleteVolumeFile(ctx context.Context, vol, file string) error

DeleteVolumeFile removes a file or directory (recursively) from the volume. The volume root itself is refused.

func (*Runtime) DetachServiceNetwork

func (r *Runtime) DetachServiceNetwork(ctx context.Context, name, netName string) (bool, error)

DetachServiceNetwork removes a network from a service's spec, reporting whether it changed anything. The mirror of AttachServiceNetworks, and the only way a swarm service leaves a network: NetworkDisconnect on the task's container is undone within seconds, because the attachment lives in the service spec and the orchestrator puts it back.

This is what makes a pooled network safe to recycle. Without it the pool hands the name to the next environment with the previous tenant's service still on it, and two environments that should not see each other can reach each other by DNS.

func (*Runtime) DialContainer

func (r *Runtime) DialContainer(ctx context.Context, tileID, containerID, targetAlias string, port int) (net.Conn, error)

DialContainer opens a TCP connection to port on the tile's container, always through a proxyrelay: a disposable container on both the stackr network and the target's network, so stackr itself never joins environment networks. targetAlias is the tile's DNS alias (envnet.TileAlias, passed in because envnet imports this package), which the relay dials so a redeployed tile re-resolves.

The relay can idle-exit between our inspect and our dial; on a failed dial the relay is removed and recreated once.

func (*Runtime) DialOnNetwork

func (r *Runtime) DialOnNetwork(ctx context.Context, tileID, envNet, targetAlias string, port int) (net.Conn, error)

DialOnNetwork is DialContainer without the container: it puts the relay on the named network and dials the alias there.

This is the multi-node half. Inspecting the tile's container to find its network only works while the container is on this machine, and a port forward to a tile on a worker died at that inspect with "no such container", even though the env network is an overlay and the alias resolves on it from any node, which is the whole point of an overlay. The caller passes the network from the environment row instead.

func (*Runtime) DigestRef

func (r *Runtime) DigestRef(ctx context.Context, ref string) (string, error)

DigestRef turns a pushed tag into the same image pinned by digest: registry/name@sha256:... The agent service uses it because its tag never changes. A spec that says :latest is byte-identical after an upgrade, so EnsureService sees nothing to do and every node keeps running the old agent while the panel starts refusing its calls on the version header.

func (*Runtime) DisconnectTenants

func (r *Runtime) DisconnectTenants(ctx context.Context, name string) (int, error)

DisconnectTenants takes every non-infrastructure container off a network and leaves the network standing. Pooled networks are reused by the next tenant (infra/netpool), so they are drained rather than removed; traefik and the panel stay attached. Returns how many were disconnected.

func (*Runtime) EnsureBuilder

func (r *Runtime) EnsureBuilder(ctx context.Context, name string, memMB int) error

EnsureBuilder creates a buildx docker-container builder called name if this panel does not know it yet, capped at memMB with a low cpu weight so a build yields to running services instead of pinning the manager. The daemon's own builder ignores every resource flag. One builder per org, each with its own cache, so no org ever hits another's cached step (docs/plans/37-builds.md, items 2 and 3). An existing builder container of that name is reused.

func (*Runtime) EnsureOverlay

func (r *Runtime) EnsureOverlay(ctx context.Context, name string) error

EnsureOverlay creates an attachable swarm overlay if it is missing. Every tenant network is one of these (docs/plans/30-docker-swarm.md): a service cannot hot-join a network, so they are pre-created and handed out from a pool instead of being created per environment. Attachable so plain containers, traefik and the forward relays, until step 4, can still join. Requires a swarm manager; the install script inits one.

func (*Runtime) EnsureRemoteBuilder

func (r *Runtime) EnsureRemoteBuilder(ctx context.Context, name, addr string) error

EnsureRemoteBuilder points a buildx builder called name at a buildkit daemon listening on addr (docs/plans/37-builds.md, item 4). The daemon is somebody else's to run; this is only the client side.

func (*Runtime) EnsureSecret

func (r *Runtime) EnsureSecret(ctx context.Context, name string, value []byte) (existed bool, err error)

EnsureSecret creates a swarm secret if it is missing and returns whether it already existed. The agent's shared runtime key lives in one of these: mounted into the agent and the panel services, readable by neither tiles nor users (docs/plans/31-node-agent-open-questions.md, where the key lives).

func (*Runtime) EnsureService

func (r *Runtime) EnsureService(ctx context.Context, s ServiceSpec) (created bool, err error)

EnsureService creates the service or updates it in place, reporting whether it had to create it. Callers use that to skip work that a fresh task has already done, a forced roll right after a create is both pointless and a race against swarm's own version bump.

func (*Runtime) EnsureVolumeTool

func (r *Runtime) EnsureVolumeTool(ctx context.Context) error

EnsureVolumeTool pulls the helper image if it is not on the host yet. Call it before freezing a container: the first TarVolume on a fresh host would otherwise pull inside the pause window, turning "frozen for seconds" into "frozen for a registry round trip".

func (*Runtime) Exec

func (r *Runtime) Exec(ctx context.Context, containerID string, cmd []string) (string, error)

Exec runs cmd inside the container and returns combined output.

func (*Runtime) ExecShell

func (r *Runtime) ExecShell(ctx context.Context, containerID, command string) (string, error)

ExecShell runs a shell command inside the container. On ctx timeout the process group is killed inside the container too, killing just the docker CLI would leave the command running.

func (*Runtime) ExecStream

func (r *Runtime) ExecStream(ctx context.Context, containerID string, cmd []string, stdin io.Reader) (io.Reader, func() error, error)

ExecStream runs cmd inside the container with optional stdin, streaming stdout to the returned reader. Caller must drain and close via the returned wait func, which reports the exec's error (stderr included in the message).

func (*Runtime) ExecTTY

func (r *Runtime) ExecTTY(ctx context.Context, containerID string, cmd []string) (io.ReadWriter, func(w, h uint) error, func(), error)

ExecTTY opens an interactive TTY in the container running cmd (nil = a login shell). Returns a raw read/write stream bridged to the exec's TTY, plus a resize func and closer.

func (*Runtime) GetNode

func (r *Runtime) GetNode(ctx context.Context, id string) (Node, error)

GetNode returns one node by ID.

func (*Runtime) HealthStatus

func (r *Runtime) HealthStatus(ctx context.Context, containerID string) (string, error)

HealthStatus reads a container's live health via inspect: healthy | unhealthy | starting, or "" when no HEALTHCHECK is declared.

func (*Runtime) Info

func (r *Runtime) Info(ctx context.Context) (HostInfo, error)

Info reports the Docker daemon snapshot.

func (*Runtime) InspectContainer

func (r *Runtime) InspectContainer(ctx context.Context, id string) (*ContainerDetail, error)

InspectContainer returns curated details for one container.

func (*Runtime) InspectVolume

func (r *Runtime) InspectVolume(ctx context.Context, name string) (VolumeInfo, error)

InspectVolume returns one named volume with its host path and size. Size comes from docker's disk-usage scan (the only API that reports it) so this is a click-time call, not a pollable one.

func (*Runtime) IsManagerNode

func (r *Runtime) IsManagerNode(ctx context.Context) bool

IsManagerNode reports whether this daemon can run swarm control-plane calls. The Add node button is hidden when it cannot.

func (*Runtime) IsRunning

func (r *Runtime) IsRunning(ctx context.Context, containerID string) (bool, error)

IsRunning reports whether the container is in running state.

func (*Runtime) JoinToken

func (r *Runtime) JoinToken(ctx context.Context) (token, managerAddr string, err error)

JoinToken is the swarm's worker join token, which the join script needs alongside a manager address.

func (*Runtime) ListAll

func (r *Runtime) ListAll(ctx context.Context) ([]ManagedContainer, error)

ListAll lists every container on the host (running or not).

func (*Runtime) ListByLabel

func (r *Runtime) ListByLabel(ctx context.Context, label, value string) ([]ManagedContainer, error)

ListByLabel lists containers (running or not) matching label=value.

func (*Runtime) ListImageTags

func (r *Runtime) ListImageTags(ctx context.Context, repository string) ([]string, error)

ListImageTags lists local image tags matching a repository reference (e.g. "stackr/<appid>"), returned as full "repo:tag" strings.

func (*Runtime) ListImageTagsByLabel

func (r *Runtime) ListImageTagsByLabel(ctx context.Context, label, value string) ([]string, error)

ListImageTagsByLabel lists the tags of every local image carrying label=value. Built images are labelled with the tile they belong to.

func (*Runtime) ListNetworks

func (r *Runtime) ListNetworks(ctx context.Context, prefix string) ([]string, error)

ListNetworks returns network names starting with prefix.

func (*Runtime) ListNodes

func (r *Runtime) ListNodes(ctx context.Context) ([]Node, error)

ListNodes returns every node in the swarm.

func (*Runtime) ListProxyRelays

func (r *Runtime) ListProxyRelays(ctx context.Context) ([]ProxyRelay, error)

ListProxyRelays lists running relay containers across all tiles, the source of truth for the canvas's forward cards.

func (*Runtime) ListServiceNames

func (r *Runtime) ListServiceNames(ctx context.Context) ([]string, error)

ListServiceNames returns every swarm service on this cluster, by name, stackr's own and anyone else's. Read-only: the one caller is agent.Running, which asks whether the agent service exists at all. Anything that acts on the list must filter on LabelManaged first.

func (*Runtime) ListVolumeFiles

func (r *Runtime) ListVolumeFiles(ctx context.Context, vol, dir string) ([]VolumeEntry, error)

ListVolumeFiles lists the entries directly under dir inside the volume ("/" = volume root), directories first.

func (*Runtime) ListVolumes

func (r *Runtime) ListVolumes(ctx context.Context) ([]VolumeInfo, error)

ListVolumes returns all named volumes with sizes and the containers using them. Sizes come from docker's disk-usage scan (slower than a plain list, fine for a settings page, don't poll it).

func (*Runtime) LocalDigest

func (r *Runtime) LocalDigest(ctx context.Context, ref string) (string, error)

LocalDigest returns the manifest digest the local image for ref was pulled from ("sha256:..."), "" if the image was built locally or never pulled.

func (*Runtime) Logs

func (r *Runtime) Logs(ctx context.Context, id string, tail int) (string, error)

Logs returns the last tail lines of a container's logs, one-shot.

func (*Runtime) MountSecret

func (r *Runtime) MountSecret(ctx context.Context, service, secretID, secretName, target string) (bool, error)

MountSecret adds one swarm secret to an existing service, if it is not already mounted, and reports whether it changed anything.

The panel needs this for its own service: the shared runtime key is created the first time a node is added, long after `docker service create stackr` ran, and without it every call the panel makes to a remote agent fails with "no node agent on this install yet". Adding the secret restarts the panel once and it comes back holding the key.

func (*Runtime) NetworkMemberAddr

func (r *Runtime) NetworkMemberAddr(ctx context.Context, netName, containerID string) (ip, cidr string, err error)

NetworkMemberAddr returns a container's address on one network, as the bare IP plus the network's own subnet in CIDR form, the two things an app behind traefik needs to trust a forwarded header, either exactly (the IP) or for the life of the network (the subnet).

Both come off a single inspect: docker reports a member's IPv4Address already suffixed with the network prefix, and the subnet is the IPAM config's. A container that is not on the network is not an error here, it is the state during a proxy restart, so it returns empty strings and lets the caller decide.

func (*Runtime) NetworkServices

func (r *Runtime) NetworkServices(ctx context.Context, name string) ([]string, error)

NetworkServices lists the swarm services with a task on the named network, skipping protected infrastructure. A pool network no row holds any more with a service still on it is an orphan: the rows went and the service did not, and the next environment to claim that network would inherit a neighbour it can reach.

func (*Runtime) NetworkTenants

func (r *Runtime) NetworkTenants(ctx context.Context, name string) ([]string, error)

NetworkTenants lists the containers on a network that are not stackr's own infrastructure. Traefik sits on every tenant network, so a plain member count can never reach zero, this is what "empty" has to mean before a pooled network is handed to the next environment. A missing network counts as empty.

func (*Runtime) NodeTasks

func (r *Runtime) NodeTasks(ctx context.Context, nodeID string) ([]NodeTaskInfo, error)

NodeTasks lists the running tasks on one node, service name included, for the server page's "Running here" list.

func (*Runtime) PauseContainer

func (r *Runtime) PauseContainer(ctx context.Context, containerID string) error

PauseContainer freezes every process in a container (SIGSTOP via cgroup). Files stop changing while it holds, which is what makes a tar of the container's volume a point-in-time copy rather than a torn one.

func (*Runtime) Prune

func (r *Runtime) Prune(ctx context.Context) (string, error)

Prune removes stopped containers, dangling images, and build cache. Tagged images (incl. rollback targets) are untouched.

func (*Runtime) PullImage

func (r *Runtime) PullImage(ctx context.Context, ref string, logW io.Writer) error

PullImage pulls ref, streaming progress to logW.

func (*Runtime) PullImageAuth

func (r *Runtime) PullImageAuth(ctx context.Context, ref, auth string, logW io.Writer) error

PullImageAuth and PushImageAuth move an image with a credential supplied per call, as the base64 auth blob the Docker API takes in its X-Registry-Auth header.

Why not `docker login` first: the daemon config is shared by everything on the node, so logging in for one organization leaves its credential usable by the next organization's build. A per-call header keeps one org's token to one request. Blank auth is an anonymous pull, which is what a public image wants.

func (*Runtime) PurgeVolume

func (r *Runtime) PurgeVolume(ctx context.Context, name string) error

PurgeVolume removes the volume after clearing the stopped containers that hold it. Docker refuses to delete a volume any container references, and swarm keeps a rescheduled task's container in its history, so after a volume move the source copy was permanently undeletable: the node page offered no Delete button and the docs said to use it anyway.

Only containers that are not running are removed, so this can never take down something that is serving. A running container still makes the whole call fail, from docker's own refusal, which is the safety net the panel relies on.

func (*Runtime) PushImage

func (r *Runtime) PushImage(ctx context.Context, ref string, logW io.Writer) error

PushImage pushes ref, streaming progress to logW.

func (*Runtime) PushImageAuth

func (r *Runtime) PushImageAuth(ctx context.Context, ref, auth string, logW io.Writer) error

func (*Runtime) ReadVolumeFile

func (r *Runtime) ReadVolumeFile(ctx context.Context, vol, file string) (io.ReadCloser, func() error, error)

ReadVolumeFile streams one file out of the volume. The returned closer reaps the docker process; the error it reports includes stderr.

func (*Runtime) RegistryLogin

func (r *Runtime) RegistryLogin(ctx context.Context, url, user, pass string) error

func (*Runtime) RemoveBuilder

func (r *Runtime) RemoveBuilder(ctx context.Context, name string) error

RemoveBuilder removes a builder and, for a docker-container one, its container and cache volume. Missing is fine.

func (*Runtime) RemoveImage

func (r *Runtime) RemoveImage(ctx context.Context, ref string) error

RemoveImage removes an image tag (no force; in-use images survive).

func (*Runtime) RemoveNode

func (r *Runtime) RemoveNode(ctx context.Context, nodeID string) error

RemoveNode takes a node out of the swarm. Force, because a node that has already gone dark never leaves cleanly and leaving it listed is worse than removing it, the volumes on its disk are unreachable either way, which is what the Remove modal warns about.

func (*Runtime) RemoveService

func (r *Runtime) RemoveService(ctx context.Context, name string) error

RemoveService deletes a service. Missing is not an error.

func (*Runtime) RemoveVolume

func (r *Runtime) RemoveVolume(ctx context.Context, name string) error

func (*Runtime) RestartContainer

func (r *Runtime) RestartContainer(ctx context.Context, containerID string) error

RestartContainer restarts a container in place. Networks and addresses survive, unlike a recreate, so stored proxy addresses stay valid.

func (*Runtime) RestartService

func (r *Runtime) RestartService(ctx context.Context, name string, want int) error

RestartService brings a service back to one replica and re-rolls its tasks. One update, not a scale followed by a force: each ServiceUpdate carries the version it read, so two back-to-back calls race the first one's version bump. want is how many replicas a stopped service comes back with. Zero or less means one. It is a parameter because the spec of a stopped service says zero and has forgotten what it was: restarting a tile configured for three replicas used to silently bring back one, and nothing in the panel then said the count had changed.

func (*Runtime) RollbackService

func (r *Runtime) RollbackService(ctx context.Context, name string) error

RollbackService puts the previous spec back. Swarm does this on its own when an update fails its monitor window; this is for the case swarm cannot see, a task stuck pulling or starting, which it will wait on forever.

func (*Runtime) RunContainer

func (r *Runtime) RunContainer(ctx context.Context, spec ContainerSpec) (string, error)

RunContainer creates and starts a container, returning its ID.

func (*Runtime) RunJob

func (r *Runtime) RunJob(ctx context.Context, s ServiceSpec) (string, error)

RunJob runs a spec once as a replicated job: one task, run to completion, logs collected through the manager. Swarm never removes a finished job service, so this does, on every path, a stale one collides with the next run of the same name and its task keeps showing up in task lists.

Returns the task's output and a non-nil error when it exited non-zero, so the caller reads it exactly like a `docker run` result.

func (*Runtime) RunMoveSend

func (r *Runtime) RunMoveSend(ctx context.Context, moveID, vol, target string, progress func(done, total int64)) error

RunMoveSend runs one rsync pass from vol into the receiver answering to target, calling progress with rsync's own byte counters as it goes.

--delete is deliberate: the second pass has to remove what the tile deleted between the passes, or the target ends up with files the source no longer has. It only ever deletes inside the fresh target volume.

func (*Runtime) RunningTasks

func (r *Runtime) RunningTasks(ctx context.Context, service string) ([]NodeTask, error)

RunningTasks lists a service's running tasks: the node each is on and the container id there.

This is the multi-node answer to "where is this tile's container". Looking it up by label on the local socket only ever finds the ones on the manager, so a tile running on a worker came back with nothing, and the callers read that as "not running" rather than "not here", which is how a backup came to tar an empty volume and report success.

func (*Runtime) RunningTileTasks

func (r *Runtime) RunningTileTasks(ctx context.Context) (map[string]NodeTask, error)

RunningTileTasks maps a tile id to the node and container of its running task, for every tile in the swarm.

The manager's own socket lists only the manager's containers, so a tile on a worker looked exactly like a tile whose container had gone: the status reconciler marked it stopped and the canvas showed it red while it was serving traffic. Swarm's task list is the one view that covers every node.

func (*Runtime) ScaleService

func (r *Runtime) ScaleService(ctx context.Context, name string, n int) error

func (*Runtime) SecretID

func (r *Runtime) SecretID(ctx context.Context, name string) (string, error)

SecretID resolves a secret's name to its ID, which is what a service spec references.

func (*Runtime) SelfNodeID

func (r *Runtime) SelfNodeID(ctx context.Context) (string, error)

SelfNodeID is the swarm node this daemon is. Empty when the daemon is not in a swarm at all.

func (*Runtime) SelfServiceName

func (r *Runtime) SelfServiceName(ctx context.Context) string

SelfServiceName is the swarm service this process's own task belongs to, or "" when the panel is still a plain container.

Read from the task's own labels rather than guessed from a constant. Note that "" is two answers in one: a plain-container install, and a lookup that failed. The one caller, agent.Ensure, only mounts a key either way, so it does not have to tell them apart; anything destructive would.

func (*Runtime) ServiceLogs

func (r *Runtime) ServiceLogs(ctx context.Context, name string, tail int) (string, error)

ServiceLogs returns the last tail lines from every replica of a service, one-shot. Swarm collects them through the manager, so a task on another node needs nothing extra; each line is prefixed with the task name, which carries the slot.

func (*Runtime) ServiceStatus

func (r *Runtime) ServiceStatus(ctx context.Context, name string) (ServiceState, error)

ServiceStatus reads the service's own view plus its tasks.

func (*Runtime) ServiceTasks

func (r *Runtime) ServiceTasks(ctx context.Context, name string) ([]ServiceTask, error)

ServiceTasks lists a service's tasks whose desired state is running: the replicas that are meant to exist right now, which is what a slot picker and the canvas both want. A service that is gone has no tasks, not an error, that is the state between delete and the next list.

func (*Runtime) ServiceTasksOnNetwork

func (r *Runtime) ServiceTasksOnNetwork(ctx context.Context, service, netName string) ([]NodeTask, error)

ServiceTasksOnNetwork lists a service's running tasks with each task's address on netName. This is how the panel finds an agent: the agent service is global, so one task per node, and the task's stkr address is where that node's agent listens. Nothing is configured and nothing is registered.

func (*Runtime) SetNodeAvailability

func (r *Runtime) SetNodeAvailability(ctx context.Context, nodeID, availability string) error

SetNodeAvailability drains, pauses or reactivates a node. Draining is how swarm moves stateless tasks off; pinned tiles do not move on their own and are the Move modal's job (docs/plans/32-multi-node-ui.md, Drain).

func (*Runtime) SetNodeGroup

func (r *Runtime) SetNodeGroup(ctx context.Context, nodeID, group string) error

SetNodeGroup writes (or clears, with "") the node's group label. Every other docker node label is left alone: free-form labels are a separate, parked job (docs/notes.md, misc).

func (*Runtime) StartContainer

func (r *Runtime) StartContainer(ctx context.Context, containerID string) error

StartContainer starts an existing container.

func (*Runtime) StartMoveReceiver

func (r *Runtime) StartMoveReceiver(ctx context.Context, moveID, vol string) error

StartMoveReceiver opens the receiving side of a move: a container with vol mounted and an rsync daemon in it, answering to the move's alias on the stkr overlay. Idempotent, a retried call finds the container already there and leaves it running.

func (*Runtime) Stats

func (r *Runtime) Stats(ctx context.Context, id string) (ContainerStats, error)

Stats returns instantaneous CPU%/memory/network for a running container.

func (*Runtime) StopContainer

func (r *Runtime) StopContainer(ctx context.Context, containerID string) error

StopContainer stops (but keeps) a container.

func (*Runtime) StopMoveReceiver

func (r *Runtime) StopMoveReceiver(ctx context.Context, moveID string) error

StopMoveReceiver removes the receiving container. The volume it wrote stays: it is the point of the exercise.

func (*Runtime) StopRemove

func (r *Runtime) StopRemove(ctx context.Context, containerID string) error

StopRemove force-removes a container.

func (*Runtime) StopService

func (r *Runtime) StopService(ctx context.Context, name string) error

StopService scales a service to zero and waits for its container to actually exit. ScaleService returns as soon as the new spec is posted, and a database with dbStopGraceS (60s) of grace goes on writing for up to a minute after that. Both callers, a volume move and a backup, then rsync or rm -rf a volume a live process is still writing to, which is how a "green" backup ends up torn.

WaitConverged is not the tool: it reports converged only against a wanted count above zero. This watches the tasks instead, and a task that has left the list is gone.

A timeout is a failure, not a shrug: carrying on would do the unsafe thing the wait exists to prevent.

func (*Runtime) StreamLogs

func (r *Runtime) StreamLogs(ctx context.Context, id string, tail int) (io.Reader, func(), error)

StreamLogs follows container logs; returns a reader and a stop func.

func (*Runtime) StreamLogsMarked

func (r *Runtime) StreamLogsMarked(ctx context.Context, id string, tail int) (<-chan string, func(), error)

StreamLogsMarked follows container logs with docker timestamps, emitting one line per log entry prefixed "O " (stdout) or "E " (stderr) so viewers can colour the streams. The channel closes when the container stops or ctx ends; call stop to end early.

func (*Runtime) StreamServiceLogsMarked

func (r *Runtime) StreamServiceLogsMarked(ctx context.Context, name string, tail int) (<-chan string, func(), error)

StreamServiceLogsMarked follows every replica's logs, marked the same way StreamLogsMarked marks a container's.

func (*Runtime) SweepForwardState

func (r *Runtime) SweepForwardState(ctx context.Context)

SweepForwardState cleans up after the pre-proxyrelay design and crashes: removes leftover relay containers (the normal path is their own idle exit) and detaches the stackr container itself from every non-stackr network the shipped self-attach version joined. Best-effort; under `hamr dev` the process has no container and the detach half is a no-op.

func (*Runtime) SweepMoveReceivers

func (r *Runtime) SweepMoveReceivers(ctx context.Context)

SweepMoveReceivers removes both sides of any move left behind by a process that died mid-copy. Called at boot: a stray receiver holds a volume open and answers to an alias a later move would reuse, and a stray sender is an rsync still writing into it.

func (*Runtime) TagImage

func (r *Runtime) TagImage(ctx context.Context, src, dst string) error

TagImage tags src as dst.

func (*Runtime) TarVolume

func (r *Runtime) TarVolume(ctx context.Context, vol string, w io.Writer, live bool) error

TarVolume streams a gzipped tar of the whole volume into w. It goes through the helper container's stdout rather than a shared path on purpose: stackr itself usually runs containerized, so a directory it can write is not a directory the docker daemon can bind-mount.

func (*Runtime) TasksByNode

func (r *Runtime) TasksByNode(ctx context.Context) (map[string]int, error)

TasksByNode counts a node's running tasks, the servers list's "containers" column, since one task is one container.

func (*Runtime) UnpauseContainer

func (r *Runtime) UnpauseContainer(ctx context.Context, containerID string) error

UnpauseContainer resumes a paused container. Safe to call on one that is not paused, a backup that failed mid-tar still ends with this.

func (*Runtime) UntarVolume

func (r *Runtime) UntarVolume(ctx context.Context, vol string, src io.Reader) error

UntarVolume wipes the volume and extracts the archive from r into it. The wipe is the destructive half of a restore, callers verify the archive first, because there is no way back from an emptied volume.

func (*Runtime) VerifyTar

func (r *Runtime) VerifyTar(ctx context.Context, path string) error

VerifyTar reads an archive end to end and reports whether it is intact. A truncated or corrupt download fails here, before the volume is wiped.

func (*Runtime) VolumeSize

func (r *Runtime) VolumeSize(ctx context.Context, vol string) (int64, error)

VolumeSize is the volume's size on disk, from du on the node holding it. The Move modal asks for this before it offers to copy anything, so the estimate it shows is measured rather than guessed.

func (*Runtime) WaitConverged

func (r *Runtime) WaitConverged(ctx context.Context, name string, timeout time.Duration) error

WaitConverged blocks until the service has its replicas up and no update in flight, or the timeout passes. Callers that read a task's container or its addresses right after a roll need this: the old task is still listed while the new one starts.

func (*Runtime) WaitRolled

func (r *Runtime) WaitRolled(ctx context.Context, name string, since time.Time, timeout time.Duration) error

WaitRolled waits for a service to settle on an update that swarm began at or after since. Pass the time just before posting the update; a zero time means "settled at all", which is WaitConverged.

The baseline is the whole point. Right after a spec update swarm may still be reporting the previous update as completed with the old task running and wanted, which Converged reads as settled. A caller that then execs into "the" container gets the one that is about to be killed: seen on the rig as "the database system is shutting down" in the middle of cutting a slice.

func (*Runtime) WriteVolumeFile

func (r *Runtime) WriteVolumeFile(ctx context.Context, vol, file string, src io.Reader) error

WriteVolumeFile streams src into a file inside the volume, creating parent directories as needed.

type SecretMount

type SecretMount struct {
	ID     string
	Name   string
	Target string
}

SecretMount is one swarm secret in a service spec. Target is the filename under /run/secrets.

type ServiceSpec

type ServiceSpec struct {
	Name       string
	Image      string
	Entrypoint []string // replaces the image's ENTRYPOINT (nil keeps it)
	Cmd        []string
	Env        []string
	Labels     map[string]string
	Mounts     []string // "name-or-hostpath:/container/path[:ro]"
	Ports      map[string]string
	// HostPorts publishes on the node's own interface instead of through the
	// routing mesh. The mesh SNATs, so the visitor IP is lost, traefik and
	// anything else that has to see a real client address needs this.
	HostPorts bool
	Networks  []NetAttach
	Replicas  int
	User      string

	CPULimit   float64
	MemLimitMB int

	// ShmSizeMB sizes /dev/shm. Swarm has no --shm-size, so it rides as a
	// tmpfs mount on /dev/shm, the same thing docker does under the flag.
	// Postgres parallel query dies on the 64MB default.
	ShmSizeMB int

	// Pinned tiles hold a volume: exactly one replica, the old task stopped
	// before the new one starts (two writers on one volume corrupt it), and
	// placement fixed so the task cannot land on a node with an empty disk.
	Pinned bool

	// HomeNode is the swarm node ID a pinned tile's volume lives on, turned
	// into a `node.id ==` constraint. A local volume is a directory on one
	// host's disk: lose this and swarm will happily schedule the database
	// onto an empty node with an empty volume, which is silent data loss and
	// not an error (docs/plans/30-docker-swarm.md, addendum). EnsureService
	// refuses a pinned spec without one.
	HomeNode string

	// NodeGroup constrains the task to nodes labelled stackr.group=<x>.
	// Empty means anywhere.
	NodeGroup string

	// ManagerOnly pins the task to the swarm manager by role rather than by
	// node ID. stackr's own infrastructure, traefik, the registry, the panel,
	// is placed this way: it holds the manager's disk, and it is what a
	// single-manager install means. Tiles never use it.
	ManagerOnly bool

	// Global places one task on every node instead of a replica count. The
	// node agent is the only global service (infra/agent).
	Global bool

	// Secrets are swarm secrets mounted into the task at
	// /run/secrets/<Target>, by secret name.
	Secrets []SecretMount

	// StopGraceS overrides swarm's 10s SIGTERM-to-SIGKILL window (0 = leave
	// the default).
	StopGraceS int

	// RegistryAuth is the base64 auth blob for pulling the image on whichever
	// node the task lands (the API's --with-registry-auth). Empty is fine on
	// a single node with a public or already-pulled image.
	RegistryAuth string

	// Unconfined turns off seccomp and apparmor for the task. Rootless
	// buildkit cannot start under the default profile and it is the only
	// thing that sets this. Not --privileged: swarm has none, and buildkit
	// does not need it.
	Unconfined bool

	HealthCmd          string
	HealthIntervalS    int
	HealthTimeoutS     int
	HealthRetries      int
	HealthStartPeriodS int

	// RestartPolicy is one of RestartPolicies: "" (restart on any exit, the
	// default), "on-failure", or "no" (a task that exits stays down).
	RestartPolicy string
}

ServiceSpec describes one swarm service. It is deliberately the same shape as ContainerSpec where the two overlap, so the deploy engine reads the same either way, ContainerSpec stays for the things that are still plain containers (one-shots, the volume tool, the forward relays, traefik).

Three ContainerSpec fields have no swarm equivalent and are dropped with a warning by the caller rather than silently: Devices, ShmSizeMB and Privileged. Swarm's ContainerSpec has no --device, no --shm-size and no --privileged; its Privileges field is about AppArmor/seccomp, not root.

type ServiceState

type ServiceState struct {
	Wanted  int
	Running int
	Update  string // swarm's UpdateStatus.State ("" = no update recorded)
	Message string
	// UpdateStarted is when swarm began the update it is reporting, zero when
	// it has never updated this service. It is the only way to tell "the
	// update I just asked for has finished" from "a previous update finished
	// and this one has not been picked up yet", which read identically and
	// made WaitConverged return before the roll had even started.
	UpdateStarted time.Time
}

ServiceState is what stackrd needs to narrate a rolling update: how many replicas are up out of how many are wanted, and what swarm says about the update itself.

func (ServiceState) Converged

func (s ServiceState) Converged() bool

Converged reports every wanted replica running and no update in flight.

func (ServiceState) RolledBack

func (s ServiceState) RolledBack() bool

RolledBack reports that swarm gave up on the new spec and put the old one back on its own. The deploy is a failure even though the service is healthy.

type ServiceTask

type ServiceTask struct {
	Slot        int
	TaskID      string
	ContainerID string
	NodeID      string
	State       string // swarm's task state: running, starting, failed, ...
	Desired     string
	Err         string
	ExitCode    int
}

ServiceTask is one running (or wanted) replica of a service. Slot is the stable handle, replica 2 is slot 2 for the life of the service, while TaskID and ContainerID change on every restart.

type VolumeEntry

type VolumeEntry struct {
	Name    string
	Dir     bool
	Size    int64
	ModTime time.Time
}

VolumeEntry is one file or directory in a volume listing.

type VolumeInfo

type VolumeInfo struct {
	Name       string
	Driver     string
	Created    string
	Mountpoint string   // path on the host holding the data
	SizeBytes  int64    // -1 = unknown
	UsedBy     []string // names of *running* containers mounting it
	// HeldBy is the containers that mount it but are not running: a tile the
	// operator stopped, and the corpses swarm keeps in its task history after
	// a task is rescheduled to another node. Docker refuses to delete a
	// volume while either list is non-empty, so these have to be named rather
	// than folded into UsedBy: a volume held only by corpses is free to
	// delete, one held by a stopped tile is the tile's data.
	HeldBy []string
}

VolumeInfo describes one docker named volume for the volumes UI.

Jump to

Keyboard shortcuts

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