The Deployer documentation
Creating & deploying a project

Environment from a secret manager

Many teams keep passwords and API keys in a secret manager, not in a file: AWS Secrets Manager, Google Secret Manager or Azure Key Vault. The Deployer can fill a service's environment variables from there. It reads the secrets when it deploys, puts the values in the same encrypted environment as every other variable, and picks up a rotated secret on the next deploy.

When this helps

Your repository may already have a script that builds a .env file by asking a secret manager for each value, such as scripts/pull-dev-secrets.sh. The same secrets may feed your test servers or a cluster. Here, the secret manager stays the one place a value is changed, and a deployment always uses today's value.

Set it up

  1. Open Environment variables on the Dashboard and switch to Secret manager.
  2. Choose the service and the secret manager, and click Find in my repository. The Deployer reads your pull script, your workflow files and the comments in .env.example, and proposes the mapping: which variable comes from which secret, in which account and region. It only reads text. Nothing is run and no secret manager is called. You can also type the mapping yourself.
  3. Check the list. Each line is a variable name and the name of the secret. If a secret holds JSON, add the JSON key to take one field of it.
  4. Choose how to read: with a cloud connection you already have, or with a credential just for this source (see below).
  5. Click Test access. The Deployer reads every secret and tells you which ones it could not read, and why. It never shows a value.
  6. Save, then click Sync now or deploy.

Which credential to use

  • A cloud connection you already added for the same cloud. Use this when the secrets are in the same account your app deploys to. Owners and admins can choose any connection. Other team members need the setup right on the project and access to its environment values, because a connection reaches the whole account.
  • A credential for this source. Use this when the secrets are in another account, such as a central secrets account. It can be much narrower than a deployment connection: a user or role that may only read secrets. You provide:
    • AWS: an access key (ID and secret), or a role ARN with an external ID.
    • Google Cloud: a service account key (JSON) with the Secret Manager Secret Accessor role.
    • Azure: a tenant ID, a client ID and a client secret for an app with the Key Vault Secrets User role on the vault.

A credential for a source is write-only. Adding, replacing or removing it asks for your account password, and it is never shown again, not even to you. The source only shows a short hint, such as the last four characters of a key.

The least access to give

For AWS, allow only secretsmanager:GetSecretValue on the secrets you map (and kms:Decrypt if they use your own key). The Deployer also checks which account the credential belongs to and compares it with the account you entered, so a credential from the wrong account is refused.

What happens on a deploy

Reading the secrets is the first thing a deploy does, before anything changes on your servers.

  • Every value is written into the service's encrypted environment, and the app is built and started with it.
  • The source wins. A variable that a secret manager provides is read-only in the dashboard, marked as coming from the secret manager. Change the secret there. Other variables stay yours.
  • If a secret cannot be read, the deploy stops right away and nothing changes on your servers. The message names the variables and the secrets, and why (not found, not allowed, binary, and so on), never a value. Fix the secret or the access and deploy again.
  • Keep the last value. If you prefer that a short outage of the secret manager does not stop a deploy, set the source to keep the last value. A variable that was read before then keeps its last value, with a warning in the log. A variable that was never read still stops the deploy.
  • Removing a variable from the mapping removes it from the environment on the next sync. A secret that disappears from the manager does not: the deploy stops instead, so a deleted secret is never silently dropped.

Each sync that changes anything appears in the environment History, as "Synced from AWS Secrets Manager", with the variable names. Values stay hidden there, as everywhere.

Rotating a secret

Change the secret in your secret manager. The next deploy reads the new value. To apply it to a running app now, click Sync now and deploy on the source, which updates only what changed.

What it will not do

  • Binary secrets. A secret stored as binary data cannot be an environment variable and is refused.
  • Values with line breaks. An environment file holds one line per variable, so a multi-line value (a certificate or a key file) is refused. Use a credential file for those.
  • Copy production's secrets into Dev or UAT. When you add an environment with copied settings, values that came from a secret manager are not copied. Give the new environment its own source, pointing at its own secrets.
  • Blueprints. A blueprint records that a service takes its variables from a secret manager, and the variable names. It never carries a secret name, an account, a region or a credential.

Related