List parameter versions

This page describes how to retrieve a list of all the parameter versions associated with a parameter within a specified Google Cloud project and location.

Versions represent the specific setting or configuration value that the parameter holds at a given point in time. By looking at the list of versions, you can see how a parameter has changed over time and who made the change. This helps with auditing and troubleshooting. For example, if you're experiencing issues with your current configuration, examining disabled versions can help you understand what settings were previously used and potentially identify if a recent change caused the problem.

Required roles

To get the permissions that you need to list parameter versions, ask your administrator to grant you the Parameter Manager Parameter Viewer (roles/parametermanager.parameterViewer) 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.

List all parameters versions

To list all the parameter versions associated with a parameter, 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. Click the parameter name to view its versions.

    The parameter details page opens with the Versions tab in focus where you can see all the versions of the selected parameter.

gcloud

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

  • PARAMETER_ID: the name of the parameter

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud parametermanager parameters versions list --parameter=PARAMETER_ID --location=global

Windows (PowerShell)

gcloud parametermanager parameters versions list --parameter=PARAMETER_ID --location=global

Windows (cmd.exe)

gcloud parametermanager parameters versions list --parameter=PARAMETER_ID --location=global

You should receive a response similar to the following:

NAME                                                                                DISABLED  CREATE_TIME                     UPDATE_TIME
projects/production-1/locations/global/parameters/app_config/versions/configv3            2024-11-14T10:07:12.883361876Z  2024-11-14T10:07:13.331806596Z

REST

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

HTTP method and URL: 

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

Request JSON body: 

{}

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

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 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" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "parameterVersions": [
    {
      "name": "projects/production-1/locations/global/parameters/app_config/versions/configv3",
      "createTime": "2024-11-12T10:22:17.704800878Z",
      "updateTime": "2024-11-12T11:08:24.173199506Z",
      "disabled": true
    },
    {
      "name": "projects/production-1/locations/global/parameters/app_config/versions/configv2",
      "createTime": "2024-11-12T10:26:44.168165094Z",
      "updateTime": "2024-11-12T10:26:44.483145675Z"
    }
  ]
}

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 list_param_versions(project_id: str, parameter_id: str) -> None:
    """
    Lists all versions of an existing parameter in the global location
    of the specified project using the Google Cloud Parameter Manager SDK.

    Args:
        project_id (str): The ID of the project where the parameter is located.
        parameter_id (str): The ID of the parameter for
        which versions are to be listed.

    Returns:
        None

    Example:
        list_param_versions(
            "my-project",
            "my-global-parameter"
        )
    """
    # 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 request to list parameter versions.
    request = parametermanager_v1.ListParameterVersionsRequest(parent=parent)

    # List the parameter versions.
    page_result = client.list_parameter_versions(request=request)

    # Print the versions of the parameter.
    for response in page_result:
        print(f"Found parameter version: {response.name}")

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. Click the parameter name to view its versions.

    The parameter details page opens with the Versions tab in focus where you can see all the versions of the selected parameter.

gcloud

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

  • PARAMETER_ID: the name of the parameter
  • LOCATION: the Google Cloud location of the parameter

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud parametermanager parameters versions list --parameter=PARAMETER_ID --location=LOCATION

Windows (PowerShell)

gcloud parametermanager parameters versions list --parameter=PARAMETER_ID --location=LOCATION

Windows (cmd.exe)

gcloud parametermanager parameters versions list --parameter=PARAMETER_ID --location=LOCATION

You should receive a response similar to the following:

NAME                                                                                DISABLED  CREATE_TIME                     UPDATE_TIME
projects/production-1/locations/us-central1/parameters/app_config/versions/configv3            2024-11-14T10:07:12.883361876Z  2024-11-14T10:07:13.331806596Z

REST

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

HTTP method and URL: 

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

Request JSON body: 

{}

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

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 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" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "parameterVersions": [
    {
      "name": "projects/production-1/locations/us-central1/parameters/app_config/versions/configv3",
      "createTime": "2024-10-30T05:27:51.206825427Z",
      "updateTime": "2024-10-30T05:27:51.442194863Z"
    }
  ]
}

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 list_regional_param_versions(
    project_id: str, location_id: str, parameter_id: str
) -> None:
    """
    List all versions of a regional parameter in Google Cloud Parameter Manager.

    This function lists all versions of an existing
    parameter in the specified region of the specified project
    using the Google Cloud Parameter Manager SDK.

    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 versions are to be listed.

    Returns:
        None

    Example:
        list_regional_param_versions(
            "my-project",
            "us-central1",
            "my-regional-parameter"
        )
    """
    # 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 request to list parameter versions.
    request = parametermanager_v1.ListParameterVersionsRequest(parent=parent)

    # List the parameter versions.
    page_result = client.list_parameter_versions(request=request)

    # Print the versions of the parameter.
    for response in page_result:
        print(f"Found regional parameter version: {response.name}")

What's next