Skip to main content

Deployments · Secret managers

Secret managers

Keep your secrets in the secret manager you already use and point a service at them. ComputeSphere reads each value when the service deploys, stores it encrypted and never shows it. Your secret manager stays the place you change it.

How it works​

StepWhat happens
ConnectYou add a secret manager to a project with a credential that can read it, and choose which environments may use it.
ReferenceOn a service or an environment, a secret is set from a secret manager: its name in your service, plus the key to read.
DeployEvery deploy, redeploy, restart and build reads each referenced value again and stores it encrypted with the service's other secrets.
RunThe running service gets the value like any other secret variable.

A change reaches your service on its next deploy or restart. Changing a value in your secret manager doesn't restart anything on its own: redeploy or restart the service when you want the new value live.

Supported secret managers:

Secret managerSign-in methodWhat you choose
DopplerService tokenA project and a config

Connect Doppler​

  1. In Doppler, create a service token for the config you want to read from (read access is enough).
  2. In the console, open your project's menu and choose Secret managers.
  3. Click Connect a secret manager and fill in:
    • Name: lowercase letters, numbers and dashes. Secrets refer to the secret manager by this name.
    • Type: Doppler.
    • Project and Config: the Doppler project and config to read from.
    • Service token: stored encrypted. ComputeSphere never shows it again.
    • Environments that can use it: only these environments can read from it. Choose at least one.
  4. Click Connect, then Test connection. A successful test shows Signed in to name. and the list shows OK under Last test.

If the test fails, the message says why, for example: Couldn't sign in to name. Check the credential, then test again. Fix the token and test again.

To replace the token later, edit the secret manager and enter a new one. Leaving the field empty keeps the stored token.

Use a secret from a secret manager​

On a service:

  1. Open the service, then Settings → Variables → the Secrets tab.
  2. Under From a secret manager, click Add secret.
  3. Enter the Name the service sees (for example DATABASE_URL), choose the Secret manager, and enter the Key: the secret's name in that secret manager. It defaults to the name you entered.
  4. Click Save. The service redeploys and reads the value.

On an environment: open the environment's shared variables and add the secret the same way. The environment's services redeploy and each one gets it, except a service that sets a secret with the same name itself: the service's own value wins.

Each secret from a secret manager shows its state:

StateMeaning
SyncedThe last read worked. The service runs the value it read.
Using last valueThe secret manager didn't answer at the last read. The service keeps the last value it read, and the console shows since when.
Can't readThe secret manager gave a definite answer, for example the key no longer exists or the token was revoked. The message says which.

To link many secrets at once, import a .env file on a service's Secrets tab. A line can set a value, as before, or link the name to a secret in a secret manager:

# Reads DATABASE_URL from app-doppler
DATABASE_URL=ref://app-doppler
# Reads STRIPE_LIVE_KEY from app-doppler, as STRIPE_KEY
STRIPE_KEY=ref://app-doppler/STRIPE_LIVE_KEY
# A value, saved as written
FEATURE_SALT=a-value
  1. Open the service, then Settings → Variables → the Secrets tab, and click Edit.
  2. Click Import .env and paste the file.
  3. Check the rows under the box. Each row shows Value or Link (with the secret manager and key), and its button switches it to the other.
  4. Click Import, then Save. Choose Save & redeploy to deploy now (or Save & rebuild when the change has to reach the build), or Save only to deploy later.

How a line is read:

  • NAME=ref://<secret manager> links NAME to the secret of the same name in that secret manager.
  • NAME=ref://<secret manager>/<key> reads <key> instead. Everything after the secret manager's name is the key, slashes included.
  • A quoted value is a value. DOCS_LINK="ref://app-doppler/x" saves the text ref://app-doppler/x.
  • A link to a secret manager the project doesn't have is an error on its row, never saved as a value. A key can't contain #.

Link all to a secret manager turns every pasted value into a link with the key set to its name, and removes those values from the page at once. It leaves out:

  • names that start with DOPPLER_, which set up the Doppler CLI rather than your app;
  • names that look like a secret manager's own credential, such as VAULT_TOKEN or AWS_SECRET_ACCESS_KEY. Click Include to import one as a link.

When you save, the links are saved first, all or nothing. If a secret can't be read, nothing is saved, and its row says why. Then the values are saved. With Save & redeploy, one deploy then delivers both. A save takes up to 100 links.

A value you turn into a link never leaves your browser: only the link is sent.

When the secret manager doesn't answer, or says no​

No answer (an outage, a timeout, rate limiting): the deploy goes ahead with the last value read, and the secret shows Using last value. There's no time limit on the last value: a long outage on the secret manager's side doesn't take your service down.

A definite answer (the key was deleted, access was revoked, the token no longer signs in): the deploy is refused before anything changes, and the version that's running keeps serving. The deploy's error and the secret's Can't read state say which secret and why. Fix it in your secret manager, or change or remove the reference, then deploy again.

Values are never shown​

ComputeSphere never shows a secret read from a secret manager: it's not in the console or API responses. There's no Show value for it. To check a value, look in your secret manager. (Your own application can still print it, as with any secret variable.)

Remove a secret manager​

Open Secret managers, choose Remove from the secret manager's menu, and confirm. Removing is refused while secrets still read from it: remove those secrets, or set them to plain values, first. After removal, services and environments can't read from it, and its stored sign-in details are deleted.

Current limits​

  • Doppler only for now. Doppler is the secret manager available today.
  • No live sync between deploys. A change in your secret manager reaches the service on its next deploy or restart.
  • Console and API. The CLI commands aren't available yet.

Next​