Add 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.

This page describes how to add a parameter version. A parameter version stores the actual value of the parameter, whether it's a string, a number, or more complex data.

By creating parameter versions, you can do the following:

• Track changes to your parameter values over time.
• Rollback to previous values when required.
• Maintain an audit trail to see who made changes to the parameters and when.

Required roles

To get the permissions that you need to add a parameter version, ask your administrator to grant you the Parameter Manager Parameter Version Adder (roles/parametermanager.parameterVersionAdder) IAM role on the parameter. 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.

Add a parameter version

Parameter Manager lets you create multiple versions of a parameter. The version contains the actual data or value associated with the parameter. In the context of Parameter Manager, we'll call this data the parameter payload.

To add a new version, use the following command:

gcloud

Add a version 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, that you want to store within 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 create PARAMETER_VERSION_ID --parameter=PARAMETER_ID --location=global --payload-data="PARAMETER_PAYLOAD"

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"

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"

You should receive a response similar to the following:

Created parameterVersion [set1].

Add a version 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, that you want to store within 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 create PARAMETER_VERSION_ID --parameter=PARAMETER_ID --location=LOCATION --payload-data="PARAMETER_PAYLOAD"

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"

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"

You should receive a response similar to the following:

Created parameterVersion [set1].

REST

Add a version to a global parameter

Encode the raw parameter data to Base64 format.

 $ PARAMETER_PAYLOAD=$(echo "a: b" | base64 -w0)
 

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

• PROJECT_ID: the Google Cloud project ID.
• PARAMETER_ID: the name of 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.
• PPARAMETER_PAYLOAD: the Base64 encoded string corresponding to the data that you want to store within the parameter.

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/intrusion_detection_rules/versions/set1",
  "createTime": "2024-11-12T10:26:44.168165094Z",
  "updateTime": "2024-11-12T10:26:44.168165094Z",
  "payload": {
    "data": "QSBzdHJpbmcgYmxvYiBjYW4gYmUgc3RvcmVkIGluIHRoZSB1bmZvcm1hdHRlZCBwYXJhbWV0ZXIu"
  }
}

Add a version to a regional parameter

Encode the raw parameter data to Base64 format.

 $ PARAMETER_PAYLOAD=$(echo "a: b" | base64 -w0)
 

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 Base64 encoded string corresponding to the data that you want to store within the parameter.

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/intrusion_detection_rules/versions/set1",
  "createTime": "2024-10-30T05:27:51.206825427Z",
  "updateTime": "2024-10-30T05:27:51.206825427Z",
  "payload": {
    "data": "YTogYgo="
  }
}

You can also pass a payload file containing the parameter data directly in the create version command. Following is an example of uploading a payload file using the REST API:

Sample command

  echo "{\"payload\": { \"data\": \"$(cat PAYLOAD_FILE.yaml | base64 -w0)\"}}" | \
  curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d @- \
    "https://parametermanager.googleapis.com/v1/projects/PROJECT_ID/locations/global/parameters/PARAMETER_ID/versions?parameter_version_id=PARAMETER_VERSION_ID"

Replace the following:

• PAYLOAD_FILE: the payload file containing the parameter data
• PROJECT_ID: the Google Cloud project ID
• PARAMETER_ID: the name of the parameter
• PARAMETER_VERSION_ID: the ID of the parameter version

Sample response

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

What's next

• Reference secrets in parameters