Skip to main content
← Back to list
01Issue
FeatureClosedSwamp ClubPublic
AssigneesNone

Relationships

#2451 Docs: access-commands manual page describes --vault and control-plane failures incorrectly after #2437

Opened by stack72 · 9/23/2026

What changed

swamp-club/swamp#2586 (swamp-club#2437) changed how the token commands handle the _token-secrets control-plane vault and --vault:

  • Local access token mint, access token rotate and worker token create always reject --vault: "--vault is not supported when minting locally - token secrets are always stored in the control-plane vault". They already rejected it whenever the local filesystem control plane initialized, which was nearly always. The only time --vault was honoured was the silent-fallback bug that PR removed.
  • worker token create --server --vault <v> is unchanged: serve stores the plaintext in that server vault.
  • If the control-plane vault cannot initialize (bad or expired datastore credentials, an unreachable datastore, a damaged local key), mint, rotate, reveal and worker token create fail with the underlying error and a hint. They no longer fall back to a user vault.

Stale manual text

content/manual/reference/swamp-serve/access-commands.md:

  • Around lines 44–47: "The --vault flag is rejected in this mode because storage is managed by the control plane. For local repos without a datastore, the plaintext is stored in the vault selected by --vault." The second sentence is wrong. Local repos also use the control-plane vault, and --vault is rejected.
  • Line 58, the options table: "--vault … Vault for the token plaintext (rejected when a datastore is configured — secrets use the control-plane vault)". This should say it is not supported for local mint and rotate, and that passing it prints how to copy the credential into another vault.
  • Around line 95: "For local repos without a datastore, it is stored in the …" needs the same correction.
  • The worker token create section, if present: --vault applies only with --server.

Suggested additions

  • A short "When the control-plane vault can't start" note: the commands fail with Failed to initialize the _token-secrets control-plane vault (remote datastore|local control plane): <cause>, and the fix is to repair datastore access. Do not create a vault named _token-secrets, because vault create rejects _ names.
  • A note that a token whose secret is still in a user vault (minted before swamp-club#1717) cannot be revealed while the control plane is broken, and that rotate migrates it.
02Bog Flow
✓OPEN○TRIAGED○IN PROGRESS◉CLOSED

Closed

9/23/2026, 10:33:00 PM

No activity in this phase yet.

03Sludge Pulse
Editable. Press Enter to edit.

stack72 commented 9/23/2026, 10:33:00 PM

Fixed in https://github.com/swamp-club/swamp-club/pull/1247 — access-commands.md now says token secrets always live in the _token-secrets control-plane vault, --vault is rejected (locally and with --server), and documents the control-plane vault init failures and legacy user-vault tokens. worker-commands.md updated to match.

Sign in to post a ripple.