Skip to content

Secrets at rest & key rotation

Entrepot stores some secrets in Postgres so they can be managed through the API: upstream proxy passwords, S3 secret access keys, scanner secrets (Trivy server token, webhook HMAC key), GitLab API tokens and repository signing keys. They are encrypted with AES-256-GCM before they reach the database, and the API treats them as write-only — they are never returned.

Sealed values carry a key ID (enc:v1:<kid>:…), so several keys can coexist during a rotation.

Key Env Default
secrets.key ENTREPOT_SECRETS_KEY (_FILE supported) derived from auth.sessionSecret
secrets.previousKeys ENTREPOT_SECRETS_PREVIOUSKEYS (comma-separated) none
  • The key must be at least 32 bytes and identical on all replicas (and on scan workers).
  • Without secrets.key, a key derived from auth.sessionSecret is used. Setting a dedicated key lets you rotate the session secret and the secrets key independently — recommended for production.
  • With the Helm chart, put the key under secrets-key in auth.existingSecret, or set secrets.key.
  1. Generate a new key, e.g. openssl rand -base64 48.

  2. Deploy with the new key as secrets.key and the old key in secrets.previousKeys:

    secrets:
    key: <new key>
    previousKeys: [<old key>]

    Old values stay readable through the previous key, and new values are sealed with the current one. At startup values are re-encrypted with the current key.

  3. Once every replica runs with the new key and has started at least once, remove the old key from previousKeys and roll out again.

If you never set secrets.key and want to rotate auth.sessionSecret, do the same: set secrets.key to a new key and list the old session secret in secrets.previousKeys, so the values sealed with the derived key can still be opened. (Rotating the session secret also signs everyone out and invalidates outstanding Docker registry tokens.)

Values written before encryption was enabled are read as-is and re-sealed by the startup migration, so upgrading needs no manual step.