swarmexec › Docs › TUI: Volumes, Forwards, Networks, Secrets, Configs
TUI: Volumes, Forwards, Networks, Secrets, Configs_
The other resource tabs, key by key.
On this page
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.
| Key | Action |
|---|---|
| / | search — filter the list by volume name, driver or node |
| n | create 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 |
| space | select / deselect the volume (marked ▣) for a bulk delete |
| a | select / deselect all currently displayed volumes |
| X | delete 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) |
| P | prune: delete every volume no running container mounts and no service declares, behind a confirm |
| Enter | show 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) |
| i | show which services/containers use it |
| A | attach 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 S | cycle 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
| Key | Action |
|---|---|
| Enter | show the forward's full detail (including any error) |
| X | stop the selected forward |
| o | copy 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):
- attachable — green
- internal — yellow
- ingress — gray
- other overlay / swarm-scoped — aqua
- local (
bridge,host, …) — dimmed gray
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:
- red — node addresses (each node's address, plus a manager's advertised address) lie inside the subnet
- yellow — the subnet overlaps the configured underlay, or another network's subnet
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.
| Key | Action |
|---|---|
| a | swarm networks only (the default) / all networks, the manager node's local ones included. A session preference: a cluster switch keeps it |
| n | create 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 / i | show 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) |
| Enter | in 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 |
| A | in 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) |
| a | in 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 |
| d | in 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.
| Key | Action |
|---|---|
| n | create a new secret — opens the secret editor |
| Enter | show the secret's metadata and the services/containers that use it |
| X | on 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 |
| a | in 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 |
| d | in 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 |
| R | in 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.
| Keys | Action |
|---|---|
| :r file | insert 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 :w | create 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.
| Key | Action |
|---|---|
| Enter / i | open the detail overlay: name, id, size, created, updated, the services that mount it, its labels — and the config's content |
| n | create 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 G | in 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.