Reference secrets in parameters

Preview

This product is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products are available "as is" and might have limited support. For more information, see the launch stage descriptions.

This page describes how to reference secrets in parameters. To learn more about secrets, see Secret Manager overview.

You can store sensitive information such as your passwords and API keys in Secret Manager and then reference those secrets from within parameters used in your applications or infrastructure. The maximum number of secret references a parameter version can contain is 15.

For example, you have a database connection string that includes a password. Do the following:

• Store the password as a secret in Secret Manager.
• Create a parameter in Parameter Manager for the connection string.
• Store a reference to the secret in your parameter version.

When your application or infrastructure needs the secret, it retrieves the parameter value, which contains the reference to the secret. Then, it uses that reference to fetch the actual secret value from Secret Manager. This way, the actual password is not exposed in your configuration files.

By storing secrets separately from configuration files and application code, you can reduce the risk of accidental exposure or unauthorized access. You can securely store, audit, and rotate your secrets in Secret Manager while keeping all your configuration data organized in Parameter Manager.

To reference secrets within parameters, you must do the following:

• Create a parameter version with the secret reference
• Grant the Secret Manager Secret Accessor role to the parameter

Note: Secret references can only be added to parameters that hold structured data, such as YAML or JSON.

Required roles

To get the permissions that you need to create a parameter version with a secret reference, ask your administrator to grant you the Parameter Manager Parameter Version Adder (roles/parametermanager.parameterversions.create) IAM role on the project, folder, or organization. For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Create a parameter version with the secret reference

If you are using the REST API to manage parameter versions, complete these steps before creating a new version:

• Encode the parameter payload data containing the secret reference using Base64 and then pass the encoded string in the create version command. For example, you want to create a new version of an existing parameter with a secret reference using the following YAML data:

  project:
    display_name: PM Bank
    locale: en-US
    port: 8080
    db_password: __REF__("//secretmanager.googleapis.com/projects/production-1/secrets/db_password/versions/1")
    mask_sensitive_fields: false
  

  The field db_password uses a special reference (__REF__()) to pull the actual password value from Secret Manager and the corresponding URL specifies the location of your database password within Secret Manager.

  Here's the Base64 string for the sample YAML data given in this section:

  cHJvamVjdDoNCiAgZGlzcGxheV9uYW1lOiBQTSBCYW5rDQogIGxvY2FsZTogZW4tVVMNCiAgcG9ydDogODA4MA0KICBkYl9wYXNzd29yZDogX19SRUZfXygiLy9zZWNyZXRtYW5hZ2VyLmdvb2dsZWFwaXMuY29tL3Byb2plY3RzL2FjbS1zYW1wbGUvc2VjcmV0cy9kYl9wYXNzd29yZC92ZXJzaW9ucy8xIikNCiAgbWFza19zZW5zaXRpdmVfZmllbGRzOiBmYWxzZQ==

Note: The parameter payload is encoded by default when you use it with the gcloud CLI command.

Use the following command to create the new version with the secret reference:

gcloud

Add version containing secret reference to a global parameter

Before using any of the command data below, make the following replacements:

• PARAMETER_VERSION_ID: the ID that you want to assign to the parameter version. Parameter version IDs must be 63 characters or less and consist only of alphanumeric characters (A-Z, a-z, 0-9), dashes (-), and underscores (_). IDs cannot begin with a dash.
• PARAMETER_ID: the name of the parameter.
• PARAMETER_PAYLOAD: the data, in plaintext, containing the secret references that you want to store within the parameter version.
• PROJECT_ID: the Google Cloud project ID.

Execute the following command:

Linux, macOS, or Cloud Shell

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud beta parametermanager parameters versions create PARAMETER_VERSION_ID --parameter=PARAMETER_ID --location=global --payload-data="PARAMETER_PAYLOAD" --project=PROJECT_ID

Windows (PowerShell)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud beta parametermanager parameters versions create PARAMETER_VERSION_ID --parameter=PARAMETER_ID --location=global --payload-data="PARAMETER_PAYLOAD" --project=PROJECT_ID

Windows (cmd.exe)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud beta parametermanager parameters versions create PARAMETER_VERSION_ID --parameter=PARAMETER_ID --location=global --payload-data="PARAMETER_PAYLOAD" --project=PROJECT_ID

You should receive a response similar to the following:

Created parameterVersion [refv1].

Add version containing secret reference to a regional parameter

Before using any of the command data below, make the following replacements:

• PARAMETER_VERSION_ID: the ID that you want to assign to the parameter version. Parameter version IDs must be 63 characters or less and consist only of alphanumeric characters (A-Z, a-z, 0-9), dashes (-), and underscores (_). IDs cannot begin with a dash.
• PARAMETER_ID: the name of the parameter.
• LOCATION: the Google Cloud location of the parameter.
• PARAMETER_PAYLOAD: the data, in plaintext, containing the secret references that you want to store within the parameter version.

Execute the following command:

Linux, macOS, or Cloud Shell

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud beta parametermanager parameters versions create PARAMETER_VERSION_ID --parameter=PARAMETER_ID --location=LOCATION --payload-data="PARAMETER_PAYLOAD" --project=PROJECT_ID

Windows (PowerShell)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud beta parametermanager parameters versions create PARAMETER_VERSION_ID --parameter=PARAMETER_ID --location=LOCATION --payload-data="PARAMETER_PAYLOAD" --project=PROJECT_ID

Windows (cmd.exe)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud beta parametermanager parameters versions create PARAMETER_VERSION_ID --parameter=PARAMETER_ID --location=LOCATION --payload-data="PARAMETER_PAYLOAD" --project=PROJECT_ID

You should receive a response similar to the following:

Created parameterVersion [refv2].

REST

Add version containing secret reference to a global parameter

Before using any of the request data, make the following replacements:

• PROJECT_ID: the Google Cloud project ID.
• PARAMETER_ID: the name of the parameter.
• PARAMETER_VERSION_ID: the ID that you want to assign to the parameter version. Parameter version IDs must be 63 characters or less and consist only of alphanumeric characters (A-Z, a-z, 0-9), dashes (-), and underscores (_). IDs cannot begin with a dash.
• PARAMETER_PAYLOAD: the data, as a Base64 encoded string, containing the secret references that you want to store within the parameter version.

HTTP method and URL:

POST https://parametermanager.googleapis.com/v1/projects/PROJECT_ID/locations/global/parameters/PARAMETER_ID/versions?parameter_version_id=PARAMETER_VERSION_ID

Request JSON body:

{"payload": {"data": "PARAMETER_PAYLOAD"}}

To send your request, choose one of these options:

curl

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://parametermanager.googleapis.com/v1/projects/PROJECT_ID/locations/global/parameters/PARAMETER_ID/versions?parameter_version_id=PARAMETER_VERSION_ID"

PowerShell

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://parametermanager.googleapis.com/v1/projects/PROJECT_ID/locations/global/parameters/PARAMETER_ID/versions?parameter_version_id=PARAMETER_VERSION_ID" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/production-1/locations/global/parameters/db_password_secret_ref/versions/refv1",
  "createTime": "2024-10-15T08:39:05.191747694Z",
  "updateTime": "2024-10-15T08:39:05.191747694Z"
}

Add version containing secret reference to a regional parameter

Before using any of the request data, make the following replacements:

• LOCATION: the Google Cloud location of the parameter.
• PROJECT_ID: the Google Cloud project ID.
• PARAMETER_ID: the name of the parameter.
• PARAMETER_VERSION_ID: the ID that you want to assign to the parameter version. Parameter version IDs must be 63 characters or less and consist only of alphanumeric characters (A-Z, a-z, 0-9), dashes (-), and underscores (_). IDs cannot begin with a dash.
• PARAMETER_PAYLOAD: the data, as a Base64 encoded string, containing the secret references that you want to store within the parameter version.

HTTP method and URL:

POST https://parametermanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/parameters/PARAMETER_ID/versions?parameter_version_id=PARAMETER_VERSION_ID

Request JSON body:

{"payload": {"data": "PARAMETER_PAYLOAD"}}

To send your request, choose one of these options:

curl

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://parametermanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/parameters/PARAMETER_ID/versions?parameter_version_id=PARAMETER_VERSION_ID"

PowerShell

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://parametermanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/parameters/PARAMETER_ID/versions?parameter_version_id=PARAMETER_VERSION_ID" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/production-1/locations/us-central1/parameters/db_password_secret_ref/versions/refv2",
  "createTime": "2024-10-15T08:39:05.191747694Z",
  "updateTime": "2024-10-15T08:39:05.191747694Z"
}

Grant the Secret Manager Secret Accessor role to the parameter

To let a parameter access a secret stored in Secret Manager, grant the Secret Manager Secret Accessor role (roles/secretmanager.secretAccessor) to the parameter. This gives the parameter permission to read the secret's value. Parameters are resources with built-in identities, which means that you must grant the IAM role using the resource's principal identifier. Refer to the following example to grant the role using the Google Cloud CLI:

gcloud

Before using any of the command data below, make the following replacements:

• PROJECT_ID: the ID of the project containing the secret
• SECRET_ID: the ID of the secret or fully qualified identifier for the secret
• PROJECT_NUMBER: the project number of the Google Cloud project where the parameter is stored
• PARAMETER_UID: the system-generated unique ID of the parameter

Execute the following command:

Linux, macOS, or Cloud Shell

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud secrets add-iam-policy-binding projects/PROJECT_ID/secrets/SECRET_ID --member="principal://parametermanager.googleapis.com/projects/PROJECT_NUMBER/uid/locations/global/parameters/PARAMETER_UID" --role="roles/secretmanager.secretAccessor"

Windows (PowerShell)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud secrets add-iam-policy-binding projects/PROJECT_ID/secrets/SECRET_ID --member="principal://parametermanager.googleapis.com/projects/PROJECT_NUMBER/uid/locations/global/parameters/PARAMETER_UID" --role="roles/secretmanager.secretAccessor"

Windows (cmd.exe)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud secrets add-iam-policy-binding projects/PROJECT_ID/secrets/SECRET_ID --member="principal://parametermanager.googleapis.com/projects/PROJECT_NUMBER/uid/locations/global/parameters/PARAMETER_UID" --role="roles/secretmanager.secretAccessor"

You should receive a response similar to the following:

Updated IAM policy for secret [db_password].
bindings:
- members:
  - principal://parametermanager.googleapis.com/projects/609765466568/uid/locations/global/parameters/3fe3492e-a0da-4447-8d6b-68b4594b7243
  role: roles/secretmanager.secretAccessor
etag: BwYkj3X1kGo=
version: 1

For information on rendering secret references when retrieving parameter payloads, see Render secrets referenced within a parameter version.

What's next

• List parameters
• View parameter details