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
- Variables
- func FmtBytes(n int64) string
- func NormalizeRestart(s string) (string, error)
- func ParseDevice(line string) (container.DeviceMapping, error)
- func ParseFileMount(line string) (repoPath, containerPath string, template bool, err error)
- func SelfContainerID(ctx context.Context, r *Runtime) string
- func SelfImage(ctx context.Context, r *Runtime) string
- type ContainerDetail
- type ContainerSpec
- type ContainerStats
- type HostInfo
- type ManagedContainer
- type NetAttach
- type Node
- type NodeTask
- type NodeTaskInfo
- type ProxyRelay
- type Runtime
- func (r *Runtime) AttachServiceNetwork(ctx context.Context, name string, n NetAttach) (bool, error)
- func (r *Runtime) AttachServiceNetworks(ctx context.Context, name string, ns []NetAttach) (bool, error)
- func (r *Runtime) BuildImage(ctx context.Context, builder, dir, dockerfile, tag string, ...) error
- func (r *Runtime) ConnectContainer(ctx context.Context, netName, containerID string, aliases []string) error
- func (r *Runtime) ContainerIsSystem(ctx context.Context, id string) bool
- func (r *Runtime) CreateVolume(ctx context.Context, name string) error
- func (r *Runtime) CreateVolumeOpts(ctx context.Context, name, driver string, opts map[string]string) error
- func (r *Runtime) DeleteVolumeFile(ctx context.Context, vol, file string) error
- func (r *Runtime) DetachServiceNetwork(ctx context.Context, name, netName string) (bool, error)
- func (r *Runtime) DialContainer(ctx context.Context, tileID, containerID, targetAlias string, port int) (net.Conn, error)
- func (r *Runtime) DialOnNetwork(ctx context.Context, tileID, envNet, targetAlias string, port int) (net.Conn, error)
- func (r *Runtime) DigestRef(ctx context.Context, ref string) (string, error)
- func (r *Runtime) DisconnectTenants(ctx context.Context, name string) (int, error)
- func (r *Runtime) EnsureBuilder(ctx context.Context, name string, memMB int) error
- func (r *Runtime) EnsureOverlay(ctx context.Context, name string) error
- func (r *Runtime) EnsureRemoteBuilder(ctx context.Context, name, addr string) error
- func (r *Runtime) EnsureSecret(ctx context.Context, name string, value []byte) (existed bool, err error)
- func (r *Runtime) EnsureService(ctx context.Context, s ServiceSpec) (created bool, err error)
- func (r *Runtime) EnsureVolumeTool(ctx context.Context) error
- func (r *Runtime) Exec(ctx context.Context, containerID string, cmd []string) (string, error)
- func (r *Runtime) ExecShell(ctx context.Context, containerID, command string) (string, error)
- func (r *Runtime) ExecStream(ctx context.Context, containerID string, cmd []string, stdin io.Reader) (io.Reader, func() error, error)
- func (r *Runtime) ExecTTY(ctx context.Context, containerID string, cmd []string) (io.ReadWriter, func(w, h uint) error, func(), error)
- func (r *Runtime) GetNode(ctx context.Context, id string) (Node, error)
- func (r *Runtime) HealthStatus(ctx context.Context, containerID string) (string, error)
- func (r *Runtime) Info(ctx context.Context) (HostInfo, error)
- func (r *Runtime) InspectContainer(ctx context.Context, id string) (*ContainerDetail, error)
- func (r *Runtime) InspectVolume(ctx context.Context, name string) (VolumeInfo, error)
- func (r *Runtime) IsManagerNode(ctx context.Context) bool
- func (r *Runtime) IsRunning(ctx context.Context, containerID string) (bool, error)
- func (r *Runtime) JoinToken(ctx context.Context) (token, managerAddr string, err error)
- func (r *Runtime) ListAll(ctx context.Context) ([]ManagedContainer, error)
- func (r *Runtime) ListByLabel(ctx context.Context, label, value string) ([]ManagedContainer, error)
- func (r *Runtime) ListImageTags(ctx context.Context, repository string) ([]string, error)
- func (r *Runtime) ListImageTagsByLabel(ctx context.Context, label, value string) ([]string, error)
- func (r *Runtime) ListNetworks(ctx context.Context, prefix string) ([]string, error)
- func (r *Runtime) ListNodes(ctx context.Context) ([]Node, error)
- func (r *Runtime) ListProxyRelays(ctx context.Context) ([]ProxyRelay, error)
- func (r *Runtime) ListServiceNames(ctx context.Context) ([]string, error)
- func (r *Runtime) ListVolumeFiles(ctx context.Context, vol, dir string) ([]VolumeEntry, error)
- func (r *Runtime) ListVolumes(ctx context.Context) ([]VolumeInfo, error)
- func (r *Runtime) LocalDigest(ctx context.Context, ref string) (string, error)
- func (r *Runtime) Logs(ctx context.Context, id string, tail int) (string, error)
- func (r *Runtime) MountSecret(ctx context.Context, service, secretID, secretName, target string) (bool, error)
- func (r *Runtime) NetworkMemberAddr(ctx context.Context, netName, containerID string) (ip, cidr string, err error)
- func (r *Runtime) NetworkServices(ctx context.Context, name string) ([]string, error)
- func (r *Runtime) NetworkTenants(ctx context.Context, name string) ([]string, error)
- func (r *Runtime) NodeTasks(ctx context.Context, nodeID string) ([]NodeTaskInfo, error)
- func (r *Runtime) PauseContainer(ctx context.Context, containerID string) error
- func (r *Runtime) Prune(ctx context.Context) (string, error)
- func (r *Runtime) PullImage(ctx context.Context, ref string, logW io.Writer) error
- func (r *Runtime) PullImageAuth(ctx context.Context, ref, auth string, logW io.Writer) error
- func (r *Runtime) PurgeVolume(ctx context.Context, name string) error
- func (r *Runtime) PushImage(ctx context.Context, ref string, logW io.Writer) error
- func (r *Runtime) PushImageAuth(ctx context.Context, ref, auth string, logW io.Writer) error
- func (r *Runtime) ReadVolumeFile(ctx context.Context, vol, file string) (io.ReadCloser, func() error, error)
- func (r *Runtime) RegistryLogin(ctx context.Context, url, user, pass string) error
- func (r *Runtime) RemoveBuilder(ctx context.Context, name string) error
- func (r *Runtime) RemoveImage(ctx context.Context, ref string) error
- func (r *Runtime) RemoveNode(ctx context.Context, nodeID string) error
- func (r *Runtime) RemoveService(ctx context.Context, name string) error
- func (r *Runtime) RemoveVolume(ctx context.Context, name string) error
- func (r *Runtime) RestartContainer(ctx context.Context, containerID string) error
- func (r *Runtime) RestartService(ctx context.Context, name string, want int) error
- func (r *Runtime) RollbackService(ctx context.Context, name string) error
- func (r *Runtime) RunContainer(ctx context.Context, spec ContainerSpec) (string, error)
- func (r *Runtime) RunJob(ctx context.Context, s ServiceSpec) (string, error)
- func (r *Runtime) RunMoveSend(ctx context.Context, moveID, vol, target string, ...) error
- func (r *Runtime) RunningTasks(ctx context.Context, service string) ([]NodeTask, error)
- func (r *Runtime) RunningTileTasks(ctx context.Context) (map[string]NodeTask, error)
- func (r *Runtime) ScaleService(ctx context.Context, name string, n int) error
- func (r *Runtime) SecretID(ctx context.Context, name string) (string, error)
- func (r *Runtime) SelfNodeID(ctx context.Context) (string, error)
- func (r *Runtime) SelfServiceName(ctx context.Context) string
- func (r *Runtime) ServiceLogs(ctx context.Context, name string, tail int) (string, error)
- func (r *Runtime) ServiceStatus(ctx context.Context, name string) (ServiceState, error)
- func (r *Runtime) ServiceTasks(ctx context.Context, name string) ([]ServiceTask, error)
- func (r *Runtime) ServiceTasksOnNetwork(ctx context.Context, service, netName string) ([]NodeTask, error)
- func (r *Runtime) SetNodeAvailability(ctx context.Context, nodeID, availability string) error
- func (r *Runtime) SetNodeGroup(ctx context.Context, nodeID, group string) error
- func (r *Runtime) StartContainer(ctx context.Context, containerID string) error
- func (r *Runtime) StartMoveReceiver(ctx context.Context, moveID, vol string) error
- func (r *Runtime) Stats(ctx context.Context, id string) (ContainerStats, error)
- func (r *Runtime) StopContainer(ctx context.Context, containerID string) error
- func (r *Runtime) StopMoveReceiver(ctx context.Context, moveID string) error
- func (r *Runtime) StopRemove(ctx context.Context, containerID string) error
- func (r *Runtime) StopService(ctx context.Context, name string) error
- func (r *Runtime) StreamLogs(ctx context.Context, id string, tail int) (io.Reader, func(), error)
- func (r *Runtime) StreamLogsMarked(ctx context.Context, id string, tail int) (<-chan string, func(), error)
- func (r *Runtime) StreamServiceLogsMarked(ctx context.Context, name string, tail int) (<-chan string, func(), error)
- func (r *Runtime) SweepForwardState(ctx context.Context)
- func (r *Runtime) SweepMoveReceivers(ctx context.Context)
- func (r *Runtime) TagImage(ctx context.Context, src, dst string) error
- func (r *Runtime) TarVolume(ctx context.Context, vol string, w io.Writer, live bool) error
- func (r *Runtime) TasksByNode(ctx context.Context) (map[string]int, error)
- func (r *Runtime) UnpauseContainer(ctx context.Context, containerID string) error
- func (r *Runtime) UntarVolume(ctx context.Context, vol string, src io.Reader) error
- func (r *Runtime) UpdateServiceImage(ctx context.Context, name, image string, env map[string]string, ...) (string, error)
- func (r *Runtime) VerifyTar(ctx context.Context, path string) error
- func (r *Runtime) VolumeSize(ctx context.Context, vol string) (int64, error)
- func (r *Runtime) WaitConverged(ctx context.Context, name string, timeout time.Duration) error
- func (r *Runtime) WaitRolled(ctx context.Context, name string, since time.Time, timeout time.Duration) error
- func (r *Runtime) WriteVolumeFile(ctx context.Context, vol, file string, src io.Reader) error
- type SecretMount
- type ServiceSpec
- type ServiceState
- type ServiceTask
- type VolumeEntry
- type VolumeInfo
Constants ¶
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 )
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 ¶
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.
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 "".
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 NormalizeRestart ¶
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 ¶
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 ¶
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.
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 ¶
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 ¶
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 ¶
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.
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 ¶
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 (*Runtime) AttachServiceNetwork ¶
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 ¶
ContainerIsSystem reports whether stopping/removing the container would take down protected infrastructure. Used to guard the container actions.
func (*Runtime) CreateVolume ¶
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 ¶
DeleteVolumeFile removes a file or directory (recursively) from the volume. The volume root itself is refused.
func (*Runtime) DetachServiceNetwork ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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) ExecShell ¶
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) HealthStatus ¶
HealthStatus reads a container's live health via inspect: healthy | unhealthy | starting, or "" when no HEALTHCHECK is declared.
func (*Runtime) InspectContainer ¶
InspectContainer returns curated details for one container.
func (*Runtime) InspectVolume ¶
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 ¶
IsManagerNode reports whether this daemon can run swarm control-plane calls. The Add node button is hidden when it cannot.
func (*Runtime) JoinToken ¶
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 ¶
ListByLabel lists containers (running or not) matching label=value.
func (*Runtime) ListImageTags ¶
ListImageTags lists local image tags matching a repository reference (e.g. "stackr/<appid>"), returned as full "repo:tag" strings.
func (*Runtime) ListImageTagsByLabel ¶
ListImageTagsByLabel lists the tags of every local image carrying label=value. Built images are labelled with the tile they belong to.
func (*Runtime) ListNetworks ¶
ListNetworks returns network names starting with prefix.
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 ¶
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 ¶
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 ¶
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) 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 ¶
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 ¶
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 ¶
NodeTasks lists the running tasks on one node, service name included, for the server page's "Running here" list.
func (*Runtime) PauseContainer ¶
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 ¶
Prune removes stopped containers, dangling images, and build cache. Tagged images (incl. rollback targets) are untouched.
func (*Runtime) PullImageAuth ¶
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 ¶
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) PushImageAuth ¶
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 (*Runtime) RemoveBuilder ¶
RemoveBuilder removes a builder and, for a docker-container one, its container and cache volume. Missing is fine.
func (*Runtime) RemoveImage ¶
RemoveImage removes an image tag (no force; in-use images survive).
func (*Runtime) RemoveNode ¶
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 ¶
RemoveService deletes a service. Missing is not an error.
func (*Runtime) RemoveVolume ¶
func (*Runtime) RestartContainer ¶
RestartContainer restarts a container in place. Networks and addresses survive, unlike a recreate, so stored proxy addresses stay valid.
func (*Runtime) RestartService ¶
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 ¶
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 ¶
RunContainer creates and starts a container, returning its ID.
func (*Runtime) RunJob ¶
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 ¶
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 ¶
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 (*Runtime) SecretID ¶
SecretID resolves a secret's name to its ID, which is what a service spec references.
func (*Runtime) SelfNodeID ¶
SelfNodeID is the swarm node this daemon is. Empty when the daemon is not in a swarm at all.
func (*Runtime) SelfServiceName ¶
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 ¶
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 ¶
ServiceStatus reads the service's own view plus its tasks.
func (*Runtime) ServiceTasks ¶
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 ¶
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 ¶
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 ¶
StartContainer starts an existing container.
func (*Runtime) StartMoveReceiver ¶
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) StopContainer ¶
StopContainer stops (but keeps) a container.
func (*Runtime) StopMoveReceiver ¶
StopMoveReceiver removes the receiving container. The volume it wrote stays: it is the point of the exercise.
func (*Runtime) StopRemove ¶
StopRemove force-removes a container.
func (*Runtime) StopService ¶
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 ¶
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 ¶
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 ¶
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) TarVolume ¶
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 ¶
TasksByNode counts a node's running tasks, the servers list's "containers" column, since one task is one container.
func (*Runtime) UnpauseContainer ¶
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 ¶
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) UpdateServiceImage ¶ added in v0.1.1
func (r *Runtime) UpdateServiceImage(ctx context.Context, name, image string, env map[string]string, cfg *swarm.UpdateConfig) (string, error)
UpdateServiceImage points a service at image, sets env on top of what it has, and replaces its update policy. Returns the image it ran before.
func (*Runtime) VerifyTar ¶
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 ¶
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 ¶
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.
type SecretMount ¶
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 ¶
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.