swarmexec › Docs › TUI: edit a service & the env editor
TUI: edit a service & the env editor_
Every service change behind a, each one rolling update.
On this page
Editing from the inspect overlay
When you inspect a service (not a container/task leaf, whose
overlay stays read-only), the overlay footer also exposes several edit keys, each a
manager-API ServiceUpdate that triggers a rolling update /
reconciliation of the service's tasks.
Start with a — the actions menu
On a service inspect
(service only), a opens a single list of every editor and action the
overlay offers, so you don't have to remember ~14 case-sensitive keys. Every entry
shows its letter in front, and inside the menu that letter selects it —
a S is the secrets editor, a R the
rollback. Only u, d, s, f,
e and X also run straight from the inspect: the lowercase
letters that clash with nothing, and remove, which the footer names. The others
(D/S/R/P next to
d/s/r/p, and p,
l, n, v, r) are menu-only, so a missed
or stray Shift no longer opens an editor the footer never mentioned. Choosing an
entry closes the menu and opens exactly what the direct key opens, so the two are
equivalent, not variants with different behaviour. The entries, in order:
update image version… (set image version… when no newer one was
found — pinning or rolling back to a tag of your choosing is just as valid),
diff spec (previous → current), roll back to the previous version,
placement diagnosis — why a task is missing, scale, force-update,
edit ports, edit labels, edit env, edit networks,
edit secrets, edit mounts, edit resources,
edit placement, remove service
— the destructive one, marked in red — and Cancel. Move with
j/k (g/G jump to the first/last entry),
Enter selects; Esc, or the Cancel entry, closes the
menu without doing anything. The image-version picker is first,
because setting a version is the most ordinary service change there is; its direct
key u still works from any row of the inspect. When the image is one no
version can be chosen for — an untagged reference, or a registry that will not list
the repo's tags, typically a private one the client has no credentials for — the
entry stays in the list and says so rather than quietly
disappearing, and points at the docker service update --image that
does work. Each entry is described below, by its letter in the menu.
Setting a version with u — not only when an update exists
u is not gated on an upgrade being offered. It is available on
any service inspect whose image tags swarmexec could read from the registry —
version-pinned and :latest services alike — and from any row
of the overlay, so you never have to hunt for the hint. Setting the same version again,
pinning what is currently running, or going back to an
older tag are all normal uses; you don't have to wait for an upgrade to
exist. The footer wording tells you which situation you are in:
u update version when a newer version was found (the
newer version available row is there too, carrying a concrete target),
and u set version when it wasn't.
What u opens depends on what the registry knows. On a
version-pinned service with a newer version it is the
version picker: an input whose autocomplete suggests the newer
same-family tags, highest first and prefilled with the highest. On one that is
already on the newest tag it is the same picker, only the suggestions
fall back to every tag the repo lists (prefilled with the running tag) —
that is how you pin or roll back. A service on :latest gets the picker too,
with all known tags: choosing a concrete version there is how you pin a
:latest service off the floating tag, which is exactly the fix the
unpinned-image risk finding (see the security-risks checks) asks for.
The one exception is a :latest service with a digest update
pending — that stays the single confirm on the registry's new
digest it has always been, because a picker there would invite typing
latest, which resolves to the bare tag and would silently drop the very
digest pinning that the update exists to refresh.
In the picker the suggestion list is capped at 25 entries (a busy repo
can list hundreds) and the field stays free-text, so you can
type any existing tag — including an older one to pin or roll back to a
known-good release. A typed tag is validated against the repo (a tag it doesn't list is
rejected), and choosing an older one shows a downgrade warning before it
applies. In every case the change is one ServiceUpdate / rolling update,
behind a confirm. If the registry returned no tags at all and there is no
concrete target to fall back on — a private or unreachable registry, or a service pinned
by digest — you get an explanatory notice and nothing is changed.
Every action
| Key | Action |
|---|---|
| d | diff — shows a unified diff of the service's current spec against its previous one (what the last rolling update changed), using Swarm's PreviousSpec. Changed fields are listed grouped by field with - removed / + added lines (image, mode/replicas, env, labels, networks, aliases, secrets, mounts, ports, placement constraints, spread preferences, resource limits/reservations); unchanged fields are omitted. If the service has never been updated (no previous spec) it says so. Read-only overlay — j/k scroll, Esc closes |
| R | roll back to the previous version (capital R, i.e. Shift+r, to distinguish it from r edit resources) — the counterpart of the d diff above: it undoes the last rolling update. The confirm dialog shows that same diff reversed under “This will undo:”, because that is what the rollback will actually change — a line the update added is listed as - removed, and one it removed comes back as + added. The preview is capped at 12 entries, followed by an “… and N more” note pointing back at d for the full diff (if only metadata changed it says there are no field-level differences). Confirming does a server-side rollback — one manager-API ServiceUpdate with ServiceUpdateOptions{Rollback: "previous"}, not a client-side re-apply of PreviousSpec — so the manager drives it and honours the service's own rollback configuration (parallelism, delay, failure action), and reports progress as the update state rollback_started: exactly the ↺ rolling back badge of the service tree, on the tree row and in this overlay. A service that has never been updated has no previous spec — you get an explanatory notice, not an error. Reached through the a actions menu only (a R). Like every action letter here it is fixed, not a remappable keymap action |
| s | scale — prompts for a new replica count and applies it (replicated services only; a global service reports it can't be scaled) |
| f | force-update — redeploys the service without changing its spec (the equivalent of docker service update --force: bumps TaskTemplate.ForceUpdate), after a confirm. Every task is restarted / rescheduled, which is how you unstick a service sitting in an incomplete state (e.g. 1/2 replicas). One ServiceUpdate (rolling update) |
| X | remove the service (capital X) — permanently deletes it and stops all its tasks, behind a confirm; cannot be undone. One manager-API ServiceRemove; on success the inspect overlay closes and the service tree refreshes. If the service was the sole user of one or more secrets, swarmexec then asks whether to delete those now-orphaned secrets too (secrets still referenced by another service are left alone) |
| D | diagnose placement (capital D) — answers why a service isn't running everywhere you expect in one view, instead of chasing it through several docker commands. For a global service it lists every node with ✓ running or ✗ and the reason it is excluded (availability drain/pause, a down state, an unmet placement constraint, or a platform mismatch) — which is why a 3-node cluster can legitimately show 2/2 (the third node is not eligible). For a replicated service it lists each task that is not running with the scheduler's own message (constraints, insufficient resources, image-pull errors, …). Constraints that can't be checked client-side (engine.labels.*) are noted, not guessed. Read-only overlay |
| p | edit published ports — opens a staged list editor of the service's ports, each in the form PUBLISHED:TARGET[/proto] (proto tcp|udp|sctp, default tcp), e.g. 8080:80/tcp; host-mode ports are shown with a host suffix (8080:80/tcp host), no suffix means ingress. Ports you leave alone are kept exactly as they are. The add/edit input is a wide field that wraps a long entry onto further rows instead of scrolling it out of sight; Enter saves |
| l | edit labels — the same staged list editor over key=value entries. Adding (a) or editing (e) opens a small form with two wrapping fields, key and value, so a long key or a long value such as a Traefik rule stays readable as a whole; Enter moves to the next field |
| e | edit environment variables — opens the service's whole environment as text in a small vim-style editor, one KEY=VALUE per line (e.g. LOG_LEVEL=debug); the key is required, the value may be empty and may itself contain =. A value with newlines, such as GITLAB_OMNIBUS_CONFIG, is written as a heredoc: KEY<<EOF, the value's lines, then a line EOF. Lines starting with # are comments, so commenting a line out removes that variable. :w checks every line first — an error names the line and puts the cursor on it — then shows which keys are added, changed and removed and applies them in one ServiceUpdate (rolling update). :list switches to the staged list editor with your edits carried over. See the env editor below for the keys |
| n | edit networks — a staged list editor over the service's network attachments; attachments you keep retain their aliases and options; since an entry is just a name it's add/remove only (no e edit). The add input autocompletes network names (suggesting networks the service isn't already attached to, or type one yourself). Applying replaces the attachments in one ServiceUpdate. DNS aliases are edited from here too: select a network in this editor and press A to open a staged list of the service's DNS aliases on that network (a add / e edit / d delete / y copy / u undo / Ctrl-S or w apply / Esc cancel); applying replaces that network's aliases in one ServiceUpdate. Works even when the service has no aliases yet. (You must apply a newly-added network first before you can set its aliases.) |
| S | edit secrets (capital S, i.e. Shift+s, to distinguish it from s scale) — the same staged list editor as networks over the secrets the service references; references you keep retain their file name, owner and mode (only newly added secrets get the default /run/secrets/<name>, uid 0, mode 0444); an entry is just a name, so it's add/remove only (no e edit). The add input autocompletes secret names (suggesting secrets the service doesn't already use, or type one yourself). Applying replaces the service's secret references in one ServiceUpdate (rolling update); each secret is mounted at /run/secrets/<name>. Works even when the service currently has no secrets |
| v | edit mounts — a staged list editor over the service's volumes and bind mounts. tmpfs, npipe and cluster mounts are listed too, and mounts you leave alone keep their driver options, labels and tmpfs settings. Adding (a) or editing (e) opens a small form instead of a single text field: a bind mount checkbox, a source (when the box is unchecked it's a volume name with autocomplete of existing cluster volumes; when checked it's a host path), a container path, and a read-only checkbox. The host path and the container path are wide fields that wrap a long path onto further rows, so the whole path stays visible; Enter moves to the next field. (Under the hood each entry is still volume:NAME:TARGET[:ro] / bind:/host/path:TARGET[:ro].) Bind sources and all targets must be absolute paths. Applying replaces the mounts in one ServiceUpdate (rolling update). Bind-mount guard (soft): if the staged list contains any bind mounts, applying first shows a warning listing the nodes the service could be scheduled on (computed from placement constraints plus node role/labels/availability) and reminds you that each bind source must already exist on all of them — swarmexec cannot verify host paths (the agent has no host filesystem access), so bind paths are not autocompleted or existence-checked; it is advisory only |
| r | edit resource limits — a small form to set, change or clear the service's CPU and memory limits (and, optionally, reservations). CPU is given in cores (e.g. 0.5, 2); memory as a human size (e.g. 512m, 2g, 1.5GiB). Leaving a field empty clears that limit (Swarm then treats it as unlimited). A reservation may not exceed its limit. Applying does one ServiceUpdate (rolling update); existing Pids limits and device/generic reservations are preserved |
| P | edit placement (capital P, i.e. Shift+p, to distinguish it from p ports) — opens a small menu with two staged editors: Constraints and Spread preferences.
ServiceUpdate (rolling update); the other part is preserved. |
The staged editors
These editors are staged: a adds an entry, d
deletes the one under the cursor, y copies the selected entry to your
clipboard over OSC52 (so you can grab e.g. a single environment variable while
viewing it), u undoes the last staged change
(add / edit / delete) as long as you haven't applied yet — press it repeatedly to
step back through the staged history — and Ctrl-S (or w) applies all changes at once
in a single ServiceUpdate (so adding, say, several volumes and then
pressing Ctrl-S triggers one rolling update, not one per entry),
behind a confirmation. If you press Esc while changes are still staged,
the editor doesn't silently drop them — it asks whether to apply,
discard, or keep editing.
While changes are still staged they are highlighted so you can
see exactly what will change: added or edited entries show in
green (new) and removed
entries linger as dim red “removed” rows —
the highlighting clears once you apply. The
ports, labels, mounts,
env and aliases editors
(aliases reached from the networks editor via A)
also have e to edit the entry under the cursor; the
networks and secrets editors have no e —
a network or secret entry is just a name, so it's add (a) /
remove (d) only. In the env list editor (reached with
:list) e opens a scrollable multi-line text area
(Ctrl-S save / Esc cancel) for long values; the ports
editor uses a wide input that wraps long values, and editors with
autocomplete (networks, secrets, placement) a single-line input — Enter
confirms in both.
If the service changed while the editor was open. Each editor remembers the service's version from the moment it loaded. If a CI deploy or another operator changed the service meanwhile, applying is refused — nothing is written — with service “NAME” was changed by someone else since you opened this editor (version 5, now 9) — nothing was written. Your staged entries stay on screen, so you can copy them (y), close the editor and reopen it to load the current values, then apply again. Without this check the apply would have rolled the other change back unnoticed.
The env editor
The env editor works like vim, reduced to what editing a list of variables needs. It opens in Normal mode, where keys are commands; i switches to Insert mode to type, Esc back. The status line at the bottom shows the mode, the cursor position and whether anything changed; the footer always shows the keys that matter in the current mode, and ? opens the full list. Esc in Normal mode leaves the editor when nothing changed.
| Keys | Action |
|---|---|
| i a I A o O | insert before / after the cursor, at the line start / end, on a new line below / above |
| h j k l, w b e, 0 ^ $, gg G | move by character and line, by word, to the line start / first non-blank / line end, to the first / last line (the arrow keys work too) |
| /text, n N | search, next / previous match |
| x dd D dw | delete a character, the line, to the line end, to the next word |
| cc cw C r | change the line, the word, to the line end; replace one character |
| yy p P J | copy the line, paste below / above, join the next line |
| u Ctrl-R | undo, redo; a count repeats a command (3dd, 5j) |
| Ctrl-S :w | check and apply, in any mode (also :wq, :x, ZZ). w alone stays the word motion here, unlike the list editors |
| :q :q! | cancel; :q refuses while there are changes, :q! discards them |
| :list :42 ? | switch to the list editor, go to line 42, show the help |
LOG_LEVEL=info
# DEBUG=1
GITLAB_OMNIBUS_CONFIG<<EOF
external_url 'https://gitlab.example.com'
gitlab_rails['backup_keep_time'] = 604800
EOF