Render secrets referenced within a parameter version

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.

Parameter versions can contain references to secrets created in Secret Manager. This reference doesn't reveal the actual secret value. When your application needs the secret, it retrieves the parameter. Instead of getting the plain-text secret, it gets the reference. The application then uses the reference to dynamically fetch the secret value from Secret Manager at runtime. This ensures that the secret is only accessed and exposed in memory when needed, reducing the risk of the secret being compromised.

This page describes how to retrieve a parameter version and then render the secret that the version references.

Required roles

To get the permissions that you need to render secret within a parameter version , ask your administrator to grant you the Parameter Manager Parameter Accessor (roles/parametermanager.parameterAccessor) IAM role on the parameter, 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.

Render the secret referenced within a parameter version

To render the secret referenced within a parameter version, use the following command:

gcloud

Render secrets referenced within global parameter versions

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

• PARAMETER_VERSION_ID: the ID of the parameter version
• PARAMETER_ID: the name of the parameter
• LOCATION: the Google Cloud location 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 beta parametermanager parameters versions render PARAMETER_VERSION_ID --parameter=PARAMETER_ID --location=global

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 render PARAMETER_VERSION_ID --parameter=PARAMETER_ID --location=global

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 render PARAMETER_VERSION_ID --parameter=PARAMETER_ID --location=global

You should receive a response similar to the following:

parameterVersion: projects/production-1/locations/global/parameters/db_password_secret_ref/versions/v4
payload:
  data: ZGJfcGFzc3dvcmQ6IF9fUkVGX18oLy9zZWNyZXRtYW5hZ2VyLmdvb2dsZWFwaXMuY29tL3Byb2plY3RzL3BtLWNlcC1wcm9kL3NlY3JldHMvZHVyYWJsZS1zZWNyZXQvdmVyc2lvbnMvMSk=
renderedPayload: ZGJfcGFzc3dvcmQ6IHRlc3Qtc2VjcmV0Cg==

Render secrets referenced within regional parameter versions

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

• PARAMETER_VERSION_ID: the ID of the parameter version
• PARAMETER_ID: the name of the parameter
• LOCATION: the Google Cloud location 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 beta parametermanager parameters versions render PARAMETER_VERSION_ID --parameter=PARAMETER_ID --location=LOCATION

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 render PARAMETER_VERSION_ID --parameter=PARAMETER_ID --location=LOCATION

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 render PARAMETER_VERSION_ID --parameter=PARAMETER_ID --location=LOCATION

You should receive a response similar to the following:

parameterVersion: projects/production-1/locations/us-central1/parameters/db_password_secret_ref/versions/v4
payload:
  data: ZGJfcGFzc3dvcmQ6IF9fUkVGX18oLy9zZWNyZXRtYW5hZ2VyLmdvb2dsZWFwaXMuY29tL3Byb2plY3RzL3BtLWNlcC1wcm9kL2xvY2F0aW9ucy91cy1jZW50cmFsMS9zZWNyZXRzL2R1cmFibGUtc2VjcmV0L3ZlcnNpb25zLzEpCg==
renderedPayload: ZGJfcGFzc3dvcmQ6IHRlc3Qtc2VjcmV0Cgo=

REST

Render secrets referenced within global parameter versions

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 of the parameter version

HTTP method and URL:

GET https://parametermanager.googleapis.com/v1/projects/PROJECT_ID/locations/global/parameters/PARAMETER_ID/versions/PARAMETER_VERSION_ID:render

Request JSON body:

{}

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 GET \
     -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:render"

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 GET `
    -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:render" | 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/v2",
    "createTime": "2024-10-15T08:39:05.191747694Z",
    "updateTime": "2024-10-15T08:39:05.530311092Z",
    "payload": {
      "data": "ZGJfcGFzc3dvcmQ6IF9fUkVGX18oLy9zZWNyZXRtYW5hZ2VyLmdvb2dsZWFwaXMuY29tL3Byb2plY3RzL3BtLWNlcC1wcm9kL3NlY3JldHMvZHVyYWJsZS1zZWNyZXQvdmVyc2lvbnMvMSkK"
    },
    "renderedPayload": "ZGJfcGFzc3dvcmQ6IHRlc3Qtc2VjcmV0Cgo="
}

Render secrets referenced within regional parameter versions

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 of the parameter version

HTTP method and URL:

GET https://parametermanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/parameters/PARAMETER_ID/versions/PARAMETER_VERSION_ID:render

Request JSON body:

{}

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 GET \
     -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:render"

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 GET `
    -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:render" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "parameterVersion": "pprojects/production-1/locations/us-central1/parameters/db_password_secret_ref/versions/v3",
  "payload": {
    "data": "ZGJfcGFzc3dvcmQ6IF9fUkVGX18oLy9zZWNyZXRtYW5hZ2VyLmdvb2dsZWFwaXMuY29tL3Byb2plY3RzL3BtLWNlcC1wcm9kL2xvY2F0aW9ucy91cy1jZW50cmFsMS9zZWNyZXRzL2R1cmFibGUtc2VjcmV0L3ZlcnNpb25zLzEpCg=="
  },
  "renderedPayload": "ZGJfcGFzc3dvcmQ6IHRlc3Qtc2VjcmV0Cgo="
}

This command returns the parameter version metadata as well as the following two values:

• payload: this field contains the raw, unprocessed parameter payload. This payload can have many key-value pairs, some of which might contain secrets. The data field within it holds a Base64-encoded string. If you decode this string, you'll find that the raw payload contains references (REF(...)) to locations where the secrets are stored. Note that each parameter version can contain up to 15 secret references.
• renderedPayload: this field contains the key-value pairs with actual secret values as a Base64-encoded string. Decode this string to fetch the parameter payload with rendered secret values.

Note: You can also use the render parameter version method to get version details for parameters that don't have secret references. In this scenario, the payload and renderedPayload fields contain the same value.

What's next

• Disable a parameter version
• Enable a disabled parameter version