swarmexec

swarmexec › Docs › TUI: Volumes, Forwards, Networks, Secrets, Configs

TUI: Volumes, Forwards, Networks, Secrets, Configs_

The other resource tabs, key by key.

Volumes tab

Columns: VOLUME, SIZE, NODES (count and names), USED BY, DRIVER, AGE. Size and nodes come first so they stay on screen at 80 columns; a long volume name or node list is cut with … (the full one is in Enter, i and the y copy), and an anonymous volume's 64-character hex name shows its first 12 characters.

KeyAction
/search — filter the list by volume name, driver or node
ncreate a volume — a form with name, driver (default local), labels (k=v,k=v) and a node target (autocompletes node names; leave blank to create on every node, since volumes are node-local). Creates it on each target node's agent and reports per-node success/failure. Tab moves between fields, Esc cancels
spaceselect / deselect the volume (marked ▣) for a bulk delete
aselect / deselect all currently displayed volumes
Xdelete the selected volumes — or the one under the cursor — on every node that holds them, behind a confirm (with a progress overlay; deletes run with bounded parallelism)
Pprune: delete every volume no running container mounts and no service declares, behind a confirm
Entershow which nodes hold the volume; the volume's labels are listed read-only above the nodes (Docker has no volume-update API, so labels can't be edited after creation — set them when you create the volume)
ishow which services/containers use it
Aattach the volume to a service: pick a service (name autocomplete) → enter the container target path (absolute) → choose Attach or Attach read-only. Adds the mount via one ServiceUpdate (rolling update) — the volume counterpart to the network/secret attach actions; the reverse lives in the service inspect v mounts editor
s Scycle the sort field (name → nodes → used → age → size) / reverse

Deleting is node-aware: a volume is removed on every node holding it. Prune spares volumes a service declares even when no task is running, so it won't wipe a stopped stack's data. For finer control, Enter opens the per-node list where space selects nodes, X deletes the highlighted node's copy and a deletes on all nodes — each behind a confirmation.

Forwards tab

KeyAction
Entershow the forward's full detail (including any error)
Xstop the selected forward
ocopy the forward's URL (http://<address>:<port>; a forward on 0.0.0.0 is copied as 127.0.0.1)

A running container is annotated in the tree as local→remote (e.g. 9090→8080). Forwards keep running when their overlay closes and when you switch to another cluster; they stop on X or when you quit the UI. The CLUSTER column names the context each one belongs to, dimmed for the cluster you are currently looking at — a forward on another cluster is still yours and still listening, but its CONTAINER and NODE name things you cannot see from here. The tree annotation is per cluster for the same reason: a container id is only unique within its own daemon.

Because of that, a local port you are already using is refused up front, naming the forward that holds it and the cluster it belongs to — the form stays open so you can pick another port. The operating system's own "address already in use" is kept for the case it is right about: a port held by some other program, which swarmexec cannot name.

p on a container opens the Port Forward dialog with three fields, in k9s's order — Container Port, Local Port and Address — above a Forward and a Cancel button. The container port is suggested from the container's real ports — the target ports of the service's endpoint (from the manager, works with any agent) and the ports the image EXPOSEs (from the agent on the container's node; needs an agent that reports them, older agents simply contribute nothing). The first suggestion is filled in, the hint line lists the rest and ↓ opens them as a drop-down; any other port can still be typed. The local port follows the container port until you change it. The address defaults to 127.0.0.1; anything that is not loopback (e.g. 0.0.0.0) shows a yellow reachable from your network warning, and the Forwards tab shows that forward's address in yellow too. Tab and Shift-Tab move through the fields and the buttons, Enter in any field (or on Forward) starts the forward and Esc cancels; a typo or an occupied port keeps the form open with the reason.

Networks tab

A list of the swarm's networks — scope swarm by default; a adds the manager's local ones (bridge, docker_gwbridge, host, none, compose project networks). Those come from the manager node's own daemon and exist there only — every other node has its own set — so while they are shown the status line says + local networks of the manager node only; a again hides them. Columns: name, driver, scope, type (ingress / internal / attachable), its subnet, whether the network is encrypted, how many services attach to each and how many containers (running tasks, from one cluster-wide task list) are attached right now, followed by the addresses the nodes know (endpoints and stale addresses). The TYPE column shows overlay or the driver name (e.g. bridge) for plain networks rather than a dash. The ENC column shows 🔒 yes when the overlay network has data-plane encryption on (created with --opt encrypted), else a dash. AGE — here as on the Volumes, Secrets and Configs tabs — is compact: 3d4h up to 30 days, then whole months (3mo) and years (4y). Each network's name and its TYPE cell are colour-coded by kind (highest priority first):

Subnet overlap check

Overlay subnets must not overlap the network the hosts themselves sit on (the underlay). If a subnet contains a node's address, containers on that network cannot reach that host, and IPAM may even hand a container the host's IP. Docker does not check this, and the swarm's default address pool is 10.0.0.0/8 — exactly where many cloud private networks live. The SUBNET cell gets a ⚠ marker:

The underlay is optional, per Docker context, in the config file (contexts.<name>.underlay, e.g. [10.0.0.0/16]); without it only node addresses count. The members view (Enter) shows the subnet, gateway and container count at the top, each finding in full, and the fix: an existing network cannot be renumbered — detach its services, remove it and recreate it with an explicit subnet outside the hosts' network (e.g. --subnet 10.100.1.0/24), then re-attach. The default address pool can only be set at docker swarm init --default-addr-pool.

Creating a network (n) runs the same check first. If the entered subnet contains node addresses or overlaps the underlay or an existing network, a Create anyway? dialog lists the findings instead of creating directly. With the subnet left empty on an overlay network, swarmexec reads the swarm's default address pool (10.0.0.0/8 when none was set at init); if node addresses or the underlay lie inside it, it warns that Docker will pick a /24 from that pool which may overlap the hosts, and suggests an explicit subnet — you can still create after confirming.

The dialog also proposes rather than merely objects: a concrete free subnet, drawn from a range clear of the node addresses, the underlay, every existing network and the swarm's default pool — and, when contexts.<name>.underlay_mtu is set, the MTU the overlay should carry. That second one is easy to get wrong in a way nothing reports: com.docker.network.driver.mtu states the underlay's MTU and Docker subtracts 50 bytes of VXLAN overhead from it, so its default of 1500 on a 1450-byte link produces frames that are dropped in silence — which reads as a slow or flaky connection rather than a broken one. Set the option to the link's own MTU and containers get exactly what fits. Both are suggestions: whether to accept an overlap is your call, and the moment after the network exists is the moment it can no longer be changed without detaching every service from it.

Endpoints and stale addresses

Every node's daemon keeps its own copy (networkdb) of an overlay network's endpoints — each one an IP and a MAC. A node that missed a departure keeps the departed endpoint, and its traffic to that address goes nowhere; the manager has long forgotten it. On entering the tab (and on r) swarmexec asks every node's agent once, in the background, for its view of all overlay networks (the NetworkEndpoints RPC, policy action network.inspect) and compares it with the manager's tasks. The CONTAINERS cell then reads e.g. 12 · 14 addr ⚠2 stale: 12 running tasks, 14 task addresses the nodes know (load-balancer endpoints not counted), 2 of them stale candidates — the cell turns yellow. ⚠1 dup counts an IP or MAC held by two endpoints; a trailing +2 n/a means two nodes could not answer, and a gray n/a alone that none could — the status line then reads n/a: node agent not reachable.

A stale candidate is a task endpoint (networkdb entry, or an endpoint attached on the node) whose address no live task has, that is not a load-balancer endpoint or a service VIP. An endpoint without a container (ep-…) counts too. The members view (Enter) shows the summary in its header and, below the services, one row per node — running tasks the manager places there, the node's local containers + load-balancer endpoint, its MACs and its networkdb entries — then every stale candidate (IP, MAC when still attached, task name, owning node, which nodes still list it) and every duplicate. A node whose agent predates the RPC shows agent too old — update the agent image (an image update is enough, no init --force).

It is a heuristic. A task that started or stopped between the two reads can show as stale for one refresh; a standalone container on an attachable network whose name looks like a task's is flagged too. It misses a leftover whose address has since gone to a new task (the duplicate check may still catch it), and leftovers the daemon has already dropped from its networkdb while the kernel still holds them (the agent reads the Docker API only, not the kernel's forwarding table). Stale entries usually clear once the leftover endpoint is removed on a node that lists it — docker network disconnect -f <network> <endpoint name> — or after restarting Docker on the node that held it.

KeyAction
aswarm networks only (the default) / all networks, the manager node's local ones included. A session preference: a cluster switch keeps it
ncreate a network — opens a form (default driver overlay) with the common swarm options: attachable (let standalone containers join), encrypted (overlay data-plane encryption), internal (no external routing), IPv6, an optional MTU, an optional subnet/gateway (IPAM) and labels (k=v,k=v). Tab moves between fields, Enter on Create confirms, Esc cancels. Creates it via one manager-API NetworkCreate, then refreshes the tab
Enter / ishow the attached services, each with its running containers nested underneath. The network's own labels are listed read-only at the top (Docker has no network-update API, so network labels can't be edited after creation — set them when you create the network). Each service header also shows how many DNS aliases it has on this network (or no aliases)
Enterin the members view: expand / collapse the selected service's DNS aliases (kept collapsed by default so the list stays compact); the aliases appear indented under the service header
Ain the members view: add / edit the selected service's DNS aliases on this network — opens the same staged alias editor as the inspect view (a add / e edit / d delete / Ctrl-S or w apply / Esc cancel); applying replaces that network's aliases in one ServiceUpdate and refreshes the view. Works even when the service has no aliases yet. (A is capital, Shift+a, to distinguish it from a attach; standalone non-swarm containers are not editable — aliases are a per-service ServiceUpdate)
ain the members view: attach a service to this network — an autocomplete input (suggesting services not already attached; you may also type any name), then a rolling-update confirmation
din the members view: detach a service from this network — an autocomplete input (suggesting the services currently attached; you may also type any name), then a rolling-update confirmation. Drawn red in the footer and the ? overlay: it restarts the service's tasks

Attaching or detaching does a service update that adds or removes the network in the service spec, then refreshes the Networks tab. This is a manager-API operation (ServiceUpdate) — the same channel the client uses for topology — and it triggers a rolling update that restarts the service's tasks.

Secrets tab

A read-only list of the swarm's secrets — name, how many services use each, age, last update and label count. Secret values are never shown: the Docker API does not expose them.

KeyAction
ncreate a new secret — opens the secret editor
Entershow the secret's metadata and the services/containers that use it
Xon the secrets list: delete the selected secret — permanently removes it (one SecretRemove), behind a confirm; cannot be undone. Docker refuses to remove a secret still referenced by a service, so the confirm warns when it's in use and lists those services (detach it there first). Not to be confused with the d inside the detail view, which detaches the secret from a service
ain the detail view: attach the secret to a service — an autocomplete input (suggesting services that don't already use it; you may also type any name), then a rolling-update confirmation
din the detail view: detach the secret from a service — an autocomplete input (suggesting services that currently use it; you may also type any name), then a rolling-update confirmation. Drawn red in the footer and the ? overlay: it restarts the service's tasks
Rin the detail view: rotate — give the secret new content and keep its name (how it works). Opens the secret editor with the name and labels shown but fixed, and an empty value to type or :r a file into; :w lists the services that will restart and their target paths, warns that each restarts twice and that there is no rollback, and adds the file: hint for a stack's secret. After the confirm a progress overlay follows the six steps (Esc hides it, the rotation carries on); success is flashed, a failure says which step and that pressing R on the secret again resumes. On an interrupted rotation's NAME_rotating row, R resumes the rotation of NAME

Attaching adds the secret to the service, mounted at /run/secrets/<name> (like docker service update --secret-add); detaching removes the secret reference. Then the Secrets tab refreshes. Like the network attach/detach, each is a manager-API ServiceUpdate that triggers a rolling update restarting the service's tasks.

The secret editor

n opens one large dialog: Name and Labels (k=v,k=v, optional) at the top, and below them the value in the same vim-style editor as the env editor, taking all the remaining height (and more of the screen on a big terminal). Focus starts on Name. Tab / Enter move Name → Labels → value, Shift-Tab goes back; in the value, Tab moves only in Normal mode — in Insert mode it types a tab, which files may need. Esc in Name or Labels goes to the value, or closes the dialog while nothing has been entered. The status line shows the value's size in lines and bytes, red once it is over the limit.

KeysAction
:r fileinsert a local file at the cursor (also :read; ~ expands to your home directory, a relative path is relative to where swarmexec runs) — the practical way to make a secret from a certificate, a key or a JSON file
Ctrl-S :wcreate the secret (also :wq, :x, ZZ; Ctrl-S works in Name and Labels too). An empty name, malformed labels, an empty value or one over the limit is reported on the status line and the dialog stays open
:q :q!cancel; :q refuses once anything was entered (the name and labels count), :q! discards it

The value is sent byte for byte as the editor holds it: no trailing newline is added or removed, so a typed password is exactly what you typed, and a file read with :r keeps its own line endings and final newline. Swarm limits a secret to 500 KB (512000 bytes). The editor holds text only: :r refuses a file that is not UTF-8 or contains NUL bytes — create a binary secret (a keystore, a DER certificate) with docker secret create NAME FILE instead.

Configs tab

Tab 7 — the Secrets tab's twin for the other object swarm hands to containers, with one decisive difference: a config's content is readable. The Secrets tab can never show a value (the Docker API does not return it); the config detail shows the actual content, so you can see what a service really receives without dropping to docker config inspect. That is the point of this tab.

Columns: CONFIG (name), USED BY (how many services mount it), SIZE, AGE, UPDATED and LABELS (count). Like secrets, configs are immutable: the tab creates them, but a new content is a new config.

KeyAction
Enter / iopen the detail overlay: name, id, size, created, updated, the services that mount it, its labels — and the config's content
ncreate a config — the same dialog as the secret editor: Name, optional Labels (k=v,k=v) and the content in the vim editor (:r file reads a local text file). Ctrl-S or :w creates it through the manager API; a taken name is refused. The limit is swarm's 1000 KB for a config (a secret's is 500 KB), binary files go through docker config create. Remappable as config_new
j k / g Gin the detail overlay: scroll · jump to top / bottom (Esc closes)

The content is fetched on demand, when the overlay opens — not together with the list — because a config can be a whole nginx.conf; the overlay shows loading… until it arrives, and an empty config says (empty). What you get is a preview, capped at both 64 KiB and 500 lines. Both caps are needed: bounding only the bytes still lets a file of very short lines become tens of thousands of rendered rows — each indented — which is what actually makes the view crawl. Truncation is always stated (“… truncated at 500 lines”, or at the byte cap), never a silent cut, and binary content is reported, not dumped (“(binary content, N — not shown)”, decided by looking for NUL bytes in the head of the payload). The whole config is one docker config inspect away.

USED BY is derived exactly the way the Secrets tab derives it: swarm keeps no reverse index from a config to its consumers, so swarmexec reads the service specs (one ServiceList) and matches a reference by config ID or name — a spec may carry either form, so both are looked up and merged. Best-effort: if the service list can't be read, the configs still render, just without membership.