mcpctl/docs/secret-backends.md

Secret backends

mcpctl stores the raw data for Secret resources in a pluggable backend. The default is plaintext — the secret payload lives in Postgres as plain JSON — which is fine for laptop development but a poor fit for shared clusters. For production, point at an external KV store and delete secrets from the DB after migration.

This guide covers the model, the shipped drivers, and how to migrate without downtime.

Model

• A SecretBackend resource is a single named driver instance (e.g. a pointer at one OpenBao deployment).
• Every Secret row carries a backendId FK — the backend that owns its data.
• Exactly one SecretBackend has isDefault: true. New secrets created through the API/CLI land on that backend.
• The plaintext backend is seeded at startup and named default. It cannot be deleted — there needs to always be one row where the driver's own credentials can bootstrap from (see below).

CLI

mcpctl get secretbackends              # list backends
mcpctl describe secretbackend <name>   # inspect config (credentials masked)
mcpctl create secretbackend <name> --type plaintext [--default] [--description ...]
mcpctl create secretbackend <name> --type openbao \
  --url http://bao.example:8200 \
  --token-secret bao-creds/token \
  [--namespace <ns>] [--mount secret] [--path-prefix mcpctl] \
  [--default]
mcpctl delete secretbackend <name>     # blocked if any secret still points at it

mcpctl migrate secrets --from default --to bao
mcpctl migrate secrets --from default --to bao --names a,b --keep-source
mcpctl migrate secrets --from default --to bao --dry-run

Anything you can do with create secretbackend also works via apply -f:

kind: secretbackend
name: bao
type: openbao
description: "shared cluster OpenBao"
isDefault: true
config:
  url: http://bao.svc.cluster.local:8200
  tokenSecretRef: { name: bao-creds, key: token }
  namespace: platform

Drivers

plaintext

Trivial. Secret.data holds the JSON, externalRef is empty.

• Storage: Postgres column.
• Bootstrap: seeded as default at startup.
• Cost: zero setup, zero encryption at rest, full access for any DB reader.

Use for development, CI, or single-tenant self-hosts where the DB itself is treated as sensitive.

openbao

Talks HTTP to an OpenBao (MPL 2.0 Vault fork) KV v2 mount. Also compatible with HashiCorp Vault KV v2 — the wire protocol is the same.

Config key	Required?	Description
url	yes	Base URL, e.g. http://bao.svc.cluster.local:8200.
tokenSecretRef	yes	{ name, key } pointing at a Secret on the plaintext backend that holds the bootstrap token.
mount	no	KV v2 mount name. Default secret.
pathPrefix	no	Path prefix under the mount. Default mcpctl. Secrets land at <mount>/<pathPrefix>/<secretName>.
namespace	no	X-Vault-Namespace header for OpenBao/Vault Enterprise namespaces.

The driver only stores a reference in Secret.externalRef (mount/path). The Secret.data column is left empty for openbao-backed rows — you can safely drop DB-level access to secrets after migration.

Required OpenBao policy

Minimum token policy for a backend that lives at secret/mcpctl/:

path "secret/data/mcpctl/*" {
  capabilities = ["create", "read", "update"]
}

path "secret/metadata/mcpctl/*" {
  capabilities = ["list", "delete"]
}

path "secret/metadata/mcpctl/" {
  capabilities = ["list"]
}

Grant delete on metadata/... only if you need mcpctl to fully remove secrets — OpenBao soft-deletes until the metadata is gone.

Chicken-and-egg: where does the OpenBao token live?

mcpd reads the OpenBao token from a Secret on the plaintext backend. That's the whole point of keeping plaintext around — it's the trust root:

1. Operator creates a plaintext Secret holding the bootstrap token.
2. Operator creates the openbao backend, pointing at that secret via tokenSecretRef.
3. Operator runs mcpctl migrate secrets --from default --to bao to move all other secrets off plaintext.
4. After migration, the only sensitive row left on plaintext is the OpenBao token itself. DB access is now equivalent to OpenBao token access (a single key), not equivalent to all API keys in the system.

Follow-up work (not shipped yet) replaces static token auth with Kubernetes ServiceAccount auth so no bootstrap token is needed at all.

Migration — mcpctl migrate secrets

Atomicity is per secret, not per batch. Remote writes can't roll back, so we don't pretend. For each secret the service:

1. Reads the plaintext from the source driver.
2. Writes it to the destination driver.
3. Updates the Secret row: flips backendId, sets new externalRef, clears data.
4. Deletes from source (skipped with --keep-source).

If the command is interrupted between step 2 and 3, the destination has an orphan entry but the source still owns the row. Re-running is idempotent — the service skips secrets that are already on the destination and picks up the rest.

# Dry-run first: see what would move.
mcpctl migrate secrets --from default --to bao --dry-run

# Migrate everything.
mcpctl migrate secrets --from default --to bao

# Migrate a subset only.
mcpctl migrate secrets --from default --to bao --names api-keys,oauth-client

# Leave the source copy in place (useful for A/B validation).
mcpctl migrate secrets --from default --to bao --keep-source

The command prints a per-secret summary (migrated / skipped / failed) and exits non-zero if any secret failed. Ctrl-C during the run is safe — restart when you want, no duplicate writes.

RBAC

• resource: secretbackends — gated like any other resource (view, create, edit, delete).
• role: run, action: migrate-secrets — required to call POST /api/v1/secrets/migrate.

Describe output masks config values whose keys look like credentials (token, secret, password, key), so mcpctl describe secretbackend is safe to paste into tickets.