Berglas Custom Setup

January 2, 2026 · View on GitHub

This document describes the steps required to create a Berglas Cloud Storage bucket and Cloud KMS keys manually. This is an advanced user topic and is not required to use Berglas. Users should use the berglas bootstrap command where possible!

Install the [Cloud SDK][cloud-sdk]. More detailed instructions are available in the main README.
Export your project ID as an environment variable. The rest of this setup guide assumes this environment variable is set:
```
export PROJECT_ID=my-gcp-project-id
```
Please note, this is the project ID, not the project name or project number. You can find the project ID by running gcloud projects list or in the web UI.

Enable required services on the project:

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

Create a [Cloud KMS][cloud-kms] keyring and crypto key for encrypting secrets:

gcloud kms keyrings create my-keyring \
  --project ${PROJECT_ID} \
  --location global

gcloud kms keys create my-key \
  --project ${PROJECT_ID} \
  --location global \
  --keyring my-keyring \
  --purpose encryption

You can choose alternate locations and names, but the purpose must remain as "encryption".

Create a [Cloud Storage][cloud-storage] bucket for storing secrets:
```
export BUCKET_ID=my-secrets
```
Replace my-secrets with the name of your bucket. Bucket names must be globally unique across all of Google Cloud. You can also create a bucket using the Google Cloud Console from the web.
```
gcloud storage buckets create gs://${BUCKET_ID} --project ${PROJECT_ID}
```
It is strongly recommended that you create a new bucket instead of using an existing one. Berglas should be the only entity managing IAM permissions on the bucket.
Set the default ACL permissions on the bucket to private:
```
gcloud storage buckets update gs://${BUCKET_ID} --predefined-default-object-acl=private
```
```
gcloud storage buckets update gs://${BUCKET_ID} --predefined-acl=private
```
The default permissions grant anyone with Owner/Editor access on the project access to the bucket and its objects. These commands restrict access to the bucket to project owners and access to bucket objects to only their owner. Everyone else must be granted explicit access via IAM to an object inside the bucket.