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
- func Ensure(ctx context.Context, store repo.Store, rt *runtime.Runtime, dataDir string) error
- func KeyFile(dataDir string) string
- func PanelImage(ctx context.Context, rt *runtime.Runtime) string
- func ReadKey(dataDir string) string
- func Running(ctx context.Context, rt *runtime.Runtime) bool
- type BoolResp
- type Client
- func (c *Client) CloseMoveReceiver(ctx context.Context, moveID string) error
- func (c *Client) ContainerIsSystem(ctx context.Context, id string) bool
- func (c *Client) CreateVolume(ctx context.Context, vol string) error
- func (c *Client) CreateVolumeOpts(ctx context.Context, vol, driver string, opts map[string]string) error
- func (c *Client) DeleteVolumeFile(ctx context.Context, vol, file string) error
- func (c *Client) ExecShell(ctx context.Context, id, command string) (string, error)
- func (c *Client) ExecStream(ctx context.Context, id string, cmd []string, stdin io.Reader) (io.Reader, func() error, error)
- func (c *Client) ExecTTY(ctx context.Context, id string, cmd []string) (io.ReadWriter, func(w, h uint) error, func(), error)
- func (c *Client) HealthStatus(ctx context.Context, id string) (string, error)
- func (c *Client) Info(ctx context.Context) (InfoResp, error)
- func (c *Client) InspectContainer(ctx context.Context, id string) (*runtime.ContainerDetail, error)
- func (c *Client) ListAll(ctx context.Context) ([]runtime.ManagedContainer, error)
- func (c *Client) ListVolumeFiles(ctx context.Context, vol, dir string) ([]runtime.VolumeEntry, error)
- func (c *Client) ListVolumes(ctx context.Context) ([]runtime.VolumeInfo, error)
- func (c *Client) OpenMoveReceiver(ctx context.Context, moveID, vol string) error
- func (c *Client) PauseContainer(ctx context.Context, id string) error
- func (c *Client) Prune(ctx context.Context) (string, error)
- func (c *Client) ReadVolumeFile(ctx context.Context, vol, file string) (io.ReadCloser, func() error, error)
- func (c *Client) RemoveVolume(ctx context.Context, vol string) error
- func (c *Client) SendMove(ctx context.Context, moveID, vol, target string, ...) error
- func (c *Client) StartContainer(ctx context.Context, id string) error
- func (c *Client) Stats(ctx context.Context, id string) (runtime.ContainerStats, error)
- func (c *Client) StopContainer(ctx context.Context, id string) error
- func (c *Client) StopRemove(ctx context.Context, id string) error
- func (c *Client) StreamLogsMarked(ctx context.Context, id string, tail int) (<-chan string, func(), error)
- func (c *Client) TarVolume(ctx context.Context, vol string, w io.Writer, live bool) error
- func (c *Client) UnpauseContainer(ctx context.Context, id string) error
- func (c *Client) UntarVolume(ctx context.Context, vol string, src io.Reader) error
- func (c *Client) VolumeSize(ctx context.Context, vol string) (int64, error)
- func (c *Client) WriteVolumeFile(ctx context.Context, vol, file string, src io.Reader) error
- type ContainerActionReq
- type ContainerReq
- type ErrResp
- type ErrVersionMismatch
- type ExecShellReq
- type ExecShellResp
- type InfoResp
- type MoveProgress
- type MoveReceiveReq
- type MoveSendReq
- type Nodes
- func (n *Nodes) Client(ctx context.Context, nodeID string) (*Client, error)
- func (n *Nodes) Info(ctx context.Context, nodeID string) (InfoResp, error)
- func (n *Nodes) IsSelf(ctx context.Context, nodeID string) bool
- func (n *Nodes) Reachable(ctx context.Context, nodeID string) bool
- func (n *Nodes) Self(ctx context.Context) string
- type PauseReq
- type PruneResp
- type SampleReq
- type Server
- type SizeResp
- type VolumeReq
Constants ¶
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" )
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.
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.
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 ¶
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 PanelImage ¶
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 ¶
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.
Types ¶
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 ¶
CloseMoveReceiver tears the receiving container down. The volume it wrote stays, it is the point of the move.
func (*Client) ContainerIsSystem ¶
func (*Client) CreateVolume ¶
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 (*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 (*Client) InspectContainer ¶
func (*Client) ListVolumeFiles ¶
func (*Client) ListVolumes ¶
func (*Client) OpenMoveReceiver ¶
OpenMoveReceiver asks this node to accept a volume move into vol.
func (*Client) PauseContainer ¶
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 ¶
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 (*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) UnpauseContainer ¶
func (*Client) UntarVolume ¶
func (*Client) VolumeSize ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
Info is the docker daemon snapshot of one node, plus the host's distro, which only the agent can see.
func (*Nodes) IsSelf ¶
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.
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 ¶
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 ¶
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.