nodes

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: 15 Imported by: 0

Documentation

Overview

Package nodes keeps the servers table in step with the swarm, pings the nodes, and issues the one-time keys a node joins with.

The swarm is the truth about which nodes exist and what state they are in; the table exists for the things swarm has no opinion on, the display name the operator typed, and a row that exists before its node does (docs/plans/32-multi-node-ui.md).

Index

Constants

View Source
const KeyTTL = time.Hour

KeyTTL is how long a join key lives. Long enough to walk to another machine and paste a command, short enough that a key left in a chat log is not a way into the swarm.

View Source
const LocalID = "local"

LocalID is the row that predates the swarm work: the manager, and the node the panel runs on.

View Source
const PingUnknown = -2

PingUnknown is "nobody has measured this node yet", which is not the same answer as "the node did not reply" and must not be shown as one. A node that joined less than one ping tick ago read as a red "timeout", which is an alarming thing to say about a node that is perfectly fine.

Variables

This section is empty.

Functions

func PingRef

func PingRef(serverID string) string

PingRef is the metrics ref one node's ping samples are stored under, so the server page can chart them with the same code as the host graphs.

The milliseconds go in Metric.CPUPct: one row shape serves every series, and a ping has no memory or byte counters to fill the other columns. The server page has to read the same slot back, which it did not.

func ValidateAddress

func ValidateAddress(addr string) error

ValidateAddress refuses anything that is not a private address.

The overlay data plane is plain VXLAN. A node reachable over the public internet means every byte between tiles crosses it in the clear unless encryption is on, and even then the swarm ports are exposed to everyone, so the address has to be a LAN, a provider private network, or a tunnel (docs/plans/30-docker-swarm.md, step 8, addresses).

Types

type Row

type Row struct {
	Server repo.Server
	Node   *runtime.Node // nil while the row is pending
	// Status is the word the list shows: pending, ready, draining or down.
	Status     string
	Containers int
	// PingMs is the last measured round trip, -1 when it failed,
	// PingUnknown when nothing has measured it yet, and 0 for
	// the manager's own row, which reads "self".
	PingMs float64
	// JoinKey is the key still on offer for a pending row, nil once used or
	// expired.
	JoinKey *repo.JoinKey
}

Row is one line of the servers list: the table row and the swarm node folded together.

type Service

type Service struct {
	Store repo.Store
	RT    *runtime.Runtime
}

Service is the servers screen's back end.

func (*Service) AddNode

func (s *Service) AddNode(ctx context.Context, name, addr string) (*repo.Server, *repo.JoinKey, error)

AddNode creates the pending row and its one-time join key.

One row per address. Adding the same machine twice used to be allowed, and the second row is not harmless: both rows then compete for the same swarm node, only one can claim it, and the loser reads "pending" for good while Sync's adoption loop stays disabled behind it. The operator is told which row already holds the address rather than being given a duplicate.

func (*Service) Claim

func (s *Service) Claim(ctx context.Context, key, nodeID, remoteAddr string) error

Claim attaches a swarm node id to the row its join key was issued for.

The address match on its own could not be relied on: n.Addr is the daemon's swarm advertise address and sv.Address is what the operator typed, and those routinely differ (a machine with several interfaces, a host advertising a tailscale address, a LAN address typed for a node that advertises its bridge). When they did, the row read "pending" for ever, offered a join script that resolved nothing, and, because Sync skips adoption while anything is pending, stopped every other node from being adopted too. The joining machine knows its own id, so it says so.

The key is re-read rather than a second nonce minted: the row exists, the key already carries a TTL and the private-source rail, and the callback happens seconds after the join. It is accepted spent but not expired, which is what JoinKey's separate UsedAt and ExpiresAt are for.

Three refusals stand between this and a hijack: inside the TTL, from a private address, and an id that is really a node in this swarm and is not already held by another row. The key's own row may be overwritten: a node removed and re-added carries a stale id, and the key was minted for exactly that row.

func (*Service) IssueKey

func (s *Service) IssueKey(ctx context.Context, sv *repo.Server) (*repo.JoinKey, error)

IssueKey mints a fresh join key for a pending row, which is what the "new script" button does.

It spends the row's existing keys first. Issuing without revoking is what made "new script" look like a rotation and act like an addition: the key the operator meant to replace kept working for the rest of its hour, and nothing in the product could stop it. One node has one live key by construction, so a leaked script dies the moment a new one is generated.

func (*Service) Ping

func (s *Service) Ping(ctx context.Context)

Ping measures every node once and stores the result. Called on a ticker.

func (*Service) Redeem

func (s *Service) Redeem(ctx context.Context, key, remoteAddr string) (*repo.Server, error)

Redeem checks a join key and burns it, returning the row it belongs to.

One-time and one hour are what actually protect the swarm. The address the key was issued for is a second rail on top, and a deliberately loose one: the joining machine reaches the panel through traefik and, on any LAN whose panel has a public DNS name, through the gateway's NAT as well, so the address the panel observes is routinely the router's and not the node's. Refusing on that mismatch would refuse every ordinary join.

What the rail still catches is the case worth catching: a key used from outside the private network entirely. A public source address means the key left the building, and no legitimate node joins from one, because the whole swarm is private by rule (ValidateAddress).

func (*Service) StoreSample

func (s *Service) StoreSample(ctx context.Context, nodeID string, ts time.Time, sample hostmetrics.HostSample) error

StoreSample records a host metrics sample an agent posted for its node.

func (*Service) Sync

func (s *Service) Sync(ctx context.Context) ([]Row, error)

Sync reconciles `docker node ls` into the servers table and returns the list to render.

Nodes that swarm knows about and the table does not get a row: that is a node joined by hand, or one whose pending row was matched by hostname. Rows whose node has left are kept, not deleted, the operator removed the node, and losing the name they gave it in the same click is worse than a stale row they can delete themselves.

Jump to

Keyboard shortcuts

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