Add a parameter version

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 one of the following methods:

Global parameters

Console

  1. In the Google Cloud console, go to the Secret Manager page.

    Go to Secret Manager

  2. Click Parameter Manager to go to the Parameter Manager page. You'll see the list of parameters for that project.

  3. Select the parameter for which you want to add the new version.

  4. Click the Actions menu associated with that parameter, and then click Add new version. The Create parameter version page appears.

  5. Enter the version name. Parameter version names must be 63 characters or less and consist only of alphanumeric characters (A-Z, a-z, 0-9), dashes (-), and underscores (_). Names cannot begin with a dash.

  6. In the Payload section, enter a value for the parameter. Alternatively, you can upload a file containing the parameter value, and then edit the values in the payload editor. The parameter value must be in the format specified for the parameter.

  7. Click Create.

gcloud

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

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

Windows (PowerShell)

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

Windows (cmd.exe)

gcloud 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].

REST

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

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

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"
  }
}

C#

To run this code, first set up a C# development environment and install the Secret Manager C# SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.


using Google.Cloud.ParameterManager.V1;
using Google.Protobuf;
using System.Text;

public class CreateParameterVersionSample
{
    /// <summary>
    /// This function creates a parameter version with an unformatted payload using the Parameter Manager SDK for GCP.
    /// </summary>
    /// <param name="projectId">The ID of the project where the parameter is located.</param>
    /// <param name="parameterId">The ID of the parameter for which the version is to be created.</param>
    /// <param name="versionId">The ID of the version to be created.</param>
    /// <returns>The created ParameterVersion object.</returns>
    public ParameterVersion CreateParameterVersion(
        string projectId,
        string parameterId,
        string versionId)
    {
        // Create the client.
        ParameterManagerClient client = ParameterManagerClient.Create();

        // Build the parent resource name.
        ParameterName parent = new ParameterName(projectId, "global", parameterId);

        // Convert the payload to bytes.
        string payload = "test123";
        ByteString data = ByteString.CopyFrom(payload, Encoding.UTF8);

        // Build the parameter version with the unformatted payload.
        ParameterVersion parameterVersion = new ParameterVersion
        {
            Payload = new ParameterVersionPayload
            {
                Data = data
            }
        };

        // Call the API to create the parameter version.
        ParameterVersion createdParameterVersion = client.CreateParameterVersion(parent, parameterVersion, versionId);

        // Print the created parameter version name.
        Console.WriteLine($"Created parameter version: {createdParameterVersion.Name}");

        // Return the created parameter version.
        return createdParameterVersion;
    }
}

Go

To run this code, first set up a Go development environment and install the Secret Manager Go SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.

import (
	"context"
	"fmt"
	"io"

	parametermanager "cloud.google.com/go/parametermanager/apiv1"
	parametermanagerpb "cloud.google.com/go/parametermanager/apiv1/parametermanagerpb"
)

// createParamVersion creates a new version of a parameter with an unformatted payload in Parameter Manager.
//
// w: The io.Writer object used to write the output.
// projectID: The ID of the project where the parameter is located.
// parameterID: The ID of the parameter for which the version is to be created.
// versionID: The ID of the version to be created.
// payload: The unformatted string payload to be stored in the new parameter version.
//
// The function returns an error if the parameter version creation fails.
func createParamVersion(w io.Writer, projectID, parameterID, versionID, payload string) error {
	// Create a context and a Parameter Manager client.
	ctx := context.Background()
	client, err := parametermanager.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("failed to create Parameter Manager client: %w", err)
	}
	defer client.Close()

	// Construct the name of the create parameter version.
	parent := fmt.Sprintf("projects/%s/locations/global/parameters/%s", projectID, parameterID)

	// Build the request to create a new parameter version with the unformatted payload.
	req := &parametermanagerpb.CreateParameterVersionRequest{
		Parent:             parent,
		ParameterVersionId: versionID,
		ParameterVersion: &parametermanagerpb.ParameterVersion{
			Payload: &parametermanagerpb.ParameterVersionPayload{
				Data: []byte(payload), // Set the unformatted payload data.
			},
		},
	}

	// Call the API to create the parameter version.
	version, err := client.CreateParameterVersion(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to create parameter version: %w", err)
	}

	fmt.Fprintf(w, "Created parameter version: %s\n", version.Name)
	return nil
}

Java

To run this code, first set up a Java development environment and install the Secret Manager Java SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.


import com.google.cloud.parametermanager.v1.ParameterManagerClient;
import com.google.cloud.parametermanager.v1.ParameterName;
import com.google.cloud.parametermanager.v1.ParameterVersion;
import com.google.cloud.parametermanager.v1.ParameterVersionPayload;
import com.google.protobuf.ByteString;
import java.io.IOException;

/**
 * This class demonstrates how to create a parameter version with an unformatted payload using the
 * Parameter Manager SDK for GCP.
 */
public class CreateParamVersion {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String parameterId = "your-parameter-id";
    String versionId = "your-version-id";
    String payload = "test123";

    // Call the method to create a parameter version with unformatted payload.
    createParamVersion(projectId, parameterId, versionId, payload);
  }

  // This is an example snippet that creates a parameter version with an unformatted payload.
  public static ParameterVersion createParamVersion(
      String projectId, String parameterId, String versionId, String payload) throws IOException {
    // Initialize the client that will be used to send requests. This client only
    // needs to be created once, and can be reused for multiple requests.
    try (ParameterManagerClient client = ParameterManagerClient.create()) {
      String locationId = "global";

      // Build the parameter name.
      ParameterName parameterName = ParameterName.of(projectId, locationId, parameterId);

      // Convert the payload string to ByteString.
      ByteString byteStringPayload = ByteString.copyFromUtf8(payload);

      // Create the parameter version payload.
      ParameterVersionPayload parameterVersionPayload =
          ParameterVersionPayload.newBuilder().setData(byteStringPayload).build();

      // Create the parameter version with the unformatted payload.
      ParameterVersion parameterVersion =
          ParameterVersion.newBuilder().setPayload(parameterVersionPayload).build();

      // Create the parameter version in the Parameter Manager.
      ParameterVersion createdParameterVersion =
          client.createParameterVersion(parameterName.toString(), parameterVersion, versionId);
      System.out.printf("Created parameter version: %s\n", createdParameterVersion.getName());

      return createdParameterVersion;
    }
  }
}

Node.js

To run this code, first set up a Node.js development environment and install the Secret Manager Node.js SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const projectId = 'YOUR_PROJECT_ID';
// const parameterId = 'YOUR_PARAMETER_ID';
// const parameterVersionId = 'YOUR_PARAMETER_VERSION_ID';
// const payload = 'This is unstructured data';

// Imports the Parameter Manager library
const {ParameterManagerClient} = require('@google-cloud/parametermanager');

// Instantiates a client
const client = new ParameterManagerClient();

async function createParamVersion() {
  // Construct the parent resource name
  const parent = client.parameterPath(projectId, 'global', parameterId);

  // Construct the parameter version
  const parameterVersion = {
    payload: {
      data: Buffer.from(payload, 'utf8'),
    },
  };

  // Construct the request
  const request = {
    parent: parent,
    parameterVersionId: parameterVersionId,
    parameterVersion: parameterVersion,
  };

  // Create the parameter version
  const [paramVersion] = await client.createParameterVersion(request);
  console.log(`Created parameter version: ${paramVersion.name}`);
  return paramVersion;
}

return await createParamVersion();

PHP

To run this code, first learn about using PHP on Google Cloud and install the Secret Manager PHP SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.

// Import necessary classes for creating a parameter version.
use Google\Cloud\ParameterManager\V1\Client\ParameterManagerClient;
use Google\Cloud\ParameterManager\V1\CreateParameterVersionRequest;
use Google\Cloud\ParameterManager\V1\ParameterVersion;
use Google\Cloud\ParameterManager\V1\ParameterVersionPayload;

/**
 * Creates a parameter version with an unformatted payload.
 *
 * @param string $projectId The Google Cloud Project ID (e.g. 'my-project')
 * @param string $parameterId The Parameter ID (e.g. 'my-param')
 * @param string $versionId The Version ID (e.g. 'my-param-version')
 * @param string $payload The unformatted string payload (e.g. 'test123')
 */
function create_param_version(string $projectId, string $parameterId, string $versionId, string $payload): void
{
    // Create a client for the Parameter Manager service.
    $client = new ParameterManagerClient();

    // Build the resource name of the parent object.
    $parent = $client->parameterName($projectId, 'global', $parameterId);

    // Create a new ParameterVersionPayload object and set the unformatted data.
    $parameterVersionPayload = new ParameterVersionPayload();
    $parameterVersionPayload->setData($payload);

    // Create a new ParameterVersion object and set the payload.
    $parameterVersion = new ParameterVersion();
    $parameterVersion->setPayload($parameterVersionPayload);

    // Prepare the request with the parent and parameter version object.
    $request = (new CreateParameterVersionRequest())
        ->setParent($parent)
        ->setParameterVersionId($versionId)
        ->setParameterVersion($parameterVersion);

    // Call the API to create the parameter version.
    $newParameterVersion = $client->createParameterVersion($request);
    printf('Created parameter version: %s' . PHP_EOL, $newParameterVersion->getName());
}

Python

To run this code, first set up a Python development environment and install the Secret Manager Python SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.

def create_param_version(
    project_id: str, parameter_id: str, version_id: str, payload: str
) -> parametermanager_v1.ParameterVersion:
    """
    Creates a new version of an existing parameter in the global location
    of the specified project using the Google Cloud Parameter Manager SDK.
    The payload is specified as an unformatted string.

    Args:
        project_id (str): The ID of the project where the parameter is located.
        parameter_id (str): The ID of the parameter for which
        the version is to be created.
        version_id (str): The ID of the version to be created.
        payload (str): The unformatted string payload
        to be stored in the new parameter version.

    Returns:
        parametermanager_v1.ParameterVersion: An object representing the
        newly created parameter version.

    Example:
        create_param_version(
            "my-project",
            "my-global-parameter",
            "v1",
            "my-unformatted-payload"
        )
    """
    # Import the necessary library for Google Cloud Parameter Manager.
    from google.cloud import parametermanager_v1

    # Create the Parameter Manager client.
    client = parametermanager_v1.ParameterManagerClient()

    # Build the resource name of the parameter.
    parent = client.parameter_path(project_id, "global", parameter_id)

    # Define the parameter version creation request with an unformatted payload.
    request = parametermanager_v1.CreateParameterVersionRequest(
        parent=parent,
        parameter_version_id=version_id,
        parameter_version=parametermanager_v1.ParameterVersion(
            payload=parametermanager_v1.ParameterVersionPayload(
                data=payload.encode("utf-8")  # Encoding the payload to bytes.
            )
        ),
    )

    # Create the parameter version.
    response = client.create_parameter_version(request=request)

    # Print the newly created parameter version name.
    print(f"Created parameter version: {response.name}")

Ruby

To run this code, first set up a Ruby development environment and install the Secret Manager Ruby SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.

require "google/cloud/parameter_manager"

##
# Create a parameter version
#
# @param project_id [String] The Google Cloud project (e.g. "my-project")
# @param parameter_id [String] The parameter name (e.g. "my-parameter")
# @param version_id [String] The version name (e.g. "my-version")
# @param payload [String] The parameter payload (e.g. "test123")
#
def create_param_version project_id:, parameter_id:, version_id:, payload:
  # Create a Parameter Manager client.
  client = Google::Cloud::ParameterManager.parameter_manager

  # Build the resource name of the parent project.
  parent = client.parameter_path project: project_id, location: "global", parameter: parameter_id

  parameter_version = {
    payload: {
      data: payload
    }
  }

  # Create the parameter version.
  param_version = client.create_parameter_version parent: parent, parameter_version_id: version_id,
                                                  parameter_version: parameter_version

  # Print the new parameter version name.
  puts "Created parameter version #{param_version.name}"
end

Regional parameters

Console

  1. In the Google Cloud console, go to the Secret Manager page.

    Go to Secret Manager

  2. Click Parameter Manager to go to the Parameter Manager page. You'll see the list of parameters for that project.

  3. Select the parameter for which you want to add the new version.

  4. Click the Actions menu associated with that parameter, and then click Add new version. The Create parameter version page appears.

  5. Enter the version name. Parameter version names must be 63 characters or less and consist only of alphanumeric characters (A-Z, a-z, 0-9), dashes (-), and underscores (_). Names cannot begin with a dash.

  6. In the Payload section, enter a value for the parameter. Alternatively, you can upload a file containing the parameter value, and then edit the values in the payload editor. The parameter value must be in the format specified for the parameter.

  7. Click Create.

gcloud

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

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

Windows (PowerShell)

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

Windows (cmd.exe)

gcloud 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

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

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

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="
  }
}

C#

To run this code, first set up a C# development environment and install the Secret Manager C# SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.


using Google.Cloud.ParameterManager.V1;
using Google.Protobuf;
using System.Text;


public class CreateRegionalParameterVersionSample
{
    /// <summary>
    /// This function creates a regional parameter version with an unformatted payload using the Parameter Manager SDK for GCP.
    /// </summary>
    /// <param name="projectId">The ID of the project where the parameter is located.</param>
    /// <param name="locationId">The ID of the region where the parameter is located.</param>
    /// <param name="parameterId">The ID of the parameter for which the version is to be created.</param>
    /// <param name="versionId">The ID of the version to be created.</param>
    /// <returns>The created ParameterVersion object.</returns>
    public ParameterVersion CreateRegionalParameterVersion(
        string projectId,
        string locationId,
        string parameterId,
        string versionId)
    {
        // Define the regional endpoint
        string regionalEndpoint = $"parametermanager.{locationId}.rep.googleapis.com";

        // Create the client with the regional endpoint
        ParameterManagerClient client = new ParameterManagerClientBuilder
        {
            Endpoint = regionalEndpoint
        }.Build();

        // Build the parent resource name using ParameterName
        ParameterName parent = new ParameterName(projectId, locationId, parameterId);

        // Convert the payload to bytes
        string payload = "test123";
        ByteString data = ByteString.CopyFrom(payload, Encoding.UTF8);

        // Build the parameter version with the unformatted payload
        ParameterVersion parameterVersion = new ParameterVersion
        {
            Payload = new ParameterVersionPayload
            {
                Data = data
            }
        };

        // Call the API to create the parameter version
        ParameterVersion createdParameterVersion = client.CreateParameterVersion(parent, parameterVersion, versionId);

        // Print the created parameter version name
        Console.WriteLine($"Created regional parameter version: {createdParameterVersion.Name}");

        // Return the created parameter version
        return createdParameterVersion;
    }
}

Go

To run this code, first set up a Go development environment and install the Secret Manager Go SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.

import (
	"context"
	"fmt"
	"io"

	parametermanager "cloud.google.com/go/parametermanager/apiv1"
	parametermanagerpb "cloud.google.com/go/parametermanager/apiv1/parametermanagerpb"
	"google.golang.org/api/option"
)

// createRegionalParamVersion creates a new version of a regional parameter with an unformatted payload in Parameter Manager.
//
// w: The io.Writer object used to write the output.
// projectID: The ID of the project where the parameter is located.
// locationID: The ID of the region where the parameter is located.
// parameterID: The ID of the parameter for which the version is to be created.
// versionID: The ID of the version to be created.
// payload: The unformatted string payload to be stored in the new parameter version.
//
// The function returns an error if the parameter version creation fails.
func createRegionalParamVersion(w io.Writer, projectID, locationID, parameterID, versionID, payload string) error {
	// Create a context.
	ctx := context.Background()

	// Create a Parameter Manager client.
	endpoint := fmt.Sprintf("parametermanager.%s.rep.googleapis.com:443", locationID)
	client, err := parametermanager.NewClient(ctx, option.WithEndpoint(endpoint))
	if err != nil {
		return fmt.Errorf("failed to create parametermanager client: %w", err)
	}
	defer client.Close()

	// Construct the name of the create parameter version.
	parent := fmt.Sprintf("projects/%s/locations/%s/parameters/%s", projectID, locationID, parameterID)

	// Create a parameter version.
	req := &parametermanagerpb.CreateParameterVersionRequest{
		Parent:             parent,
		ParameterVersionId: versionID,
		ParameterVersion: &parametermanagerpb.ParameterVersion{
			Payload: &parametermanagerpb.ParameterVersionPayload{
				Data: []byte(payload),
			},
		},
	}
	version, err := client.CreateParameterVersion(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to create parameter version: %w", err)
	}
	fmt.Fprintf(w, "Created regional parameter version: %s\n", version.Name)
	return nil
}

Java

To run this code, first set up a Java development environment and install the Secret Manager Java SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.


import com.google.cloud.parametermanager.v1.ParameterManagerClient;
import com.google.cloud.parametermanager.v1.ParameterManagerSettings;
import com.google.cloud.parametermanager.v1.ParameterName;
import com.google.cloud.parametermanager.v1.ParameterVersion;
import com.google.cloud.parametermanager.v1.ParameterVersionPayload;
import com.google.protobuf.ByteString;
import java.io.IOException;

/**
 * This class demonstrates how to create a regional parameter version with an unformatted payload
 * using the Parameter Manager SDK for GCP.
 */
public class CreateRegionalParamVersion {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String locationId = "your-location-id";
    String parameterId = "your-parameter-id";
    String versionId = "your-version-id";
    String payload = "test123";

    // Call the method to create a regional parameter version with unformatted payload.
    createRegionalParamVersion(projectId, locationId, parameterId, versionId, payload);
  }

  // This is an example snippet that creates a regional parameter version with an unformatted
  // payload.
  public static ParameterVersion createRegionalParamVersion(
      String projectId, String locationId, String parameterId, String versionId, String payload)
      throws IOException {
    // Endpoint to call the regional parameter manager server
    String apiEndpoint = String.format("parametermanager.%s.rep.googleapis.com:443", locationId);
    ParameterManagerSettings parameterManagerSettings =
        ParameterManagerSettings.newBuilder().setEndpoint(apiEndpoint).build();

    // Initialize the client that will be used to send requests. This client only
    // needs to be created once, and can be reused for multiple requests.
    try (ParameterManagerClient client = ParameterManagerClient.create(parameterManagerSettings)) {
      // Build the parameter name.
      ParameterName parameterName = ParameterName.of(projectId, locationId, parameterId);

      // Convert the payload string to ByteString.
      ByteString byteStringPayload = ByteString.copyFromUtf8(payload);

      // Create the parameter version payload.
      ParameterVersionPayload parameterVersionPayload =
          ParameterVersionPayload.newBuilder().setData(byteStringPayload).build();

      // Create the parameter version with the unformatted payload.
      ParameterVersion parameterVersion =
          ParameterVersion.newBuilder().setPayload(parameterVersionPayload).build();

      // Create the parameter version in the Parameter Manager.
      ParameterVersion createdParameterVersion =
          client.createParameterVersion(parameterName.toString(), parameterVersion, versionId);
      System.out.printf(
          "Created regional parameter version: %s\n", createdParameterVersion.getName());

      return createdParameterVersion;
    }
  }
}

Node.js

To run this code, first set up a Node.js development environment and install the Secret Manager Node.js SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const projectId = 'YOUR_PROJECT_ID';
// const locationId = 'us-central1';
// const parameterId = 'YOUR_PARAMETER_ID';
// const parameterVersionId = 'YOUR_PARAMETER_VERSION_ID';
// const payload = 'This is unstructured data';

// Imports the Parameter Manager library
const {ParameterManagerClient} = require('@google-cloud/parametermanager');

// Adding the endpoint to call the regional parameter manager server
const options = {
  apiEndpoint: `parametermanager.${locationId}.rep.googleapis.com`,
};

// Instantiates a client with regional endpoint
const client = new ParameterManagerClient(options);

async function createRegionalParamVersion() {
  // Construct the parent resource name
  const parent = client.parameterPath(projectId, locationId, parameterId);

  // Construct the parameter version
  const parameterVersion = {
    payload: {
      data: Buffer.from(payload, 'utf8'),
    },
  };

  // Construct the request
  const request = {
    parent: parent,
    parameterVersionId: parameterVersionId,
    parameterVersion: parameterVersion,
  };

  // Create the parameter version
  const [paramVersion] = await client.createParameterVersion(request);
  console.log(`Created regional parameter version: ${paramVersion.name}`);
  return paramVersion;
}

return await createRegionalParamVersion();

PHP

To run this code, first learn about using PHP on Google Cloud and install the Secret Manager PHP SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.

// Import necessary classes for creating a parameter version.
use Google\Cloud\ParameterManager\V1\Client\ParameterManagerClient;
use Google\Cloud\ParameterManager\V1\CreateParameterVersionRequest;
use Google\Cloud\ParameterManager\V1\ParameterVersion;
use Google\Cloud\ParameterManager\V1\ParameterVersionPayload;

/**
 * Creates a regional parameter version with an unformatted payload.
 *
 * @param string $projectId The Google Cloud Project ID (e.g. 'my-project')
 * @param string $locationId The Parameter Location (e.g. 'us-central1')
 * @param string $parameterId The Parameter ID (e.g. 'my-param')
 * @param string $versionId The Version ID (e.g. 'my-param-version')
 * @param string $payload The unformatted string payload (e.g. 'test123')
 */
function create_regional_param_version(string $projectId, string $locationId, string $parameterId, string $versionId, string $payload): void
{
    // Specify regional endpoint.
    $options = ['apiEndpoint' => "parametermanager.$locationId.rep.googleapis.com"];

    // Create a client for the Parameter Manager service.
    $client = new ParameterManagerClient($options);

    // Build the resource name of the parent object.
    $parent = $client->parameterName($projectId, $locationId, $parameterId);

    // Create a new ParameterVersionPayload object and set the unformatted data.
    $parameterVersionPayload = new ParameterVersionPayload();
    $parameterVersionPayload->setData($payload);

    // Create a new ParameterVersion object and set the payload.
    $parameterVersion = new ParameterVersion();
    $parameterVersion->setPayload($parameterVersionPayload);

    // Prepare the request with the parent and parameter version object.
    $request = (new CreateParameterVersionRequest())
        ->setParent($parent)
        ->setParameterVersionId($versionId)
        ->setParameterVersion($parameterVersion);

    // Call the API to create the parameter version.
    $newParameterVersion = $client->createParameterVersion($request);
    printf('Created regional parameter version: %s' . PHP_EOL, $newParameterVersion->getName());
}

Python

To run this code, first set up a Python development environment and install the Secret Manager Python SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.

def create_regional_param_version(
    project_id: str, location_id: str, parameter_id: str, version_id: str, payload: str
) -> parametermanager_v1.ParameterVersion:
    """
    Creates a new version of an existing parameter in the specified region
    of the specified project using the Google Cloud Parameter Manager SDK.
    The payload is specified as an unformatted string.

    Args:
        project_id (str): The ID of the project where the parameter is located.
        location_id (str): The ID of the region where the parameter is located.
        parameter_id (str): The ID of the parameter for which
        the version is to be created.
        version_id (str): The ID of the version to be created.
        payload (str): The unformatted string payload
        to be stored in the new parameter version.

    Returns:
        parametermanager_v1.ParameterVersion: An object representing the
        newly created parameter version.

    Example:
        create_regional_param_version(
            "my-project",
            "us-central1",
            "my-regional-parameter",
            "v1",
            "my-unformatted-payload"
        )
    """
    # Import the necessary library for Google Cloud Parameter Manager.
    from google.cloud import parametermanager_v1

    # Create the Parameter Manager client with the regional endpoint.
    api_endpoint = f"parametermanager.{location_id}.rep.googleapis.com"
    client = parametermanager_v1.ParameterManagerClient(
        client_options={"api_endpoint": api_endpoint}
    )

    # Build the resource name of the parameter.
    parent = client.parameter_path(project_id, location_id, parameter_id)

    # Define the parameter version creation request with an unformatted payload.
    request = parametermanager_v1.CreateParameterVersionRequest(
        parent=parent,
        parameter_version_id=version_id,
        parameter_version=parametermanager_v1.ParameterVersion(
            payload=parametermanager_v1.ParameterVersionPayload(
                data=payload.encode("utf-8")  # Encoding the payload to bytes.
            )
        ),
    )

    # Create the parameter version.
    response = client.create_parameter_version(request=request)

    # Print the newly created parameter version name.
    print(f"Created regional parameter version: {response.name}")

Ruby

To run this code, first set up a Ruby development environment and install the Secret Manager Ruby SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.

require "google/cloud/parameter_manager"

##
# Create a regional parameter version
#
# @param project_id [String] The Google Cloud project (e.g. "my-project")
# @param location_id [String] The location name (e.g. "us-central1")
# @param parameter_id [String] The parameter name (e.g. "my-parameter")
# @param version_id [String] The version name (e.g. "my-version")
# @param payload [String] The parameter payload (e.g. "test123")
#
def create_regional_param_version project_id:, location_id:, parameter_id:, version_id:, payload:
  # Endpoint for the regional parameter manager service.
  api_endpoint = "parametermanager.#{location_id}.rep.googleapis.com"

  # Create the Parameter Manager client.
  client = Google::Cloud::ParameterManager.parameter_manager do |config|
    config.endpoint = api_endpoint
  end

  # Build the resource name of the parent project.
  parent = client.parameter_path project: project_id, location: location_id, parameter: parameter_id

  parameter_version = {
    payload: {
      data: payload
    }
  }

  # Create the parameter version.
  param_version = client.create_parameter_version parent: parent, parameter_version_id: version_id,
                                                  parameter_version: parameter_version

  # Print the new parameter version name.
  puts "Created regional parameter version #{param_version.name}"
end

If you're using the gcloud CLI or the REST API, you can 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. Don't use latest (uppercase or lowercase) when naming your parameter version resources, because it's a reserved keyword. Reserved keywords have special meanings within the API and can't be used for other purposes.

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