agent

package
v0.4.0 Latest Latest
Warning

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

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

Documentation

Overview

Package agent is the node agent: one task per swarm node, proxying the handful of docker calls Swarm's control plane does not forward.

Swarm speaks in services and tasks. Exec, stats, pause, inspect and anything that mounts a volume are local daemon calls on the node holding the container, and Swarm forwards none of them, k8s has the kubelet for this, Swarm has nothing (docs/plans/30-docker-swarm.md, step 7).

The shape, decided in docs/plans/31-node-agent-open-questions.md:

  • The agent is a narrow proxy to its own node's socket: thin handlers over the same infra/runtime methods, by name, with the panel's arguments. The daemon API itself never goes on the wire, a full socket proxy would be root on the node for anyone holding the key.
  • Socket local, agent remote. On one node nothing new runs: the panel keeps using runtime.Runtime directly. See node.go.
  • HTTP/1.1 plus JSON for calls, websocket for the two streams (exec TTY and logs). Tar and untar are request and response bodies.
  • The agent listens on its overlay address only. The panel finds it by reading the agent task's overlay IP out of swarm task state, so there is nothing to configure on either side.

This file is the contract. Changes to it are additive only and unknown fields are ignored, so a panel and an agent one version apart still talk.

Index

Constants

View Source
const (
	// ServiceName is the global swarm service every node runs a task of.
	ServiceName = "stkr-agent"

	// Port is the agent's listener. Fixed, because the panel finds the agent
	// by node and there is nothing to look a port up in.
	Port = 8090

	// SecretName is the swarm secret holding the shared runtime key, mounted
	// into the agent and the panel at SecretPath. One `docker secret create`;
	// a global service has one spec, so the key cannot be per node.
	SecretName = "stkr-agent-key"
	SecretPath = "/run/secrets/agent_key" //nolint:gosec // a mount path, not a credential

	// VersionHeader rides on every call. HTTP has no "connect", so this is
	// where plan 30's version handshake lives.
	VersionHeader = "X-Stackr-Agent-Version"

	// LabelAgent marks the agent's own service and its throwaway containers.
	LabelAgent = "stackr.agent"
)
View Source
const (
	PathInfo    = "/v1/info"
	PathInspect = "/v1/inspect"
	PathStats   = "/v1/stats"
	PathHealth  = "/v1/health"
	PathPause   = "/v1/pause"
	PathPrune   = "/v1/prune"
	PathVolumes = "/v1/volumes"

	// The containers admin page, which lists and drives containers on every
	// node, not just the manager's.
	PathContainers      = "/v1/containers"
	PathContainerAction = "/v1/container/action"
	PathContainerSystem = "/v1/container/system"

	PathVolumeList   = "/v1/volume/list"
	PathVolumeDelete = "/v1/volume/delete"
	PathVolumeSize   = "/v1/volume/size"
	PathVolumeRead   = "/v1/volume/read"
	PathVolumeWrite  = "/v1/volume/write"
	PathVolumeTar    = "/v1/volume/tar"
	PathVolumeUntar  = "/v1/volume/untar"

	// The volume itself, not a file in it: PathVolumeDelete above removes
	// one entry inside a volume, these two make and destroy the volume. A
	// volume is a directory on one host's disk, so both have to run on the
	// node that owns it, doing them on the manager was silently deleting
	// the manager's volume while the operator looked at a worker's list.
	PathVolumeCreate = "/v1/volume/create"
	PathVolumeRemove = "/v1/volume/remove"

	PathExec      = "/v1/exec"
	PathExecRun   = "/v1/exec/run"
	PathExecShell = "/v1/exec/shell"
	PathLogs      = "/v1/logs"

	// A move is two calls, one to each agent: the target opens a receiver,
	// the source pushes into it and streams progress back.
	PathMoveReceive = "/v1/move/receive"
	PathMoveSend    = "/v1/move/send"
	PathMoveClose   = "/v1/move/close"
)

Paths under /v1. One prefix, one file, so adding a call is one line in each of client.go and server.go.

View Source
const ExecErrorTrailer = "X-Stackr-Exec-Error"

ExecErrorTrailer carries an exec's failure after its output.

A dump is a stream: by the time the command fails the body has started and there is no status code left to say so with. A trailer is HTTP's answer to exactly that, and it has to be one, a truncated database dump that reports success is a backup nobody can restore.

View Source
const StreamErrorTrailer = "X-Stackr-Stream-Error"

StreamErrorTrailer is ExecErrorTrailer for the volume streams: a tar of a volume and a read of one file off it. Same problem, same answer. Without it a tar that died halfway ends its chunked body normally, the client's io.Copy returns nil, and the backup is recorded green with half an archive in it.

Variables

This section is empty.

Functions

func Ensure

func Ensure(ctx context.Context, store repo.Store, rt *runtime.Runtime, dataDir string) error

Ensure creates the shared runtime key and the global agent service if they are not there yet, and makes sure the image it runs is one every node can actually pull.

Called on the first Add node submit, before the node joins (plan 32): the service exists first so swarm places a task on the new node the moment it arrives. Swarm also places one on the manager, which the panel ignores, on its own node it uses the socket directly. Also called at boot when the service has gone missing, and after the encryption flip recreates the networks.

func KeyFile

func KeyFile(dataDir string) string

KeyFile is where the panel keeps its copy of the runtime key.

func PanelImage

func PanelImage(ctx context.Context, rt *runtime.Runtime) string

PanelImage is the image the panel's own task runs, which is what the agent service is built from. Read from this container's own inspect, so an install running a local build gets that same local build on its nodes rather than a published tag nobody has.

func ReadKey

func ReadKey(dataDir string) string

ReadKey loads the shared runtime key: the mounted swarm secret in the agent, the copy beside the database in the panel. Absent is not an error, an install that has never added a node has no agent, no secret, and nothing to talk to.

dataDir is empty in the agent, which only ever has the secret.

func Running

func Running(ctx context.Context, rt *runtime.Runtime) bool

Running reports whether the agent service exists at all. Every "needs the node agent" state in the UI is this question.

Types

type BoolResp

type BoolResp struct {
	OK bool `json:"ok"`
}

BoolResp is a yes/no answer.

type Client

type Client struct {
	// Addr is the agent task's address on the stkr overlay.
	Addr string
	Key  string
	// Version is the panel's own version, sent on every call. HTTP has no
	// "connect", so this is where the handshake lives: the agent echoes its
	// version back and Do refuses a mismatch.
	Version string

	HTTP *http.Client
}

Client is the panel's side of one node's agent. It carries the node's overlay address, which the panel reads out of swarm task state, there is nothing to configure and nothing to discover.

func (*Client) CloseMoveReceiver

func (c *Client) CloseMoveReceiver(ctx context.Context, moveID string) error

CloseMoveReceiver tears the receiving container down. The volume it wrote stays, it is the point of the move.

func (*Client) ContainerIsSystem

func (c *Client) ContainerIsSystem(ctx context.Context, id string) bool

func (*Client) CreateVolume

func (c *Client) CreateVolume(ctx context.Context, vol string) error

CreateVolume makes a named volume on the node this client points at.

func (*Client) CreateVolumeOpts

func (c *Client) CreateVolumeOpts(ctx context.Context, vol, driver string, opts map[string]string) error

CreateVolumeOpts makes a volume with an explicit driver and driver opts on the node this client points at, how a storage sub-path gets its nfs/cifs mount on the machine that will serve it.

func (*Client) DeleteVolumeFile

func (c *Client) DeleteVolumeFile(ctx context.Context, vol, file string) error

func (*Client) ExecShell

func (c *Client) ExecShell(ctx context.Context, id, command string) (string, error)

func (*Client) ExecStream

func (c *Client) ExecStream(ctx context.Context, id string, cmd []string, stdin io.Reader) (io.Reader, func() error, error)

ExecStream runs one non-TTY exec on the node, mirroring the local method: stdin goes up as the request body, stdout comes back as the response body, and the command's own failure arrives in a trailer that the wait func reads. Reading the body to EOF before wait() is what makes the trailer available, which is the same order the local caller already uses.

func (*Client) ExecTTY

func (c *Client) ExecTTY(ctx context.Context, id string, cmd []string) (io.ReadWriter, func(w, h uint) error, func(), error)

ExecTTY opens a TTY exec on the node and returns it in the same shape the local method does, so handlers/web/wsterm bridges a browser to a remote container without knowing it is remote.

func (*Client) HealthStatus

func (c *Client) HealthStatus(ctx context.Context, id string) (string, error)

func (*Client) Info

func (c *Client) Info(ctx context.Context) (InfoResp, error)

func (*Client) InspectContainer

func (c *Client) InspectContainer(ctx context.Context, id string) (*runtime.ContainerDetail, error)

func (*Client) ListAll

func (c *Client) ListAll(ctx context.Context) ([]runtime.ManagedContainer, error)

func (*Client) ListVolumeFiles

func (c *Client) ListVolumeFiles(ctx context.Context, vol, dir string) ([]runtime.VolumeEntry, error)

func (*Client) ListVolumes

func (c *Client) ListVolumes(ctx context.Context) ([]runtime.VolumeInfo, error)

func (*Client) OpenMoveReceiver

func (c *Client) OpenMoveReceiver(ctx context.Context, moveID, vol string) error

OpenMoveReceiver asks this node to accept a volume move into vol.

func (*Client) PauseContainer

func (c *Client) PauseContainer(ctx context.Context, id string) error

func (*Client) Prune

func (c *Client) Prune(ctx context.Context) (string, error)

func (*Client) ReadVolumeFile

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

ReadVolumeFile streams one file off the node. The wait func is where a mid-stream failure surfaces, matching the local method: by the time the body starts there is no status code left to say it with. It used to only close the body, so every mid-stream failure read as success.

func (*Client) RemoveVolume

func (c *Client) RemoveVolume(ctx context.Context, vol string) error

RemoveVolume destroys a named volume on the node this client points at. Not to be confused with DeleteVolumeFile, which removes one file inside one.

func (*Client) SendMove

func (c *Client) SendMove(ctx context.Context, moveID, vol, target string, progress func(done, total int64)) error

SendMove runs one rsync pass from this node into the receiver, reporting rsync's own byte counters as they arrive. It returns when the pass ends.

func (*Client) StartContainer

func (c *Client) StartContainer(ctx context.Context, id string) error

func (*Client) Stats

func (c *Client) Stats(ctx context.Context, id string) (runtime.ContainerStats, error)

func (*Client) StopContainer

func (c *Client) StopContainer(ctx context.Context, id string) error

func (*Client) StopRemove

func (c *Client) StopRemove(ctx context.Context, id string) error

func (*Client) StreamLogsMarked

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

StreamLogsMarked follows a container's logs on the node, one "O "/"E " prefixed line per message, the same channel the local method returns.

func (*Client) TarVolume

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

func (*Client) UnpauseContainer

func (c *Client) UnpauseContainer(ctx context.Context, id string) error

func (*Client) UntarVolume

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

func (*Client) VolumeSize

func (c *Client) VolumeSize(ctx context.Context, vol string) (int64, error)

func (*Client) WriteVolumeFile

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

type ContainerActionReq

type ContainerActionReq struct {
	Container string `json:"container"`
	// Action is "start", "stop" or "remove".
	Action string `json:"action"`
}

ContainerActionReq starts, stops or removes one container.

type ContainerReq

type ContainerReq struct {
	Container string `json:"container"`
}

ContainerReq names a container. The panel resolves a tile to a task and a node first; by the time it gets here the node is already decided.

type ErrResp

type ErrResp struct {
	Error string `json:"error"`
}

ErrResp is the body of any non-2xx reply.

type ErrVersionMismatch

type ErrVersionMismatch struct {
	Panel, Agent string
}

ErrVersionMismatch is returned when the agent on a node is not the same build as the panel. The node shows as "agent outdated": the fix is to update the agent service, which is one service update for the whole swarm.

func (ErrVersionMismatch) Error

func (e ErrVersionMismatch) Error() string

type ExecShellReq

type ExecShellReq struct {
	Container string `json:"container"`
	Command   string `json:"command"`
}

ExecShellReq runs one shell command in a container and waits for it. The scheduled-job "exec" mode is the caller; the timeout kill it does on a cancelled context has to happen next to the container, which is why this is its own call rather than two of PathExecRun.

type ExecShellResp

type ExecShellResp struct {
	Output string `json:"output"`
	Error  string `json:"error,omitempty"`
}

ExecShellResp carries the combined output and the command's own failure. The error is a field, not a status code: the output is wanted either way and a failed run records both.

type InfoResp

type InfoResp struct {
	Host   runtime.HostInfo `json:"host"`
	Distro string           `json:"distro"`
}

InfoResp is the node's own description for the server page. HostInfo is the docker daemon's view; Distro is the one thing only the agent can see, since the panel's own container has no idea what the host runs.

type MoveProgress

type MoveProgress struct {
	Bytes int64  `json:"bytes"`
	Total int64  `json:"total"`
	Done  bool   `json:"done"`
	Error string `json:"error,omitempty"`
}

MoveProgress is one line of the send stream: rsync's own byte counters, so the modal's bar and ETA are real numbers and not a guess.

type MoveReceiveReq

type MoveReceiveReq struct {
	MoveID string `json:"move_id"`
	Volume string `json:"volume"`
}

MoveReceiveReq opens the receiving side of a volume move: a container on the stkr overlay with the target volume mounted and an rsync daemon in it, answering to MoveAlias+ID.

type MoveSendReq

type MoveSendReq struct {
	MoveID string `json:"move_id"`
	Volume string `json:"volume"`
	// Target is the receiving agent's alias on the overlay.
	Target string `json:"target"`
}

MoveSendReq runs one rsync pass from the source volume into the receiver opened by MoveReceiveReq. Two passes make a move: the first with the tile running, the second after it stops, carrying only the delta (docs/plans/30-docker-swarm.md, "Moving a volume after the fact").

type Nodes

type Nodes struct {
	RT      *runtime.Runtime
	Key     string
	Version string
	// contains filtered or unexported fields
}

Nodes is the panel's view of the agents, and the one place that decides socket or agent for a call.

Plan 30's "one code path, agent everywhere" is deliberately overruled here as bloat (docs/plans/31-node-agent-open-questions.md, which calls move): on a single node nothing new runs, the panel keeps its own docker socket, and the agent is only ever reached for a container that is on another node.

This is not an interface over runtime.Runtime. Runtime has some sixty methods and only the handful below ever leave the manager; wrapping the whole thing to remote eight calls would be a much larger change for no more behaviour.

func New

func New(rt *runtime.Runtime, version, dataDir string) *Nodes

New builds the panel's node dispatcher. The key is read from the swarm secret mounted into the panel; empty means no agent has been set up yet, which is every single-node install that has never added a node.

func (*Nodes) Client

func (n *Nodes) Client(ctx context.Context, nodeID string) (*Client, error)

Client returns the agent client for one node, or an error when that node's agent task is not running. It is never called for the local node: IsSelf answers that first, and this is the other branch.

func (*Nodes) Info

func (n *Nodes) Info(ctx context.Context, nodeID string) (InfoResp, error)

Info is the docker daemon snapshot of one node, plus the host's distro, which only the agent can see.

func (*Nodes) IsSelf

func (n *Nodes) IsSelf(ctx context.Context, nodeID string) bool

IsSelf reports whether nodeID is this machine. An empty node ID means "wherever it is", which on a single-node install is here, that is what keeps every existing caller working unchanged.

func (*Nodes) Reachable

func (n *Nodes) Reachable(ctx context.Context, nodeID string) bool

Reachable reports whether a node's agent answers. Used by the UI to decide whether exec, stats and volume browse are offered on an off-manager tile.

func (*Nodes) Self

func (n *Nodes) Self(ctx context.Context) string

Self is the swarm node the panel runs on.

type PauseReq

type PauseReq struct {
	Container string `json:"container"`
	Unpause   bool   `json:"unpause"`
}

PauseReq pauses or unpauses one container.

type PruneResp

type PruneResp struct {
	Output string `json:"output"`
}

PruneResp is the human-readable output of an image and container prune.

type SampleReq

type SampleReq struct {
	NodeID   string    `json:"node_id"`
	TS       time.Time `json:"ts"`
	CPUPct   float64   `json:"cpu_pct"`
	MemBytes int64     `json:"mem_bytes"`
	RxBps    float64   `json:"rx_bps"`
	TxBps    float64   `json:"tx_bps"`
	DiskUsed int64     `json:"disk_used"`
}

SampleReq is what an agent posts to the panel on its ticker: one host metrics sample from the node's own /proc. The panel stores it under the server row's ref, so a worker's graphs are the same graphs as the manager's.

type Server

type Server struct {
	RT  *runtime.Runtime
	Key string
	// Version is the binary's build version, echoed on every reply so the
	// panel can refuse a mismatch and show the node as "agent outdated".
	Version string
	// PanelURL is where samples are posted, the panel's service name on the
	// stkr overlay.
	PanelURL string
	// NodeID is this node's swarm ID, so the panel knows whose sample it is.
	NodeID string
}

Server is the agent side: a narrow HTTP surface over this node's own docker socket, plus the two things that are not socket calls at all, the /proc sampler and the volume move.

func (*Server) Handler

func (s *Server) Handler() http.Handler

Handler builds the agent's routes. Every one of them is authenticated by the shared runtime key; there is no unauthenticated surface except the health probe swarm itself uses.

func (*Server) Run

func (s *Server) Run(ctx context.Context) error

Run starts the agent listener and the sampler, and blocks until ctx ends.

The listener binds the node's overlay address only: nothing on the host's LAN can reach it, which is the narrowing plan 30 step 7 asks for.

Fails closed. net.JoinHostPort("", port) is ":port", every interface in the task's netns, so an address lookup that came back empty used to widen the agent instead of narrowing it, and the agent is root on its node by any other name.

type SizeResp

type SizeResp struct {
	Bytes int64 `json:"bytes"`
}

SizeResp is a volume's size in bytes, from du on the node that holds it.

type VolumeReq

type VolumeReq struct {
	Volume string `json:"volume"`
	Dir    string `json:"dir,omitempty"`
	File   string `json:"file,omitempty"`
	// Driver and Opts are the create call's only: a storage sub-path is an
	// nfs, cifs or bind mount, which is driver opts on the volume. Empty
	// Driver means the plain local volume an older panel asked for.
	Driver string            `json:"driver,omitempty"`
	Opts   map[string]string `json:"opts,omitempty"`
}

VolumeReq names a volume, and for the listing a directory inside it.

Jump to

Keyboard shortcuts

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