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.