Secrets and Vault Best Practices

Sensitive values — database passwords, API keys, signing tokens, private certificates — need to live somewhere your application can reach at runtime but that never ends up in a log line, a source repository, or a container image. Bahriya's vault exists for exactly this. This article collects the practices that keep those values safe.

Never bake secrets into your image

A container image is not a secret store. Anything you COPY in, set with a build-time ENV, or hard-code in your source travels with the image everywhere it goes — your registry, every region it deploys to, and anyone who can pull it. Rotating a leaked value then means rebuilding and re-releasing.

Keep credentials out of the image entirely and inject them at runtime instead:

• Store the value as a secret in the vault.
• Attach the secret to the project.
• Wire it to the container as an environment variable.

The plaintext is only ever materialised at deployment time and discarded immediately afterwards. See Secrets for the full lifecycle.

Use the right vault item for the job

Every vault item is encrypted at rest, surfaced as metadata only, and decrypted solely at deploy time. Plain environment variables, by contrast, are visible in the console and stored unencrypted — use them for non-sensitive configuration only.

Rotate on a schedule and after any exposure

Secrets and TLS bundles are versioned. The first value is v1; rotating creates a new current version and keeps the previous one for rollback. Rotate whenever you:

• Reach a scheduled rotation interval.
• Suspect a value has been exposed.
• Cycle a third-party token.

After rotation, containers pick up the new value on their next deployment. If a rotation breaks something, activate the previous version to roll back instantly rather than re-entering the old value by hand.

Apply least privilege

• Attach only where needed. A vault item lives at the organisation level, but a project can only use it once it has been attached. Attach a secret to the projects that genuinely need it, not to every project by default.
• Wire only the containers that use it. A single secret can be wired into many containers, but each wiring is explicit. Grant a value to a workload only when that workload reads it.
• Scope access by role. Role-based access control governs who can create, attach, and rotate vault items. Give people the narrowest role that lets them do their job. See Security overview.

Deploy per region deliberately

Vault items are applied to each region where an attached container runs, and billed per region. Deploy a secret only to the regions you actually run in — running in three regions means the value is provisioned to three regions and metered accordingly. Choosing regions carefully keeps both your exposure surface and your bill smaller. See Regions.

Delete cleanly

Before deleting a secret, unwire it from every container and detach it from every project. A container that still expects a deleted value will fail to start on its next deployment. Note that a handle is permanently consumed once used — you cannot recreate a secret under the same handle after deletion.

Related

• Secrets
• Registries
• TLS Bundles
• Security overview