GoogleCloudPlatform/berglas: secrets as KMS encrypted objects in a Cloud Storage bucket

Two storage backends, one command line

Berglas is a command line tool and library for storing and retrieving secrets on Google Cloud. The mechanism is deliberately simple: secrets are encrypted with Cloud KMS and stored in Cloud Storage, and an interoperable layer also exists with Secret Manager.

So there are two backends for the same concept. The `sm://` scheme addresses Secret Manager, and a bucket path addresses Cloud Storage. The commands look nearly identical between them, which is the point of the design, because the choice of backend becomes a decision you make at the URL level rather than a different tool for each store.

The tool has two faces. As a CLI, it automates the process of encrypting, decrypting and storing data on Google Cloud. As a library, it automates the inclusion of secrets into various Google Cloud runtimes, which is the harder part of the problem, since a secret that sits in a store is worth nothing until it reaches the process that needs it.

The module path tells you about the project's history, since the go.mod declares `github.com/GoogleCloudPlatform/berglas/v2`, so the major version is two and the current code lives in that module. It targets Go 1.26.6 and depends on the Cloud KMS, Secret Manager, Storage and IAM client libraries, on cobra for the command line, and on gRPC and the Google API client underneath them.

The disclaimer that comes before everything else

The second line of the README's description of the tool is that Berglas is not an officially supported Google product.

It is worth sitting with that for a moment, because the repository lives under the GoogleCloudPlatform organisation, the badges point at Google Cloud documentation, and the setup instructions tell you to enable Google Cloud services and configure IAM policies. Everything about the presentation suggests a first party tool, and the one sentence that says otherwise is easy to skim past.

What it means in practice is that you are adopting a community maintained tool that depends on Google Cloud services, without a Google support contract behind it. The code is Apache-2.0 licensed and the releases are frequent, with v2.0.15 on 2026-07-21, v2.0.16 on 2026-08-17 and v2.0.17 on 2026-09-03, and the last push was on 2026-09-18. Not every dependency is a Google library, though: the module also pulls in cobra and a retry helper.

That is a reasonable position for a tool that glues Google services together, but it is a different position from a Google supported product, and an organisation with a policy on vendor support for its secrets infrastructure needs to know which side of that line it is on.

Setup: credentials, the project ID, and the services to enable

The prerequisites are the Cloud SDK for your operating system, or you can run the commands from Cloud Shell, which has the SDK and other popular tools pre-installed. If you are running from a local machine you also need Default Application Credentials, obtained with:

gcloud auth application-default login

That opens a browser and prompts for a Google account login, and on headless devices you need to create a service account instead, which the README points at its authentication section for.

The project identity is the next step, and the documentation is emphatic about a distinction that causes real errors. Export your project ID as an environment variable, and note that it is the project ID, not the project name or project number, which you can find by running `gcloud projects list` or in the web UI:

export PROJECT_ID=my-gcp-project-id

Then the services differ depending on which backend you use. For Secret Manager storage it is one service:

gcloud services enable --project ${PROJECT_ID} \
  secretmanager.googleapis.com

For Cloud Storage storage it is three, Cloud KMS plus the two Storage services:

gcloud services enable --project ${PROJECT_ID} \
  cloudkms.googleapis.com \
  storage-api.googleapis.com \
  storage-component.googleapis.com

That difference is the first hint of the operational difference between the backends, since the Cloud Storage path needs a KMS key and a bucket in addition to the secret itself.

bootstrap expects a bucket that does not exist yet

Bootstrapping a Berglas environment is one command, and it creates both halves of the storage setup:

berglas bootstrap --project $PROJECT_ID --bucket $BUCKET_ID

The bucket name is exported separately and there are two constraints on it. It is the name only, without the `gs://` prefix, and, in bold in the documentation, this bucket should not exist yet.

That second constraint is the sort of thing that produces a confusing failure. Bootstrap is the command that creates the bucket, so pointing it at a bucket that already exists means the command is trying to create something that is already there. If you want full control over the creation of the bucket and the KMS key, the README points at a custom setup page, and the flags for the bucket and key configuration are documented under `berglas bootstrap -h`.

The location of the bucket is an optional flag, and the default is the multi-regional location `US`:

export BUCKET_LOCATION=europe-west1
berglas bootstrap \
  --project $PROJECT_ID \
  --bucket $BUCKET_ID \
  --bucket-location $BUCKET_LOCATION

The list of supported locations is in the Cloud Storage bucket location documentation, and the data residency implication is obvious: a multi-regional default for a bucket that holds encrypted secrets is a decision that a European or Asian deployment will want to override.

The daily verbs: create, grant, access, and spawning a process

The CLI surface is small and the two backends mirror each other. Creating a secret with Secret Manager storage is:

berglas create sm://${PROJECT_ID}/foo my-secret-data

and with Cloud Storage storage it is the same idea with the bucket path and an explicit key:

berglas create ${BUCKET_ID}/foo my-secret-data \
  --key projects/${PROJECT_ID}/locations/global/keyRings/berglas/cryptoKeys/berglas-key

Granting access to a secret is a single command with a member, again in both flavours, `berglas grant sm://${PROJECT_ID}/foo --member user:[email protected]` for Secret Manager and `berglas grant ${BUCKET_ID}/foo --member user:[email protected]` for the bucket.

Reading the data back is `berglas access`, which prints the plaintext, and the documentation also lists spawning a child process with secrets populated, which is the mode a service or a script actually uses.

That last command is the one that shows what the library is for. A secret store integration is not interesting if a human has to paste a value; it is interesting when a Cloud Run service, a Cloud Build step or a local script gets its configuration mounted without the value ever appearing in a file or in an environment dump.

Audit logging, and the bill that comes with it

Cloud Audit logging on the bucket is optional, and the way it is described is a warning as much as a feature.

The note says that enabling it will enable audit logging on all Cloud KMS keys and all Cloud Storage buckets in the project, which may incur additional costs. That is a broader effect than the one bucket you are setting up, and a project with other KMS keys and other buckets will find them all logging after this.

The procedure is a three step IAM policy edit. You download the existing project policy, append the audit configurations for Cloud KMS and Cloud Storage, and submit the new policy:

gcloud projects get-iam-policy ${PROJECT_ID} > policy.yaml

cat <<EOF >> policy.yaml
auditConfigs:
- auditLogConfigs:
  - logType: DATA_READ
  - logType: ADMIN_READ
  - logType: DATA_WRITE
  service: cloudkms.googleapis.com
- auditLogConfigs:
  - logType: ADMIN_READ
  - logType: DATA_READ
  - logType: DATA_WRITE
  service: storage.googleapis.com
EOF

gcloud projects set-iam-policy ${PROJECT_ID} policy.yaml
rm policy.yaml

The final `rm` is in the documentation for a reason, since the downloaded policy file sits in your working directory and the recommendation is to remove it once the new policy is applied.

Four install channels, each with a caveat

Berglas can be installed four ways, and the README attaches a note to two of them.

A pre-compiled binary for your operating system from the latest releases, with no caveat. An official Docker container, run with `docker run -it us-docker.pkg.dev/berglas/berglas/berglas`, with the note that older container images are available on Container Registry and Artifact Registry but new versions are not published there. Homebrew on macOS, with `brew install berglas`, and the note that sometimes the formula can be several versions behind. And installation from source with a working Go installation, `go install github.com/GoogleCloudPlatform/berglas/v2@latest`.

Those caveats are worth taking seriously in a pipeline, because each describes a channel that goes stale in a different way. The Artifact Registry images are frozen at whatever the last published version was, so a tag that points at the old registry will not get new releases. The Homebrew formula lags by however long the maintainer of that formula takes. The Go install tracks the latest tag, and the Docker image tracks the latest release if you use the current registry path.

The Dockerfile itself is minimal, building on alpine with the CA certificates installed so that the container can actually talk to the Google APIs over TLS, and copying the compiled binary to `/bin/berglas` as the entrypoint.

Editorial conclusion

Adopt Berglas if your workloads run on Google Cloud and you want secrets resolved at process start from a KMS encrypted bucket, or you need the Cloud Storage backend that Secret Manager does not offer, since the tool's runtimes integration is its real strength. Do not adopt it if you only need one secret in one application, since Secret Manager plus the gcloud client covers that without another dependency, and do not treat it as a Google supported product, because the project states plainly that it is not one. Verify first that the project ID is the ID rather than the name or number, that the bucket you name does not already exist, since bootstrap expects to create it, and that turning on audit logging is acceptable, because it applies to every KMS key and bucket in the project and may add cost.

Frequently asked questions

Official sources

1. GoogleCloudPlatform/berglas on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases