External Secrets¶

External secrets are secrets that are stored in an external secret management service and fetched during a deployment by Doco-CD. This allows you to keep your secrets out of your Git repository and manage them in a secure way.

Supported Secret Provider¶

Setting up an External Secret Provider¶

To use an external secret provider, configure the environment variables for your provider and then set external_secrets in your .doco-cd.yml. See the provider-specific pages for details.

Using External Secrets in Deployments¶

Doco-CD uses variable interpolation to replace variables in your Compose files with the values fetched from the external secret provider, see the Compose file reference for more information and examples.

For example with Bitwarden Secrets Manager, if you want to use secrets named DB_PASSWORD and LABEL_SECRET in your Compose file, you can reference it like this:

name: myapp
external_secrets:
  DB_PASSWORD: a8f1e4eb-d76d-47b4-aa3c-103733e77fce
  LABEL_SECRET: cfd0c4a9-16d4-44c8-9a80-c6143a7c7b71

Then you can use the variable in your Compose file like this:

DB_PASSWORD=testpassword # This will be overridden by the external secret
DOMAIN=example.com

services:
  app:
    image: myapp:latest
    environment:
      DATABASE_HOST: db
      DATABASE_USER: ${$DB_USER:-postgres} # You can also set a default value if the secret is missing
      DATABASE_PASSWORD: $DB_PASSWORD
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.myapp.rule=Host(`myapp.${DOMAIN}`)"  # Note that DOMAIN is set in a local .env file and not fetched from the secret provider
  db:
    image: postgres:latest
    environment:
      POSTGRES_USER: ${$DB_USER:-postgres}
      POSTGRES_PASSWORD: ${DB_PASSWORD}

This will result in the following docker-compose configuration being used during deployment:

services:
  app:
    image: myapp:latest
    environment:
      DATABASE_HOST: db
      DATABASE_USER: postgres
      DATABASE_PASSWORD: supersecretpassword123 # Value of external secret fetched from Bitwarden Secrets Manager
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.myapp.rule=Host(`myapp.example.com`)"  # Value from .env file
  db:
    image: postgres:latest
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: supersecretpassword123 # Value of external secret fetched from Bitwarden Secrets Manager

With Interpolation¶

External-secret references can optionally support Compose-style interpolation using environment variables set on the doco-cd deployment itself. Set INTERPOLATE_EXTERNAL_SECRETS=true to enable this feature. It is disabled by default:

name: myapp
external_secrets:
  DB_PASSWORD: "kv:db-${PROJECT_STAGE:-prod}"

With INTERPOLATE_EXTERNAL_SECRETS=true and PROJECT_STAGE=lab set in the doco-cd container, the provider receives kv:db-lab. If PROJECT_STAGE is not set, the default prod is used.

Defining External Secrets in a File¶

Instead of (or in addition to) declaring external_secrets inline in your .doco-cd.yml, you can set external_secrets_files to a list of YAML files, each holding a map of env var name to external secret reference using the same shape as external_secrets:

name: myapp
external_secrets_files:
  - secrets.yaml

DB_PASSWORD: a8f1e4eb-d76d-47b4-aa3c-103733e77fce
LABEL_SECRET: cfd0c4a9-16d4-44c8-9a80-c6143a7c7b71

File paths are resolved relative to the same directory as dotenv files. Like env_files, you can use the remote:<filepath> syntax to load a file from the remote repository when repository_url is also specified:

name: myapp
repository_url: https://github.com/example/other-repo.git
external_secrets_files:
  - remote:secrets.yaml

Files can also be SOPS-encrypted, the same way encrypted dotenv files are supported.

Referencing Other Resolved Secrets¶

A resolved secret's value can itself reference another external secret by name, letting you compose one secret from others without duplicating values in your Compose file. Set INTERPOLATE_RESOLVED_SECRETS=true to enable this feature. It is disabled by default:

name: myapp
external_secrets:
  DB_PASSWORD: <secret-ref-a>
  DB_HOST: <secret-ref-b>
  DB_URL: <secret-ref-c> # resolves to: postgres://user:${DB_PASSWORD}@${DB_HOST}/mydb

With INTERPOLATE_RESOLVED_SECRETS=true, if the secret provider returns postgres://user:${DB_PASSWORD}@${DB_HOST}/mydb for DB_URL, doco-cd substitutes ${DB_PASSWORD} and ${DB_HOST} with the values of the other resolved external secrets before the value is made available to the Compose file. References can be chained across multiple secrets.