Secret Backends

Every secret in Planton is stored in a secret backend — the store that holds its value. The backend determines where your secrets physically live, and with a real provider backend they live there as native citizens: real values, readable names, your IAM, your audit.

The Built-In Default

Every organization starts with a working default and zero setup:

• Hosted organizations get a Planton-operated OpenBAO vault. Values are stored as native KV entries with per-organization isolation.
• A self-hosted install gets its bundled OpenBAO vault the same way — or, when the install runs with its vault off (spec.vault.enabled: false), the built-in local store below, with its key in a Kubernetes Secret the Planton operator holds. An install can also declare its first organization's default instead: the platform vault, or AWS Secrets Manager reached with the cluster's workload identity.
• A local desktop instance gets the built-in local store: values envelope-encrypted in the instance's own database, with the encryption key minted into the operating system's keychain.

The built-in local store is the one backend where Planton's database is the store — offered only where the install holds its key, and so never on the hosted service.

For teams getting started, the default is the right choice. Connect your own store when you want secrets in your own account.

Bring Your Own Backend

How a Cloud Backend Signs In

Cloud Connection (recommended) — the backend signs in through one of your organization's cloud connections (--aws-connection, --gcp-connection, --azure-connection). With a keyless connection nothing about the backend is stored; with a stored-key connection the key stays in the connection's own secret. Keyless connections need your cloud to reach the install's token issuer over the public internet, so a desktop instance offers none (use a stored-key connection, or Ambient Identity below), and a self-hosted install offers them when its front door is public, over HTTPS, and its vault runs. A connection's own secrets must live in a backend that does not itself sign in through a connection, and a connection a backend signs in through cannot be deleted. See Signed In Through Your Connection.

Inline Credentials — provide static credentials for the store (an AWS access key pair, a GCP service account key, an Azure service principal). They are moved into the platform's internal credential store on save and masked in every response — they never sit in the backend record.

Ambient Identity — provide no credentials at all. The deployment authenticates as itself: the cluster's workload identity on a self-hosted install, or your own signed-in developer CLI on a local desktop instance. On a machine signed into several identities, per-backend handles pin one: an AWS profile, a gcloud configuration, or an az subscription — authenticated through the host's own CLI. Planton's hosted service refuses it, because its identity is Planton's own.

The vault-family backends sign in with a token stored with the backend.

Coordinates and Naming

• Region, project, vault URL, and tenant coordinates accept a literal value or a reference to an org-level variable, so a coordinate maintained in one place serves many backends.
• An optional name prefix (default planton) leads every remote name the backend renders; it is immutable after creation because it is part of every stored secret's address.
• The backend type is likewise immutable — a backend is a stable address, never a moving target. How it signs in can change in place: every secret stays where it is, and a stored key is deleted once the backend signs in another way.

Verify Before You Save

Backend creation ends with a verification probe you can run on the not-yet-saved backend: credential resolution, store reachability, and a real write/read/delete round-trip under the backend's own prefix. The verdict is per-check data, not a boolean — and when an ambient login is broken, the failing check names the exact remedy (gcloud auth application-default login, aws sso login, az login, or the specific config-file problem). The same probe is available any time:

planton secret backend verify my-backend    # exit 1 on unhealthy — scriptable

The Default Backend

Each organization has a default backend, used when a secret does not name one explicitly. Change it to any configured backend. A secret's backend binding is immutable after creation — to move a secret, create it on the target backend and copy the value.

Choosing the Right Backend

Related Documentation

• Where Secrets Live — What lands in your store, and under what name
• Managing Secrets — Creating and referencing secrets
• Variables — Non-sensitive configuration management
• Connections: Cloud Providers — Connecting the cloud accounts your backends live in