docker-vals

A Docker Compose provider service plugin that resolves ref+<backend>:// URIs via helmfile/vals and injects them as environment variables into dependent containers.

Run docker compose up and secrets from AWS SSM, Vault, 1Password, GCP Secret Manager, and more are automatically injected.

Requirements

• Docker Compose v5.2.0+ (required for rawsetenv protocol support; older versions will not work)
• Backend-specific credentials must be configured on the host where docker compose runs:
  • AWS SSM / Secrets Manager: valid SSO session or credentials in ~/.aws/
  • HashiCorp Vault: VAULT_ADDR and VAULT_TOKEN environment variables
  • GCP Secret Manager: Application Default Credentials
  • 1Password: OP_SERVICE_ACCOUNT_TOKEN for ref+op://, or a signed-in op CLI (see 1Password user accounts)
  • See the vals README for each backend's prerequisites

Install

curl -fsSL https://raw.githubusercontent.com/estie-inc/docker-vals/main/install.sh | sh

Or specify a version:

curl -fsSL https://raw.githubusercontent.com/estie-inc/docker-vals/main/install.sh | sh -s v0.1.0

Installs the plugin to ~/.docker/cli-plugins/docker-vals (macOS / Linux).

On Windows, download docker-vals-windows-amd64.exe from the Releases page and place it at %USERPROFILE%\.docker\cli-plugins\docker-vals.exe.

To build from source instead:

make install

Usage

Add a provider service to your compose.yaml:

services:
  secrets:
    provider:
      type: vals
      options:
        env:
          - "DB_PASSWORD=ref+awsssm:///app-dev/db_password"
          - "API_KEY=ref+vault://secret/data/app#/api_key"
          - "GCP_CREDENTIALS=ref+gcpsecrets://my-project/gcp-creds"

  app:
    image: myapp
    depends_on:
      - secrets
    command: npm start

docker compose up

The plugin uses the rawsetenv protocol, so resolved values are injected into dependent services with their exact variable names. In the example above, app receives DB_PASSWORD, API_KEY, and GCP_CREDENTIALS as environment variables.

Values without the ref+ prefix are passed through as-is.

Tips

Environment switching

Docker Compose expands ${VAR:-default} inside provider options before docker-vals sees them, so standard variable substitution works inside ref+ URIs:

services:
  secrets:
    provider:
      type: vals
      options:
        env:
          - "DB_PASSWORD=ref+awsssm:///app-${VALS_ENV:-dev}/db_password"
          - "API_KEY=ref+awsssm:///app-${VALS_ENV:-dev}/api_key"

  app:
    image: myapp
    depends_on:
      - secrets

docker compose up                    # uses dev (default)
VALS_ENV=staging docker compose up   # uses staging

Local override

Wrap a ref+ URI in ${VAR:-...} so a local env var can skip the secret backend entirely. Values without the ref+ prefix are passed through as-is, so when the env var is set, vals forwards it without any backend lookup.

services:
  secrets:
    provider:
      type: vals
      options:
        env:
          - "DB_PASSWORD=${DB_PASSWORD:-ref+awsssm:///app-dev/db_password}"

docker compose up                       # resolves via ref+ URI
DB_PASSWORD=localpass docker compose up  # uses local value, skips resolution

1Password user accounts

The native ref+op:// backend authenticates through the 1Password SDK, which only accepts a service account token (OP_SERVICE_ACCOUNT_TOKEN). To use your own 1Password account instead, resolve secrets through the op CLI with the exec provider:

services:
  secrets:
    provider:
      type: vals
      options:
        env:
          - "DB_PASSWORD=ref+exec://op?args=read,op://MyVault/db/password"

  app:
    image: myapp
    depends_on:
      - secrets

The plugin runs op as a child process of docker compose up, so it picks up whichever session you already have: the desktop app integration (approval prompt) or an eval $(op signin) session exported in the same shell.

Two details to note:

• Arguments containing / (like op:// URIs) must go in the comma-separated args query parameter; URI path segments are split on /.
• The exec provider times out after 30 seconds by default. If the first run waits on an authorization prompt, extend it with &timeout=60.

Supported Backends

All backends supported by vals are available:

Backend	URI
AWS SSM Parameter Store	ref+awsssm:///path
AWS Secrets Manager	ref+awssecrets://name#/key
HashiCorp Vault	ref+vault://path#/key
1Password	ref+op://vault/item/field
GCP Secret Manager	ref+gcpsecrets://project/secret
Azure Key Vault	ref+azurekeyvault://vault/secret
SOPS	ref+sops://file#/key

See the vals README for the full list.

Build

make build    # Cross-compile binary via Docker
make test     # Run unit tests in Docker
make e2e      # Run E2E tests (requires Docker Compose v5.2.0+)
make install  # Build and install to ~/.docker/cli-plugins/

License

MIT