Give a deployment a credential

Goal

A deployment reading a password or an API key at start-up, with the material stored outside the description and out of version control.

Before you start

• A deployment you can update.
• A name for the credential based on what it belongs to, not on which deployment reads it — see secrets.

Dashboard

Steps

1. Open the deployment and choose Secrets.
2. Add a reference, naming the credential’s path.
3. Either paste the material, or ask the platform to mint it and say which keys and how long.
4. Save. The material is stored outside the description; the description keeps only the reference.

YAML manifest

Steps

1. Add a secrets entry with the credential’s path.
2. Supply the material inline, or declare that the platform should generate it.
3. Apply the document. The material is written away and stripped before the description is stored, so what is kept is identical to a reference-only document. The fields are in the deployment reference.

REST API

Steps

1. PUT /api/v1/deployments/{name} with the secrets list. Remember that sending the list replaces the stored one, so send it whole.
2. GET /api/v1/secrets/resources to see every credential path referenced in your tenant.
3. GET /api/v1/secrets/resources/{name}/consumers before you rotate, to see who reads it.
4. POST /api/v1/deployments/{name}/secrets/rotate to rotate and restart.

Secrets as files

Delivery is by environment variable. A path that asks for the material to be mounted as a file is refused rather than quietly ignored, and the refusal says so — an application that must read a file should render it from its environment at start-up, in its own entrypoint.

Verify

The deployment starts and the application finds its credential. Nothing in the stored description contains the material, and no route returns it.

Evidence this worked

GET /api/v1/deployments/{name} shows the reference and never the value. The consumers route lists this deployment under the credential, which is what makes rotation safe: the readers are derived from the stored descriptions on every call, so the answer cannot go stale.

When it fails

• The path is refused for its shape. A path is <namespace>/<name>, and the first segment must be one of the granted namespaces — the first segment is the namespace that every Vault policy grant is written against.
• The path is refused as a split. The same credential is already referenced under another namespace: the same credential under two namespaces is two Vault documents that must be kept identical by hand. The refusal names the other deployment and the single path to converge on.
• The deployment starts without the credential. An update that sent a shorter secrets list replaced the stored one. See sending part of a description.
• Every code: rejections and alterations.