berglas exec: Inject GCP Berglas Secrets
berglas exec finds environment variables set to berglas:// references, resolves them to plaintext, and runs the command with the real values.
Berglas stores secrets in a GCS bucket encrypted with Cloud KMS, or in Secret Manager. berglas exec resolves references at runtime so a container gets plaintext env vars without baking them in.
What it does
berglas exec scans the current environment for values shaped like berglas://<bucket>/<object> or sm://<project>/<secret>, decrypts each via KMS or Secret Manager, replaces the variable with the plaintext, and executes the given command.
Common usage
export DB_PASSWORD=berglas://my-secrets/db-password
berglas exec -- ./server
# read a single value directly
berglas access berglas://my-secrets/db-passwordOptions
| Command / Flag | What it does |
|---|---|
| exec -- <command> | Resolve berglas:// env vars and run the command |
| access <reference> | Print the plaintext of a single reference |
| --local | Resolve references from the local environment only |
| berglas:// or sm:// reference | GCS+KMS or Secret Manager backed secret path |
In CI
Grant the runner service account roles/cloudkms.cryptoKeyDecrypter and storage object read on the bucket (or secretAccessor for sm:// references). Set the env vars to references and let berglas exec resolve them into the child process only. Do not print resolved values.
Common errors in CI
A "PermissionDenied" on KMS decrypt means the service account lacks cryptoKeyDecrypter. "storage: object doesn't exist" means the berglas:// path is wrong or the bucket is in another project. "could not find default credentials" means gcloud/ADC auth is not set up on the runner.