Listar versões regionais de secrets e conferir os detalhes da versão

Esta página descreve como recuperar uma lista de todas as versões diferentes de um secret que foram criadas ao longo do tempo e visualizar os metadados de uma versão específica.

Funções exigidas

Para receber as permissões necessárias para listar versões do secret e conferir os detalhes delas, peça ao administrador para conceder a você o papel do IAM de Leitor do Secret Manager (roles/secretmanager.viewer) no secret, projeto, pasta ou organização. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.

Listar as versões de um secret

Listar as versões de um secret é útil das seguintes maneiras:

  • Você pode conferir como um secret mudou ao longo do tempo, quem fez as alterações e quando. Isso é necessário para auditoria e compliance.

  • É possível reverter para uma versão anterior e confiável se um secret for atualizado ou comprometido acidentalmente.

  • Você pode identificar versões que não estão mais em uso e podem ser excluídas com segurança.

  • Você pode resolver problemas. Por exemplo, se um aplicativo estiver com problemas, você poderá examinar versões anteriores de um secret para saber se uma alteração nele é a causa.

Para listar todas as versões de um secret, use um dos seguintes métodos:

Console

  1. Acesse a página do Secret Manager no console do Google Cloud:

    Acessar o Secret Manager

  2. Na página Secret Manager, clique na guia Secrets regionais.

  3. Clique em um secret para acessar as versões dele.

    As versões pertencentes ao secret são exibidas na tabela Versões.

gcloud

Antes de usar os dados do comando abaixo, faça estas substituições:

  • SECRET_ID: o ID do secret ou do identificador totalmente qualificado.
  • LOCATION: o local do Google Cloud do segredo

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud secrets versions list SECRET_ID --location=LOCATION

Windows (PowerShell)

gcloud secrets versions list SECRET_ID --location=LOCATION

Windows (cmd.exe)

gcloud secrets versions list SECRET_ID --location=LOCATION

A resposta contém o segredo.

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • LOCATION: o local do Google Cloud do segredo
  • PROJECT_ID: o ID do projeto do Google Cloud
  • SECRET_ID: o ID do secret ou do identificador totalmente qualificado

Método HTTP e URL: 

GET https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID/versions

Corpo JSON da solicitação:

{}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID/versions"

PowerShell

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

$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://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID/versions" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "versions": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID/versions/VERSION_ID",
      "createTime": "2024-09-04T06:41:57.859674Z",
      "state": "ENABLED",
      "etag": "\"1621457b3c1459\""
    }
  ],
  "totalSize": 1
}

Go

Para executar esse código, primeiro configure um ambiente de desenvolvimento do Go e instale o SDK do Go do Secret Manager. No Compute Engine ou no GKE, você precisa fazer a autenticação com o escopo do cloud-platform. 

import (
	"context"
	"fmt"
	"io"

	secretmanager "cloud.google.com/go/secretmanager/apiv1"
	"cloud.google.com/go/secretmanager/apiv1/secretmanagerpb"
	"google.golang.org/api/iterator"
	"google.golang.org/api/option"
)

// listSecretVersions lists all secret versions in the given secret and their
// metadata.
func ListRegionalSecretVersions(w io.Writer, projectId, locationId, secretId string) error {
	// parent := "projects/my-project/locations/my-location/secrets/my-secret"

	// Create the client.
	ctx := context.Background()
	//Endpoint to send the request to regional server
	endpoint := fmt.Sprintf("secretmanager.%s.rep.googleapis.com:443", locationId)
	client, err := secretmanager.NewClient(ctx, option.WithEndpoint(endpoint))

	if err != nil {
		return fmt.Errorf("failed to create regional secretmanager client: %w", err)
	}
	defer client.Close()

	parent := fmt.Sprintf("projects/%s/locations/%s/secrets/%s", projectId, locationId, secretId)
	// Build the request.
	req := &secretmanagerpb.ListSecretVersionsRequest{
		Parent: parent,
	}

	// Call the API.
	it := client.ListSecretVersions(ctx, req)
	for {
		resp, err := it.Next()
		if err == iterator.Done {
			break
		}

		if err != nil {
			return fmt.Errorf("failed to list regional secret versions: %w", err)
		}

		fmt.Fprintf(w, "Found regional secret version %s with state %s\n",
			resp.Name, resp.State)
	}

	return nil
}

Java

Para executar esse código, primeiro configure um ambiente de desenvolvimento do Java e instale o SDK do Java do Secret Manager. No Compute Engine ou no GKE, você precisa fazer a autenticação com o escopo do cloud-platform. 

import com.google.cloud.secretmanager.v1.SecretManagerServiceClient;
import com.google.cloud.secretmanager.v1.SecretManagerServiceClient.ListSecretVersionsPagedResponse;
import com.google.cloud.secretmanager.v1.SecretManagerServiceSettings;
import com.google.cloud.secretmanager.v1.SecretName;
import java.io.IOException;

public class ListRegionalSecretVersions {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.

    // Your GCP project ID.
    String projectId = "your-project-id";
    // Location of the secret.
    String locationId = "your-location-id";
    // Resource ID of the secret.
    String secretId = "your-secret-id";
    listRegionalSecretVersions(projectId, locationId, secretId);
  }

  // List all secret versions for a secret.
  public static ListSecretVersionsPagedResponse listRegionalSecretVersions(
      String projectId, String locationId, String secretId)
      throws IOException {

    // Endpoint to call the regional secret manager sever
    String apiEndpoint = String.format("secretmanager.%s.rep.googleapis.com:443", locationId);
    SecretManagerServiceSettings secretManagerServiceSettings =
        SecretManagerServiceSettings.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 (SecretManagerServiceClient client = 
        SecretManagerServiceClient.create(secretManagerServiceSettings)) {
      // Build the parent name.
      SecretName secretName = 
          SecretName.ofProjectLocationSecretName(projectId, locationId, secretId);

      // Get all versions.
      ListSecretVersionsPagedResponse pagedResponse = client.listSecretVersions(secretName);

      // List all versions and their state.
      pagedResponse
          .iterateAll()
          .forEach(
              version -> {
                System.out.printf("Regional secret version %s, %s\n", 
                    version.getName(), version.getState());
              });

      return pagedResponse;
    }
  }
}

Node.js

Para executar esse código, primeiro configure um ambiente de desenvolvimento do Node.js e instale o SDK do Node.js do Secret Manager. No Compute Engine ou no GKE, você precisa fazer a autenticação com o escopo do cloud-platform. 

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const projectId = 'my-project';
// const locationId = 'my-location';
// const secretId = 'my-secret';

const parent = `projects/${projectId}/locations/${locationId}/secrets/${secretId}`;

// Imports the Secret Manager library
const {SecretManagerServiceClient} = require('@google-cloud/secret-manager');

// Adding the endpoint to call the regional secret manager sever
const options = {};
options.apiEndpoint = `secretmanager.${locationId}.rep.googleapis.com`;

// Instantiates a client
const client = new SecretManagerServiceClient(options);

async function listRegionalSecretVersions() {
  const [versions] = await client.listSecretVersions({
    parent: parent,
  });

  versions.forEach(version => {
    console.log(`${version.name}: ${version.state}`);
  });
}

listRegionalSecretVersions();

Python

Para executar esse código, primeiro configure um ambiente de desenvolvimento do Python e instale o SDK do Python do Secret Manager. No Compute Engine ou no GKE, você precisa fazer a autenticação com o escopo do cloud-platform. 

# Import the Secret Manager client library.
from google.cloud import secretmanager_v1


def list_regional_secret_versions(
    project_id: str, location_id: str, secret_id: str
) -> None:
    """
    Lists all secret versions in the given secret and their metadata.
    """

    # Endpoint to call the regional secret manager sever.
    api_endpoint = f"secretmanager.{location_id}.rep.googleapis.com"

    # Create the Secret Manager client.
    client = secretmanager_v1.SecretManagerServiceClient(
        client_options={"api_endpoint": api_endpoint},
    )

    # Build the resource name of the parent secret.
    parent = f"projects/{project_id}/locations/{location_id}/secrets/{secret_id}"

    # List all secret versions.
    for version in client.list_secret_versions(request={"parent": parent}):
        print(f"Found secret version: {version.name}")

Conferir detalhes sobre uma versão do secret

Esse processo permite que você acesse os metadados de uma versão do secret, como o ID da versão, a data e a hora de criação, os detalhes de criptografia e o status. A visualização dos metadados de uma versão do secret significa acessar informações sobre a versão do secret, mas não o valor real do secret. Para conferir o valor do secret, consulte Acessar uma versão regional do secret.

Para conferir os metadados de uma versão secreta, use um destes métodos:

Console

  1. Acesse a página do Secret Manager no console do Google Cloud:

    Acessar o Secret Manager

  2. Na página Secret Manager, clique na guia Secrets regionais.

  3. Clique em um secret para acessar as versões dele.

    As versões pertencentes ao secret são exibidas na tabela Versões. Para cada versão, o ID da versão e os metadados dela também são mostrados na tabela.

gcloud

Antes de usar os dados do comando abaixo, faça estas substituições:

  • VERSION_ID: o ID da versão do secret
  • SECRET_ID: o ID do secret ou do identificador totalmente qualificado.
  • LOCATION: o local do Google Cloud do segredo

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud secrets versions describe VERSION_ID --secret=SECRET_ID --location=LOCATION

Windows (PowerShell)

gcloud secrets versions describe VERSION_ID --secret=SECRET_ID --location=LOCATION

Windows (cmd.exe)

gcloud secrets versions describe VERSION_ID --secret=SECRET_ID --location=LOCATION

A resposta contém o segredo.

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • LOCATION: o local do Google Cloud do segredo
  • PROJECT_ID: o ID do projeto do Google Cloud
  • SECRET_ID: o ID do secret ou do identificador totalmente qualificado
  • VERSION_ID: o ID da versão do secret

Método HTTP e URL: 

GET https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID/versions/VERSION_ID

Corpo JSON da solicitação:

{}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID/versions/VERSION_ID"

PowerShell

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

$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://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID/versions/VERSION_ID" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID/versions/VERSION_ID",
  "createTime": "2024-09-04T06:41:57.859674Z",
  "state": "ENABLED",
  "etag": "\"1621457b3c1459\""
}

Go

Para executar esse código, primeiro configure um ambiente de desenvolvimento do Go e instale o SDK do Go do Secret Manager. No Compute Engine ou no GKE, você precisa fazer a autenticação com o escopo do cloud-platform. 

import (
	"context"
	"fmt"
	"io"

	secretmanager "cloud.google.com/go/secretmanager/apiv1"
	"cloud.google.com/go/secretmanager/apiv1/secretmanagerpb"
	"google.golang.org/api/option"
)

// getSecretVersion gets information about the given secret version. It does not
// include the payload data.
func GetRegionalSecretVersion(w io.Writer, projectId, locationId, secretId, versionId string) error {
	// name := "projects/my-project/locations/my-location/secrets/my-secret/versions/5"
	// name := "projects/my-project/locations/my-location/secrets/my-secret/versions/latest"

	// Create the client.
	ctx := context.Background()
	//Endpoint to send the request to regional server
	endpoint := fmt.Sprintf("secretmanager.%s.rep.googleapis.com:443", locationId)
	client, err := secretmanager.NewClient(ctx, option.WithEndpoint(endpoint))

	if err != nil {
		return fmt.Errorf("failed to create regional secretmanager client: %w", err)
	}
	defer client.Close()

	name := fmt.Sprintf("projects/%s/locations/%s/secrets/%s/versions/%s", projectId, locationId, secretId, versionId)
	// Build the request.
	req := &secretmanagerpb.GetSecretVersionRequest{
		Name: name,
	}

	// Call the API.
	result, err := client.GetSecretVersion(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to get regional secret version: %w", err)
	}

	fmt.Fprintf(w, "Found regional secret version %s with state %s\n",
		result.Name, result.State)
	return nil
}

Java

Para executar esse código, primeiro configure um ambiente de desenvolvimento do Java e instale o SDK do Java do Secret Manager. No Compute Engine ou no GKE, você precisa fazer a autenticação com o escopo do cloud-platform. 

import com.google.cloud.secretmanager.v1.SecretManagerServiceClient;
import com.google.cloud.secretmanager.v1.SecretManagerServiceSettings;
import com.google.cloud.secretmanager.v1.SecretVersion;
import com.google.cloud.secretmanager.v1.SecretVersionName;
import java.io.IOException;

public class GetRegionalSecretVersion {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.

    // Your GCP project ID.
    String projectId = "your-project-id";
    // Location of the secret.
    String locationId = "your-location-id";
    // Resource ID of the secret.
    String secretId = "your-secret-id";
    // Version of the Secret ID you want to retrieve.
    String versionId = "your-version-id";
    getRegionalSecretVersion(projectId, locationId, secretId, versionId);
  }

  // Get an existing secret version.
  public static SecretVersion getRegionalSecretVersion(
      String projectId, String locationId, String secretId, String versionId)
      throws IOException {

    // Endpoint to call the regional secret manager sever
    String apiEndpoint = String.format("secretmanager.%s.rep.googleapis.com:443", locationId);
    SecretManagerServiceSettings secretManagerServiceSettings =
        SecretManagerServiceSettings.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 (SecretManagerServiceClient client = 
        SecretManagerServiceClient.create(secretManagerServiceSettings)) {
      // Build the name from the version.
      SecretVersionName secretVersionName = 
          SecretVersionName.ofProjectLocationSecretSecretVersionName(
          projectId, locationId, secretId, versionId);

      // Create the secret.
      SecretVersion version = client.getSecretVersion(secretVersionName);
      System.out.printf("Regional secret version %s, state %s\n", 
          version.getName(), version.getState());

      return version;
    }
  }
}

Node.js

Para executar esse código, primeiro configure um ambiente de desenvolvimento do Node.js e instale o SDK do Node.js do Secret Manager. No Compute Engine ou no GKE, você precisa fazer a autenticação com o escopo do cloud-platform. 

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */

// const projectId = 'my-project';
// const locationId = 'my-location';
// const secretId = 'my-secret';
// const versionId = 'my-version';

const name = `projects/${projectId}/locations/${locationId}/secrets/${secretId}/versions/${version}`;

// Imports the Secret Manager library
const {SecretManagerServiceClient} = require('@google-cloud/secret-manager');

// Adding the endpoint to call the regional secret manager sever
const options = {};
options.apiEndpoint = `secretmanager.${locationId}.rep.googleapis.com`;

// Instantiates a client
const client = new SecretManagerServiceClient(options);

async function getRegionalSecretVersion() {
  const [version] = await client.getSecretVersion({
    name: name,
  });

  console.info(`Found secret ${version.name} with state ${version.state}`);
}

getRegionalSecretVersion();

Python

Para executar esse código, primeiro configure um ambiente de desenvolvimento do Python e instale o SDK do Python do Secret Manager. No Compute Engine ou no GKE, você precisa fazer a autenticação com o escopo do cloud-platform. 

# Import the Secret Manager client library.
from google.cloud import secretmanager_v1


def get_regional_secret_version(
    project_id: str,
    location_id: str,
    secret_id: str,
    version_id: str,
) -> secretmanager_v1.GetSecretVersionRequest:
    """
    Gets information about the given secret version. It does not include the
    payload data.
    """

    # Endpoint to call the regional secret manager sever.
    api_endpoint = f"secretmanager.{location_id}.rep.googleapis.com"

    # Create the Secret Manager client.
    client = secretmanager_v1.SecretManagerServiceClient(
        client_options={"api_endpoint": api_endpoint},
    )

    # Build the resource name of the secret version.
    name = f"projects/{project_id}/locations/{location_id}/secrets/{secret_id}/versions/{version_id}"

    # Get the secret version.
    response = client.get_secret_version(request={"name": name})

    # Print information about the secret version.
    state = response.state.name
    print(f"Got secret version {response.name} with state {state}")

    return response

A seguir