Crear y gestionar anotaciones

En esta página se describe cómo añadir anotaciones a un secreto regional y cómo editar y ver estas anotaciones.

Información general

Puedes usar anotaciones para almacenar metadatos personalizados sobre un secreto. Por ejemplo, puede que quieras anotar un secreto con la ruta en la que se montará. Las anotaciones pueden ser útiles de las siguientes formas:

  • Para clasificar los secretos en función de su finalidad, entorno (desarrollo, staging o producción) o nivel de sensibilidad. De esta forma, será más fácil buscar, filtrar y organizar secretos en Secret Manager.

  • Para indicar el formato o la estructura específicos del valor del secreto, lo que ayuda a la carga de trabajo a interpretarlo correctamente.

  • Para proporcionar sugerencias sobre cómo se debe usar el secreto o cualquier consideración especial para su gestión.

Por ejemplo, si tienes un secreto que contiene una contraseña de base de datos, puedes añadir anotaciones como las siguientes:

  • environment:production

  • purpose:database_access

  • owner:database_team

Estas anotaciones permiten identificar fácilmente el propósito del secreto, su entorno y quién es responsable de él. Además, una carga de trabajo que acceda a este secreto puede usar las anotaciones para confirmar que está usando la contraseña correcta para el entorno de producción.

Las anotaciones no son lo mismo que las etiquetas. Las etiquetas se usan para ordenar, filtrar y agrupar recursos, mientras que las anotaciones se usan para almacenar metadatos arbitrarios no identificativos en un secreto. Hay una restricción de caracteres y de longitud de caracteres al especificar metadatos en una etiqueta. Los metadatos de una anotación pueden ser pequeños o grandes, estructurados o no estructurados, y pueden incluir caracteres no permitidos por las etiquetas.

Roles obligatorios

  • Para añadir y actualizar anotaciones en un secreto, se necesita el rol Administrador de Secret Manager (roles/secretmanager.admin) en el secreto, el proyecto, la carpeta o la organización.

  • Para ver las anotaciones, se necesita el rol Lector de Secret Manager (roles/secretmanager.viewer) en el secreto, el proyecto, la carpeta o la organización.

Los roles de Gestión de Identidades y Accesos (IAM) no se pueden conceder en una versión de un secreto. Para obtener más información, consulta Control de acceso con la gestión de identidades y accesos.

Añadir anotaciones a un secreto

Puedes añadir anotaciones al crear un secreto o al actualizar uno que ya tengas. Los metadatos de una anotación se almacenan como pares clave-valor. Para añadir anotaciones, utilice uno de los siguientes métodos:

Consola

  1. En la Google Cloud consola, ve a la página Secret Manager.

    Ir a Secret Manager

  2. En la página Secret Manager, haz clic en la pestaña Secretos regionales y, a continuación, en Crear secreto regional.

  3. En la página Crear secreto regional, introduce un nombre para el secreto en el campo Nombre.

  4. Introduce un valor para el secreto (por ejemplo, abcd1234). También puedes subir un archivo de texto que contenga el valor del secreto con la opción Subir archivo. Esta acción crea automáticamente la versión del secreto.

  5. En la lista Región, selecciona la ubicación en la que quieres que se almacene tu secreto regional.

  6. Ve a la sección Anotaciones y haz clic en Añadir anotación.

  7. Introduce la clave y el valor correspondiente.

  8. Haz clic en Crear secreto.

gcloud

Antes de usar los datos de los comandos que se indican a continuación, haz los siguientes cambios:

  • SECRET_ID: el ID del secreto
  • LOCATION: la Google Cloud ubicación del secreto
  • KEY: la clave de la anotación
  • VALUE: el valor correspondiente de la clave de anotación.

Ejecuta el siguiente comando:

Linux, macOS o Cloud Shell

gcloud secrets create SECRET_ID --location=LOCATION \
    --set-annotations=KEY1=VAL1,KEY2=VAL2

Windows (PowerShell)

gcloud secrets create SECRET_ID --location=LOCATION `
    --set-annotations=KEY1=VAL1,KEY2=VAL2

Windows (cmd.exe)

gcloud secrets create SECRET_ID --location=LOCATION ^
    --set-annotations=KEY1=VAL1,KEY2=VAL2

La respuesta contiene el secreto y las anotaciones.

REST

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • LOCATION: la Google Cloud ubicación del secreto
  • PROJECT_ID: el ID del proyecto Google Cloud
  • SECRET_ID: el ID del secreto
  • KEY: la clave de la anotación
  • VALUE: el valor correspondiente de la clave de anotación.

Método HTTP y URL: 

PATCH https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID?updateMask=annotations

Cuerpo JSON de la solicitud: 

{'annotations': {'KEY1': 'VALUE1', 'KEY2': 'VALUE2' }}

Para enviar tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando: 

curl -X PATCH \
     -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?updateMask=annotations"

PowerShell

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -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?updateMask=annotations" | Select-Object -Expand Content

Deberías recibir una respuesta JSON similar a la siguiente:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID",
  "createTime": "2024-09-02T07:14:00.281541Z",
  "etag": "\"16211dcd99c386\"",
  "annotations": {
    "key1": "value1",
    "key2": "value2"
  }
}

C#

Para ejecutar este código, primero debes configurar un entorno de desarrollo de C# e instalar el SDK de Secret Manager para C#. En Compute Engine o GKE, debes autenticarte con el ámbito cloud-platform. 


using Google.Api.Gax.ResourceNames;
using Google.Cloud.SecretManager.V1;
using System.Collections.Generic;

public class CreateRegionalSecretWithAnnotationsSample
{
    public Secret CreateRegionalSecretWithAnnotations(
      string projectId = "my-project",
      string locationId = "my-location",
      string secretId = "my-secret",
      string annotationKey = "my-annotation-key",
      string annotationValue = "my-annotation-value"
    )
    {
        // Create the Regional Secret Manager Client.
        SecretManagerServiceClient client = new SecretManagerServiceClientBuilder
        {
            Endpoint = $"secretmanager.{locationId}.rep.googleapis.com"
        }.Build();

        // Build the parent resource name.
        LocationName location = new LocationName(projectId, locationId);

        // Build the secret.
        Secret secret = new Secret
        {
            Annotations =
          {
              { annotationKey, annotationValue }
          },
        };

        // Call the API.
        Secret createdSecret = client.CreateSecret(location, secretId, secret);
        return createdSecret;
    }
}

Go

Para ejecutar este código, primero debes configurar un entorno de desarrollo de Go e instalar el SDK de Go de Secret Manager. En Compute Engine o GKE, debes autenticarte con el ámbito 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"
)

// createRegionalSecretWithAnnotations creates a new secret with the given name and annotations.
func createRegionalSecretWithAnnotations(w io.Writer, projectId, locationId, secretId string) error {
	// parent := "projects/my-project"
	// id := "my-secret"

	annotationKey := "annotationkey"
	annotationValue := "annotationvalue"

	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 secretmanager client: %w", err)
	}
	defer client.Close()

	parent := fmt.Sprintf("projects/%s/locations/%s", projectId, locationId)

	// Build the request.
	req := &secretmanagerpb.CreateSecretRequest{
		Parent:   parent,
		SecretId: secretId,
		Secret: &secretmanagerpb.Secret{
			Annotations: map[string]string{
				annotationKey: annotationValue,
			},
		},
	}

	result, err := client.CreateSecret(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to create secret: %w", err)
	}
	fmt.Fprintf(w, "Created secret with annotations: %s\n", result.Name)
	return nil
}

Java

Para ejecutar este código, primero debes configurar un entorno de desarrollo de Java e instalar el SDK de Java de Secret Manager. En Compute Engine o GKE, debes autenticarte con el ámbito cloud-platform. 

import com.google.cloud.secretmanager.v1.LocationName;
import com.google.cloud.secretmanager.v1.Secret;
import com.google.cloud.secretmanager.v1.SecretManagerServiceClient;
import com.google.cloud.secretmanager.v1.SecretManagerServiceSettings;
import java.io.IOException;

public class CreateRegionalSecretWithAnnotations {

  public static void createRegionalSecretWithAnnotations() throws IOException {
    // TODO(developer): Replace these variables before running the sample.

    // This is the id of the GCP project
    String projectId = "your-project-id";
    // Location of the secret.
    String locationId = "your-location-id";
    // This is the id of the secret to act on
    String secretId = "your-secret-id";
    // This is the key of the annotation to be added
    String annotationKey = "your-annotation-key";
    // This is the value of the annotation to be added
    String annotationValue = "your-annotation-value";
    createRegionalSecretWithAnnotations(
        projectId, locationId, secretId, annotationKey, annotationValue
    );
  }

  // Create a secret with annotations.
  public static Secret createRegionalSecretWithAnnotations(
        String projectId,
        String locationId,
        String secretId,
        String annotationKey,
        String annotationValue
  ) 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 from the project.
      LocationName location = LocationName.of(projectId, locationId);

      // Build the secret to create with labels.
      Secret secret =
          Secret.newBuilder()
                .putAnnotations(annotationKey, annotationValue)
                .build();

      // Create the secret.
      Secret createdSecret = client.createSecret(location.toString(), secretId, secret);
      System.out.printf("Created secret %s\n", createdSecret.getName());
      return createdSecret;
    }
  }
}

Node.js

Para ejecutar este código, primero debes configurar un entorno de desarrollo de Node.js e instalar el SDK de Node.js de Secret Manager. En Compute Engine o GKE, debes autenticarte con el ámbito cloud-platform. 

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

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

// 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 createRegionalSecretWithAnnotations() {
  const [secret] = await client.createSecret({
    parent: parent,
    secretId: secretId,
    secret: {
      annotations: {
        [annotationKey]: annotationValue,
      },
    },
  });

  console.log(`Created secret ${secret.name}`);
}

createRegionalSecretWithAnnotations();

PHP

Para ejecutar este código, primero debes consultar información sobre cómo usar PHP en Google Cloud e instalar el SDK de PHP de Secret Manager. En Compute Engine o GKE, debes autenticarte con el ámbito cloud-platform. 

// Import the Secret Manager client library.
use Google\Cloud\SecretManager\V1\CreateSecretRequest;
use Google\Cloud\SecretManager\V1\Secret;
use Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient;

/**
 * @param string $projectId       Your Google Cloud Project ID (e.g. 'my-project')
 * @param string $locationId      Your Google Cloud Location ID (e.g. 'us-central1')
 * @param string $secretId        Your secret ID (e.g. 'my-secret')
 * @param string $annotationKey   Your annotation key (e.g. 'annotation-key')
 * @param string $annotationValue Your annotation value (e.g. 'annotation-value')
 */
function create_regional_secret_with_annotations(string $projectId, string $locationId, string $secretId, string $annotationKey, string $annotationValue): void
{
    // Specify regional endpoint.
    $options = ['apiEndpoint' => "secretmanager.$locationId.rep.googleapis.com"];

    // Create the Secret Manager client.
    $client = new SecretManagerServiceClient($options);

    // Build the resource name of the parent project.
    $parent = $client->locationName($projectId, $locationId);

    $secret = new Secret();

    // set the annotations.
    $annotations = [$annotationKey => $annotationValue];
    $secret->setAnnotations($annotations);

    // Build the request.
    $request = CreateSecretRequest::build($parent, $secretId, $secret);

    // Create the secret.
    $newSecret = $client->createSecret($request);

    // Print the new secret name.
    printf('Created secret %s with annotations', $newSecret->getName());
}

Python

Para ejecutar este código, primero debes configurar un entorno de desarrollo de Python e instalar el SDK de Python de Secret Manager. En Compute Engine o GKE, debes autenticarte con el ámbito cloud-platform. 

import argparse
import typing

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


def create_regional_secret_with_annotations(
    project_id: str,
    location_id: str,
    secret_id: str,
    annotations: typing.Dict[str, str],
) -> secretmanager_v1.Secret:
    """
    Create a new secret with the given name. A secret is a logical wrapper
    around a collection of secret versions. Secret versions hold the actual
    secret material.
    """

    # 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 project.
    parent = f"projects/{project_id}/locations/{location_id}"

    # Create the secret.
    response = client.create_secret(
        request={
            "parent": parent,
            "secret_id": secret_id,
            "secret": {"annotations": annotations},
        }
    )

    # Print the new secret name.
    print(f"Created secret: {response.name}")

    return response

Ruby

Para ejecutar este código, primero debes configurar un entorno de desarrollo de Ruby e instalar el SDK de Ruby de Secret Manager. En Compute Engine o GKE, debes autenticarte con el ámbito cloud-platform. 

require "google/cloud/secret_manager"

##
# Create a regional secret with annotations
#
# @param project_id [String] Your Google Cloud project (e.g. "my-project")
# @param location_id [String] Your Google Cloud location (e.g. "us-west1")
# @param secret_id [String] Your secret name (e.g. "my-secret")
# @param annotation_key [String] Your annotation key (e.g. "my-annotation-key")
# @param annotation_value [String] Your annotation value (e.g "my-annotation-value")
#
def create_regional_secret_with_annotations project_id:, location_id:, secret_id:, annotation_key:, annotation_value:
  # Endpoint for the regional secret manager service.
  api_endpoint = "secretmanager.#{location_id}.rep.googleapis.com"

  # Create the Secret Manager client.
  client = Google::Cloud::SecretManager.secret_manager_service do |config|
    config.endpoint = api_endpoint
  end

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

  # Create the secret.
  secret = client.create_secret(
    parent:    parent,
    secret_id: secret_id,
    secret: {
      annotations: {
        annotation_key => annotation_value
      }
    }
  )

  # Print the new secret name.
  puts "Created regional secret with annotations: #{secret.name}"
end

Para añadir anotaciones a un secreto, consulta la sección Editar anotaciones de este documento.

Las claves de anotación deben cumplir los siguientes requisitos:

  • Las claves deben ser únicas para cada secreto. No puedes repetir una clave en el mismo secreto.

  • Las claves deben tener entre 1 y 63 caracteres.

  • Las claves deben tener una codificación UTF-8 de 128 bytes como máximo.

  • Las claves deben empezar y terminar con un carácter alfanumérico.

  • Las claves pueden tener guiones, guiones bajos y puntos entre los caracteres alfanuméricos.

  • El tamaño total de las claves y los valores de las anotaciones debe ser inferior a 16 KiB.

Editar anotaciones

Para editar anotaciones, utiliza uno de los siguientes métodos:

Consola

  1. En la Google Cloud consola, ve a la página Secret Manager.

    Ir a Secret Manager

  2. En la página Secret Manager, haz clic en la pestaña Secretos regionales.

  3. Busca el secreto en la lista y haz clic en el menú Acciones asociado a ese secreto. En el menú Acciones, haz clic en Editar.

  4. En la página Editar secreto, ve a la sección Anotaciones. Aquí puedes cambiar el valor de una anotación, eliminarla o añadir una nueva.

  5. Cuando haya hecho los cambios, haga clic en Actualizar secreto.

gcloud

Editar anotaciones

Antes de usar los datos de los comandos que se indican a continuación, haz los siguientes cambios:

  • SECRET_ID: el ID del secreto
  • LOCATION: la Google Cloud ubicación del secreto
  • KEY: la clave de la anotación
  • VALUE: el valor correspondiente de la clave de anotación.

Ejecuta el siguiente comando:

Linux, macOS o Cloud Shell

gcloud secrets update SECRET_ID --location=LOCATION --update-annotations= KEY=VAL

Windows (PowerShell)

gcloud secrets update SECRET_ID --location=LOCATION --update-annotations= KEY=VAL

Windows (cmd.exe)

gcloud secrets update SECRET_ID --location=LOCATION --update-annotations= KEY=VAL

La respuesta edita el secreto y las anotaciones.

Eliminar una anotación específica

Para quitar anotaciones, usa el siguiente comando:

gcloud secrets update SECRET_ID --location=LOCATION --remove-annotations= KEY=VAL

Borrar todas las anotaciones

Para borrar todas las anotaciones, usa el siguiente comando:

gcloud secrets update SECRET_ID --location=LOCATION --clear-annotations

REST

Para borrar todas las anotaciones, usa el siguiente comando:

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • LOCATION: la Google Cloud ubicación del secreto
  • PROJECT_ID: el ID del proyecto Google Cloud
  • SECRET_ID: el ID del secreto

Método HTTP y URL: 

PATCH https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID?updateMask=annotations

Cuerpo JSON de la solicitud: 

{'annotations': {}}

Para enviar tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando: 

curl -X PATCH \
     -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?updateMask=annotations"

PowerShell

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -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?updateMask=annotations" | Select-Object -Expand Content

Deberías recibir una respuesta JSON similar a la siguiente:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID",
  "createTime": "2024-09-02T07:14:00.281541Z",
  "etag": "\"16211dd90b37e7\""
}

C#

Para ejecutar este código, primero debes configurar un entorno de desarrollo de C# e instalar el SDK de Secret Manager para C#. En Compute Engine o GKE, debes autenticarte con el ámbito cloud-platform. 


using Google.Api.Gax.ResourceNames;
using Google.Cloud.SecretManager.V1;
using Google.Protobuf.Collections;
using Google.Protobuf.WellKnownTypes;


public class EditRegionalSecretAnnotationsSample
{
    public Secret EditRegionalSecretAnnotations(
      string projectId = "my-project",
      string locationId = "my-location",
      string secretId = "my-secret",
      string annotationKey = "my-annotation-key",
      string annotationValue = "my-annotation-value"
    )
    {
        // Create the Regional Secret Manager Client.
        SecretManagerServiceClient client = new SecretManagerServiceClientBuilder
        {
            Endpoint = $"secretmanager.{locationId}.rep.googleapis.com"
        }.Build();

        // Build the resource name.
        SecretName secretName = SecretName.FromProjectLocationSecret(projectId, locationId, secretId);

        // Get the exisitng secret.
        Secret existingSecret = client.GetSecret(secretName);

        // Add the mapping to the secret's annotations
        existingSecret.Annotations[annotationKey] = annotationValue;

        // Build the field mask.
        FieldMask fieldMask = FieldMask.FromString("annotations");

        // Call the update secret API.
        Secret updatedSecret = client.UpdateSecret(existingSecret, fieldMask);

        return updatedSecret;

    }
}

Go

Para ejecutar este código, primero debes configurar un entorno de desarrollo de Go e instalar el SDK de Go de Secret Manager. En Compute Engine o GKE, debes autenticarte con el ámbito 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"
	"google.golang.org/genproto/protobuf/field_mask"
)

// editRegionalSecretAnnotations updates the annotations about an existing secret.
// If the annotation key exists, it updates the annotation, otherwise it creates a new one.
func editRegionalSecretAnnotation(w io.Writer, projectId, locationId, secretId string) error {
	// name := "projects/my-project/secrets/my-secret"

	annotationKey := "annotationkey"
	annotationValue := "updatedannotationvalue"

	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 secretmanager client: %w", err)
	}
	defer client.Close()

	name := fmt.Sprintf("projects/%s/locations/%s/secrets/%s", projectId, locationId, secretId)

	// Build the request to get the secret.
	req := &secretmanagerpb.GetSecretRequest{
		Name: name,
	}

	result, err := client.GetSecret(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to get secret: %w", err)
	}

	annotations := result.Annotations

	annotations[annotationKey] = annotationValue

	// Build the request to update the secret.
	update_req := &secretmanagerpb.UpdateSecretRequest{
		Secret: &secretmanagerpb.Secret{
			Name:        name,
			Annotations: annotations,
		},
		UpdateMask: &field_mask.FieldMask{
			Paths: []string{"annotations"},
		},
	}

	// Call the API.
	update_result, err := client.UpdateSecret(ctx, update_req)
	if err != nil {
		return fmt.Errorf("failed to update secret: %w", err)
	}
	fmt.Fprintf(w, "Updated secret: %s\n", update_result.Name)
	return nil
}

Java

Para ejecutar este código, primero debes configurar un entorno de desarrollo de Java e instalar el SDK de Java de Secret Manager. En Compute Engine o GKE, debes autenticarte con el ámbito cloud-platform. 

import com.google.cloud.secretmanager.v1.Secret;
import com.google.cloud.secretmanager.v1.SecretManagerServiceClient;
import com.google.cloud.secretmanager.v1.SecretManagerServiceSettings;
import com.google.cloud.secretmanager.v1.SecretName;
import com.google.protobuf.FieldMask;
import com.google.protobuf.util.FieldMaskUtil;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

public class EditRegionalSecretAnnotations {

  public static void editRegionalSecretAnnotations() throws IOException {
    // TODO(developer): Replace these variables before running the sample.

    // This is the id of the GCP project
    String projectId = "your-project-id";
    // Location of the secret.
    String locationId = "your-location-id";
    // This is the id of the secret to act on
    String secretId = "your-secret-id";
    // This is the key of the annotation to be added/updated
    String annotationKey = "your-annotation-key";
    // This is the value of the annotation to be added/updated
    String annotationValue = "your-annotation-value";
    editRegionalSecretAnnotations(
        projectId, locationId, secretId, annotationKey, annotationValue
    );
  }

  // Update an existing secret, by creating a new annotation or updating an existing annotation.
  public static Secret editRegionalSecretAnnotations(
      String projectId,
      String locationId,
      String secretId,
      String annotationKey,
      String annotationValue
  ) 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.
      SecretName secretName = 
          SecretName.ofProjectLocationSecretName(projectId, locationId, secretId);

      // Get the existing secret
      Secret existingSecret = client.getSecret(secretName);

      Map<String, String> existingAnnotationsMap = 
          new HashMap<String, String>(existingSecret.getAnnotationsMap());

      // Add a new annotation key and value.
      existingAnnotationsMap.put(annotationKey, annotationValue);

      // Build the updated secret.
      Secret secret =
          Secret.newBuilder()
              .setName(secretName.toString())
              .putAllAnnotations(existingAnnotationsMap)
              .build();

      // Build the field mask.
      FieldMask fieldMask = FieldMaskUtil.fromString("annotations");

      // Update the secret.
      Secret updatedSecret = client.updateSecret(secret, fieldMask);
      System.out.printf("Updated secret %s\n", updatedSecret.getName());

      return updatedSecret;
    }
  }
}

Node.js

Para ejecutar este código, primero debes configurar un entorno de desarrollo de Node.js e instalar el SDK de Node.js de Secret Manager. En Compute Engine o GKE, debes autenticarte con el ámbito cloud-platform. 

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

const name = `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 getSecret() {
  const [secret] = await client.getSecret({
    name: name,
  });

  return secret;
}

async function editRegionalSecretAnnotations() {
  const oldSecret = await getSecret();
  oldSecret.annotations[annotationKey] = annotationValue;
  const [secret] = await client.updateSecret({
    secret: {
      name: name,
      annotations: oldSecret.annotations,
    },
    updateMask: {
      paths: ['annotations'],
    },
  });

  console.info(`Updated secret ${secret.name}`);
}

editRegionalSecretAnnotations();

PHP

Para ejecutar este código, primero debes consultar información sobre cómo usar PHP en Google Cloud e instalar el SDK de PHP de Secret Manager. En Compute Engine o GKE, debes autenticarte con el ámbito cloud-platform. 

// Import the Secret Manager client library.
use Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient;
use Google\Cloud\SecretManager\V1\GetSecretRequest;
use Google\Cloud\SecretManager\V1\UpdateSecretRequest;
use Google\Protobuf\FieldMask;

/**
 * @param string $projectId       Your Google Cloud Project ID (e.g. 'my-project')
 * @param string $locationId      Your secret Location (e.g. 'us-central1')
 * @param string $secretId        Your secret ID (e.g. 'my-secret')
 * @param string $annotationKey   Your annotation key (e.g. 'annotation-key')
 * @param string $annotationValue Your annotation value (e.g. 'annotation-value')
 */
function edit_regional_secret_annotations(string $projectId, string $locationId, string $secretId, string $annotationKey, string $annotationValue): void
{
    // Specify regional endpoint.
    $options = ['apiEndpoint' => "secretmanager.$locationId.rep.googleapis.com"];

    // Create the Secret Manager client.
    $client = new SecretManagerServiceClient($options);

    // Build the resource name of the secret.
    $name = $client->projectLocationSecretName($projectId, $locationId, $secretId);

    // Build the request.
    $request = GetSecretRequest::build($name);

    // get the secret.
    $getSecret = $client->getSecret($request);

    // get the annotations
    $annotations = $getSecret->getAnnotations();

    // update the annotation - need to create a new annotations map with the updated values
    $newAnnotations = [];
    foreach ($annotations as $key => $value) {
        $newAnnotations[$key] = $value;
    }
    $newAnnotations[$annotationKey] = $annotationValue;
    $getSecret->setAnnotations($newAnnotations);

    // set the field mask
    $fieldMask = new FieldMask();
    $fieldMask->setPaths(['annotations']);

    // build the secret
    $request = new UpdateSecretRequest();
    $request->setSecret($getSecret);
    $request->setUpdateMask($fieldMask);

    // update the secret
    $updateSecret = $client->updateSecret($request);

    // print the updated secret
    printf('Updated secret %s annotations' . PHP_EOL, $updateSecret->getName());
}

Python

Para ejecutar este código, primero debes configurar un entorno de desarrollo de Python e instalar el SDK de Python de Secret Manager. En Compute Engine o GKE, debes autenticarte con el ámbito cloud-platform. 


import argparse
from typing import Dict

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


def edit_regional_secret_annotations(
    project_id: str, location_id: str, secret_id: str, new_annotations: Dict[str, str]
) -> secretmanager_v1.UpdateSecretRequest:
    """
    Create or update a annotation on an existing secret.
    """

    # 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.
    name = f"projects/{project_id}/locations/{location_id}/secrets/{secret_id}"

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

    annotations = response.annotations

    # Update the annotations
    for annotation_key in new_annotations:
        annotations[annotation_key] = new_annotations[annotation_key]

    # Update the secret.
    secret = {"name": name, "annotations": annotations}
    update_mask = {"paths": ["annotations"]}
    response = client.update_secret(
        request={"secret": secret, "update_mask": update_mask}
    )

    # Print the new secret name.
    print(f"Updated secret: {response.name}")

    return response

Ruby

Para ejecutar este código, primero debes configurar un entorno de desarrollo de Ruby e instalar el SDK de Ruby de Secret Manager. En Compute Engine o GKE, debes autenticarte con el ámbito cloud-platform. 

require "google/cloud/secret_manager"

##
# Edit a regional secret annotations
#
# @param project_id [String] Your Google Cloud project (e.g. "my-project")
# @param location_id [String] Your Google Cloud location (e.g. "us-west11")
# @param secret_id [String] Your secret name (e.g. "my-secret")
# @param annotation_key [String] Your annotation key (e.g. "my-annotation-key")
# @param annotation_value [String] Your annotation value (e.g. "my-annotation-value")
#
def edit_regional_secret_annotations project_id:, location_id:, secret_id:, annotation_key:, annotation_value:
  # Endpoint for the regional secret manager service.
  api_endpoint = "secretmanager.#{location_id}.rep.googleapis.com"

  # Create the Secret Manager client.
  client = Google::Cloud::SecretManager.secret_manager_service do |config|
    config.endpoint = api_endpoint
  end

  # Build the resource name of the secret.
  name = client.secret_path project: project_id, location: location_id, secret: secret_id

  # Get the existing secret.
  existing_secret = client.get_secret name: name

  # Get the existing secret's annotations.
  existing_secret_annotations = existing_secret.annotations.to_h

  # Add a new annotation key and value.
  existing_secret_annotations[annotation_key] = annotation_value

  # Updates the secret.
  secret = client.update_secret(
    secret: {
      name: name,
      annotations: existing_secret_annotations
    },
    update_mask: {
      paths: ["annotations"]
    }
  )

  # Print the updated secret name and annotations.
  puts "Updated regional secret: #{secret.name}"
  puts "New updated annotations: #{secret.annotations}"
end

Ver anotaciones

Para ver las anotaciones asociadas a un secreto, utilice uno de los siguientes métodos:

Consola

  1. En la Google Cloud consola, ve a la página Secret Manager.

    Ir a Secret Manager

  2. En la página Secret Manager, haz clic en la pestaña Secretos regionales y, a continuación, en el secreto cuyas anotaciones quieras ver.

  3. Se abrirá la página de detalles del secreto. Haga clic en la pestaña Descripción general. Aquí puede ver las anotaciones adjuntas al secreto. Las claves se muestran en la columna de la izquierda, mientras que los valores se muestran en la columna de la derecha.

gcloud

Antes de usar los datos de los comandos que se indican a continuación, haz los siguientes cambios:

  • SECRET_ID: el ID del secreto
  • LOCATION: la Google Cloud ubicación del secreto

Ejecuta el siguiente comando:

Linux, macOS o Cloud Shell

gcloud secrets describe SECRET_ID --location=LOCATION

Windows (PowerShell)

gcloud secrets describe SECRET_ID --location=LOCATION

Windows (cmd.exe)

gcloud secrets describe SECRET_ID --location=LOCATION

La respuesta contiene el secreto y las anotaciones.

REST

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • LOCATION: la Google Cloud ubicación del secreto
  • PROJECT_ID: el ID del proyecto Google Cloud
  • SECRET_ID: el ID del secreto

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud: 

{}

Para enviar tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando: 

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"

PowerShell

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando: 

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

Deberías recibir una respuesta JSON similar a la siguiente:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID",
  "createTime": "2024-09-02T07:14:00.281541Z",
  "etag": "\"16211dcd99c386\"",
  "annotations": {
    "key1": "value1",
    "key2": "value2"
  }
}

C#

Para ejecutar este código, primero debes configurar un entorno de desarrollo de C# e instalar el SDK de Secret Manager para C#. En Compute Engine o GKE, debes autenticarte con el ámbito cloud-platform. 


using Google.Api.Gax.ResourceNames;
using Google.Cloud.SecretManager.V1;
using Google.Protobuf.Collections;
using Google.Protobuf.WellKnownTypes;
using System;


public class ViewRegionalSecretAnnotationsSample
{
    public Secret ViewRegionalSecretAnnotations(
      string projectId = "my-project",
      string locationId = "my-location",
      string secretId = "my-secret"
    )
    {
        // Create the Regional Secret Manager Client.
        SecretManagerServiceClient client = new SecretManagerServiceClientBuilder
        {
            Endpoint = $"secretmanager.{locationId}.rep.googleapis.com"
        }.Build();

        // Build the resource name.
        SecretName secretName = SecretName.FromProjectLocationSecret(projectId, locationId, secretId);

        // Get the secret.
        Secret secret = client.GetSecret(secretName);

        // Get the secret's annotations.
        MapField<string, string> secretAnnotations = secret.Annotations;

        // Print the annotations.
        foreach (var annotation in secret.Annotations)
        {
            Console.WriteLine($"Annotation Key: {annotation.Key}, Annotation Value: {annotation.Value}");
        }

        return secret;
    }
}

Go

Para ejecutar este código, primero debes configurar un entorno de desarrollo de Go e instalar el SDK de Go de Secret Manager. En Compute Engine o GKE, debes autenticarte con el ámbito 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"
)

// viewRegionalSecretAnnotations gets annotations with the given secret.
func viewRegionalSecretAnnotations(w io.Writer, projectId, locationId, secretId string) error {
	// name := "projects/my-project/secrets/my-secret"

	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 secretmanager client: %w", err)
	}
	defer client.Close()

	name := fmt.Sprintf("projects/%s/locations/%s/secrets/%s", projectId, locationId, secretId)

	// Build the request.
	req := &secretmanagerpb.GetSecretRequest{
		Name: name,
	}

	result, err := client.GetSecret(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to get secret: %w", err)
	}

	annotations := result.Annotations
	fmt.Fprintf(w, "Found secret %s\n", result.Name)

	for key, value := range annotations {
		fmt.Fprintf(w, "Annotations key %s : Annotations Value %s", key, value)
	}
	return nil
}

Java

Para ejecutar este código, primero debes configurar un entorno de desarrollo de Java e instalar el SDK de Java de Secret Manager. En Compute Engine o GKE, debes autenticarte con el ámbito cloud-platform. 

import com.google.cloud.secretmanager.v1.Secret;
import com.google.cloud.secretmanager.v1.SecretManagerServiceClient;
import com.google.cloud.secretmanager.v1.SecretManagerServiceSettings;
import com.google.cloud.secretmanager.v1.SecretName;
import java.io.IOException;
import java.util.Map;

public class ViewRegionalSecretAnnotations {

  public static void viewRegionalSecretAnnotations() throws IOException {
    // TODO(developer): Replace these variables before running the sample.

    // This is the id of the GCP project
    String projectId = "your-project-id";
    // Location of the secret.
    String locationId = "your-location-id";
    // This is the id of the secret whose annotations to view
    String secretId = "your-secret-id";
    viewRegionalSecretAnnotations(projectId, locationId, secretId);
  }

  // View the annotations of an existing secret.
  public static Map<String, String> viewRegionalSecretAnnotations(
      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 name.
      SecretName secretName = 
          SecretName.ofProjectLocationSecretName(projectId, locationId, secretId);

      // Create the secret.
      Secret secret = client.getSecret(secretName);

      Map<String, String> annotations = secret.getAnnotationsMap();

      System.out.printf("Secret %s \n", secret.getName());

      for (Map.Entry<String, String> annotation : annotations.entrySet()) {
        System.out.printf("Annotation key : %s, Annotation Value : %s\n", 
            annotation.getKey(), annotation.getValue());
      }

      return secret.getAnnotationsMap();
    }
  }
}

Node.js

Para ejecutar este código, primero debes configurar un entorno de desarrollo de Node.js e instalar el SDK de Node.js de Secret Manager. En Compute Engine o GKE, debes autenticarte con el ámbito cloud-platform. 

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

const name = `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 viewRegionalSecretAnnotations() {
  const [secret] = await client.getSecret({
    name: name,
  });

  for (const key in secret.annotations) {
    console.log(`${key} : ${secret.annotations[key]}`);
  }
}

viewRegionalSecretAnnotations();

PHP

Para ejecutar este código, primero debes consultar información sobre cómo usar PHP en Google Cloud e instalar el SDK de PHP de Secret Manager. En Compute Engine o GKE, debes autenticarte con el ámbito cloud-platform. 

// Import the Secret Manager client library.
use Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient;
use Google\Cloud\SecretManager\V1\GetSecretRequest;

/**
 * @param string $projectId  Your Google Cloud Project ID (e.g. 'my-project')
 * @param string $locationId Your secret Location (e.g. 'us-central1')
 * @param string $secretId   Your secret ID (e.g. 'my-secret')
 */
function view_regional_secret_annotations(string $projectId, string $locationId, string $secretId): void
{
    // Specify regional endpoint.
    $options = ['apiEndpoint' => "secretmanager.$locationId.rep.googleapis.com"];

    // Create the Secret Manager client.
    $client = new SecretManagerServiceClient($options);

    // Build the resource name of the secret.
    $name = $client->projectLocationSecretName($projectId, $locationId, $secretId);

    // Build the request.
    $request = GetSecretRequest::build($name);

    // get the secret.
    $getSecret = $client->getSecret($request);

    // get the annotations
    $annotations = $getSecret->getAnnotations();

    // print the secret name
    printf('Get secret %s with annotation:' . PHP_EOL, $getSecret->getName());
    // we can even loop over all the annotations
    foreach ($annotations as $key => $val) {
        printf("\t$key: $val" . PHP_EOL);
    }
}

Python

Para ejecutar este código, primero debes configurar un entorno de desarrollo de Python e instalar el SDK de Python de Secret Manager. En Compute Engine o GKE, debes autenticarte con el ámbito cloud-platform. 

import argparse

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


def view_regional_secret_annotations(
    project_id: str, location_id: str, secret_id: str
) -> None:
    """
    List all secret annotations in the given secret.
    """
    # 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.
    name = f"projects/{project_id}/locations/{location_id}/secrets/{secret_id}"

    response = client.get_secret(request={"name": name})

    print(f"Got secret {response.name} with annotations :")
    for key in response.annotations:
        print(f"{key} : {response.annotations[key]}")

Ruby

Para ejecutar este código, primero debes configurar un entorno de desarrollo de Ruby e instalar el SDK de Ruby de Secret Manager. En Compute Engine o GKE, debes autenticarte con el ámbito cloud-platform. 

require "google/cloud/secret_manager"

##
# Edit a regional secret annotations
#
# @param project_id [String] Your Google Cloud project (e.g. "my-project")
# @param location_id [String] Your Google Cloud location (e.g. "us-west11")
# @param secret_id [String] Your secret name (e.g. "my-secret")
#
def view_regional_secret_annotations project_id:, location_id:, secret_id:
  # Endpoint for the regional secret manager service.
  api_endpoint = "secretmanager.#{location_id}.rep.googleapis.com"

  # Create the Secret Manager client.
  client = Google::Cloud::SecretManager.secret_manager_service do |config|
    config.endpoint = api_endpoint
  end

  # Build the resource name of the secret.
  name = client.secret_path project: project_id, location: location_id, secret: secret_id

  # Get the existing secret.
  existing_secret = client.get_secret name: name

  # Get the existing secret's annotations.
  existing_secret_annotations = existing_secret.annotations.to_h

  # Print the secret name and the annotations.
  puts "Regional Secret: #{existing_secret.name}"
  existing_secret_annotations.each do |key, value|
    puts "Annotation Key: #{key}, Annotation Value: #{value}"
  end
end

Siguientes pasos