Google Secret Manager Plugin

Our Google Cloud Secret Manager plugin enables secure loading of secrets from GCP Secret Manager using declarative instructions within your .env files.

It supports authentication via Application Default Credentials (ADC) or explicitly passing in a service account JSON key.

In a JS/TS project, you may install the @varlock/google-secret-manager-plugin package as a normal dependency. Otherwise you can just load it directly from your .env.schema file, as long as you add a version specifier. See the plugins guide for more instructions on installing plugins.

# 1. Load the plugin
# @plugin(@varlock/google-secret-manager-plugin)
#
# 2. Initialize the plugin - see below for more details on options
# @initGsm(projectId=my-gcp-project)
# ---

By default (when no credentials parameter is set), this plugin will use Application Default Credentials (ADC) to authenticate with Google Cloud. This is the recommended way to authenticate for local dev, and within GCP.

Within GCP, you will need to set up a service account with the correct permissions, and attach it to the resources where your code will be running.

Outside of GCP, you may set up ADC credentials using the gcloud auth application-default login command, which will store credentials locally, and make them available for ADC.

In rare cases, it may be useful to pass in a service account key explicitly. This is useful for deployed environments other than GCP, or if you need to use a different service account than the one attached to your service.

1. Create and download a JSON key for your service account. This can be done via the Cloud Console or using the gcloud CLI. docs

   gcloud iam service-accounts keys create key.json \
     --iam-account=SERVICE_ACCOUNT_EMAIL

2. Wire up the service account key in your config. Add a config item of type gcpServiceAccountJson to hold the key value, and reference it when initializing the plugin.

   # @plugin(@varlock/google-secret-manager-plugin)
   # @initGsm(projectId=my-gcp-project, credentials=$GCP_SA_KEY)
   # ---
   # @type=gcpServiceAccountJson @sensitive
   GCP_SA_KEY=

3. Set your service account key in deployed environments. Copy the JSON key content from the file you downloaded, and set it in deployed environments using your platform’s env var management UI. Be sure to use the same name as you defined in your schema (e.g. GCP_SA_KEY).

If you are already using GCP Secret Manager, you likely have completed these steps already, but if not, you will need to do so before using this plugin:

1. Enable the Secret Manager API (if not already done)

   Go to the Google Cloud Console and enable the Secret Manager API for your project.

2. Create a new service account in your GCP project. This can be done via the Google Cloud Console or using the gcloud CLI. docs

   This service account, whether accessed using ADC or a service account key, will now serve as your secret-zero - which grants access to the rest of your sensitive data stored in Secret Manager.

3. Grant the service account permissions to access secrets. The service account needs the Secret Manager Secret Accessor role (roles/secretmanager.secretAccessor) on the secrets or project level. docs

   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
     --role="roles/secretmanager.secretAccessor"

4. Attach the service account to GCP resources

   You must attach this service account to any resources where your code will be running.

Once the plugin is installed and initialized, you can start adding config items that load values from Google Secret Manager using the new gsm() resolver function.

You can reference secrets using either a short format or a full resource path:

Short format (requires projectId to be set):

# Latest version
API_KEY=gsm("api-key")

# Specific version
DB_PASSWORD=gsm("database-password@5")

Full resource path:

# Full path format (projectId not required)
API_KEY=gsm("projects/my-project/secrets/api-key/versions/latest")
DB_PASSWORD=gsm("projects/my-project/secrets/database-password/versions/5")

If you have multiple plugin instances (e.g., for different projects or environments), the gsm() function accepts an optional first parameter to specify which instance id to use.

# @initGsm(id=dev, projectId=my-dev-project)
# @initGsm(id=prod, projectId=my-prod-project, credentials=$GCP_SA_KEY_PROD)
# ---
# @type=gcpServiceAccountJson @sensitive
GCP_SA_KEY_PROD=
DEV_SECRET=gsm(dev, "dev-secret")
PROD_SECRET=gsm(prod, "prod-secret")

The projectId parameter supports dynamic resolution, allowing you to specify project IDs from environment variables or other resolver functions. This is useful when you need to use different project IDs based on your deployment environment.

# @plugin(@varlock/google-secret-manager-plugin)
# @initGsm(projectId=$GCP_PROJECT_ID)
# ---
# Use environment variable for project ID
GCP_PROJECT_ID=
API_KEY=gsm("api-key")

You can also use resolver functions to construct the project ID dynamically:

# @plugin(@varlock/google-secret-manager-plugin)
# @initGsm(projectId=concat($APP_ENV, "-project"))
# ---
APP_ENV=
API_KEY=gsm("api-key")

# @initGsm(id=prod, projectId=my-gcp-project, credentials=$GCP_SA_KEY)
# ---
# @type=gcpServiceAccountJson @sensitive
GCP_SA_KEY=

# @type=gcpServiceAccountJson
GCP_SA_KEY=

# Short format (requires projectId in @initGsm)
API_KEY=gsm("api-key")
DB_PASSWORD=gsm("database-password@5")

# Full path format
API_KEY=gsm("projects/my-project/secrets/api-key/versions/latest")

# Example using a plugin instance id
PROD_SECRET=gsm(prod, "prod-secret")