Secrets

Versola needs about thirty secrets: encryption and MAC keys, signing key pairs, the Postgres password and the admin bootstrap password. This page explains where they live, what versola configure does with each one, and which ones you can replace safely. Read it before you restore a server, move to a new OpenBao, or rotate a value.

Where secrets live

• local and vps targets. In OpenBao (a Vault-compatible secret store, KV v2, mounted at secret), at secret/versola/<target>/<path>, where <path> is one of auth, central, edge and utils. versola configure starts OpenBao, reads these paths, decides what is missing, writes any new values, and then resolves every ${VAR} placeholder of the generated configuration into <service>.secrets.env files (mode 600) in the deployment bundle. The services never talk to OpenBao at runtime; OpenBao has to be up only while you run configure.
• Kubernetes. In Kubernetes Secrets that you create; the chart neither generates nor requires a particular secret backend. See Kubernetes.

Back up OpenBao’s data and the root token and unseal key in ~/.versola/openbao/vps-admin.json. A secret that protects stored data cannot be regenerated: if it is lost, the data it protects is unreadable.

The secrets

These are the secrets the vps schema lists. “On missing” is the policy explained below.

On Kubernetes the Postgres password and the admin password are operator-supplied (external), and each service has its own POSTGRES_PASSWORD.

The schema

versola-tools writes a secrets.schema.json next to the configuration it generates. It is the single declarative list that versola-cli plans against; it contains names and rules, never values.

onMissing values:

since and the deployment’s recorded revision are how the CLI tells a secret that is new in a release (not in the store because nothing could have put it there: generate it) from one that was lost (stop). The CLI records the schema revision it last applied for a deployment in state.json; a deployment with no record counts as revision 1.

What configure does for each secret

An existing value in OpenBao always wins. The policy only decides what happens when there is none. First configure concludes the state of the deployment from this machine’s record (~/.versola/active/state.json) and from what OpenBao holds:

Per secret the result is one of:

A problem stops the run with nothing written:

POSTGRES_PASSWORD must be identical under auth, central and edge on vps; configure refuses to continue if they differ.

Reading a plan

versola secrets plan <target> <version> prints the same decisions without writing anything, and exits non-zero when there are problems.

versola secrets plan vps <version>

Secrets plan: vps, Versola <version>
Schema revision 2, deployed revision 1 — upgrade (a deployment record exists, OpenBao holds secrets)

  auth     ACCESS_TOKENS_SECRET   keep
  auth     PASSWORDS_SECRET       keep
  edge     EDGE_NATIVE_BLOB_KEY   create (generated, new in this revision)

Result: OK

(Abridged: the real output has one line per secret.) With --json the same report is printed as one object. Secret values never appear in either format.

{
  "version": "<version>",
  "ok": false,
  "target": "vps",
  "state": "upgrade",
  "schemaRevision": 2,
  "deployedRevision": 1,
  "actions": [
    { "service": "auth", "name": "ACCESS_TOKENS_SECRET", "action": "keep" },
    { "service": "edge", "name": "EDGE_NATIVE_BLOB_KEY", "action": "create", "source": "generated", "reason": "new-in-revision" }
  ],
  "problems": [
    { "kind": "lost", "name": "PASSWORDS_SECRET", "services": ["auth"] }
  ]
}

reason is one of first-install, new-in-revision, policy-generate, forced-by-flag, fill-shared, local-throwaway or restart-install. source is generated or stored.

Generating what the plan refuses

When the plan stops because a secret looks lost, the right move is to restore it from a backup. If you know nothing stored depends on it, confirm the generation by name:

versola configure vps <version> --auth-url https://id.example.com --postgres-host 127.0.0.1:5432 --generate-missing EDGE_NATIVE_BLOB_KEY

• The flag takes a comma-separated list of names. It never makes a key group complete by itself: a group is generated only if every member is named.
• Generating a data-bound secret (PASSWORDS_SECRET, REFRESH_TOKENS_SECRET, CLIENT_SECRETS_SECRET, EDGE_TOKEN_ENC_KEY) makes everything it protects unreadable: every login fails, or every refresh token or stored client secret becomes invalid.
• --allow-legacy-secrets is for a release whose tools image writes no schema. Then the CLI cannot tell new from lost and refuses on vps unless OpenBao is empty and no deployment is recorded. With the flag it uses the old rule: anything missing is generated, lost or not.

Rotating a secret

An existing value always wins, so rotating means writing the new value into OpenBao and running configure again. Use bao kv patch, because kv put replaces the whole path:

docker exec -it -e BAO_ADDR=http://127.0.0.1:8200 -e BAO_TOKEN=<root token> versola-openbao-vps \
  bao kv patch -mount=secret versola/vps/auth SESSIONS_SECRET='<new value>'

Then run versola configure vps <current-version> with your usual flags and versola up. Preview with versola secrets plan first.

What you can replace depends on the secret:

The utils key pair

central registers a confidential client named utils for tooling such as loadgen provision and versola-cli, authenticating with private_key_jwt and DPoP. Its key pair is split: the public half (UTILITY_CLIENT_PUBLIC_JWK) goes into central’s configuration, and the private half is stored at secret/versola/<target>/utils (field UTILITY_CLIENT_PRIVATE_JWK) and written to utils.private-key.jwk in the bundle.

central applies the public half on every boot, so a regenerated private key would not match it and would lock out whatever authenticates as utils. The CLI therefore handles this group itself (skip-utils in a plan): the private key already in OpenBao wins, and the public half given to central is derived from it. To reuse an existing key, store it under the utils path before the first configure, or, with the generator on Kubernetes, pass it as the UTILS_PRIVATE_KEY_JWK environment variable (the contents of utils.private-key.jwk). The key must be an EC P-256 private JWK.

A utils client that an older release seeded with a client_secret cannot be switched to a key: a client’s authentication method is fixed when it is created. Delete the utils client so the next boot registers it again, or keep the old bootstrap.utility-client.

Bootstrap seeds apply once

Values in central’s bootstrap block seed the database on its first start against an empty database: the central-admin client and preset, edges, the JWK set, the metadata document, the central resource secret and the utils client. Changing the configuration later does not change what is stored. Change those objects in the admin console, or, for the secrets above, follow the table in Rotating a secret.

The first admin login is separate: auth creates the admin user with the temporary ADMIN_BOOTSTRAP_PASSWORD, valid for 24 hours. Restarting auth after it expires sets a fresh one.

Next steps

• VPS deployment: provision OpenBao yourself and store AppRole credentials.
• CLI reference: flags of secrets login, test and plan.
• Configuration: where each secret enters the configuration files.