Añadir una versión de secreto regional

Los datos de los secretos son inmutables y casi todas las operaciones se llevan a cabo en versiones de secretos. Una versión de un secreto contiene los datos del secreto propiamente dichos, junto con el estado y los metadatos del secreto. En esta página se describe cómo añadir una versión de un secreto.

Para obtener más información sobre las versiones, consulta este vídeo.

Roles obligatorios

Para obtener los permisos que necesitas para añadir una versión de un secreto, pide a tu administrador que te asigne los siguientes roles de IAM en un secreto:

Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

Los roles de gestión de identidades y accesos no se pueden conceder en una versión de un secreto.

Añadir una versión de secreto

Para añadir una versión secreta, 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, haga clic en la pestaña Regional secrets (Secretos regionales) y, a continuación, busque el secreto al que quiera añadir la nueva versión.

  3. Haz clic en el menú Acciones asociado a ese secreto y, a continuación, en Añadir nueva versión. Aparecerá el cuadro de diálogo Añadir nueva versión.

  4. En el campo Valor secreto, introduce un valor para el secreto, como abcd1234. También puedes subir un archivo que contenga el valor del secreto.

  5. Haz clic en Añadir nueva versión.

gcloud

Asegúrate de haber configurado Secret Manager para usar un endpoint regional para gestionar los secretos regionales.

Añadir una versión de secreto a partir del contenido de un archivo del disco

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
  • FILE_PATH: la ruta completa (incluido el nombre del archivo) del archivo que contiene los detalles de la versión

Ejecuta el siguiente comando:

Linux, macOS o Cloud Shell

gcloud secrets versions add SECRET_ID --location=LOCATION --data-file="FILE_PATH"

Windows (PowerShell)

gcloud secrets versions add SECRET_ID --location=LOCATION --data-file="FILE_PATH"

Windows (cmd.exe)

gcloud secrets versions add SECRET_ID --location=LOCATION --data-file="FILE_PATH"

La respuesta contiene la versión del secreto recién creada.

Añadir una versión de secreto directamente en la línea de comandos

También puedes añadir una versión secreta directamente en la línea de comandos, pero no es recomendable porque aparece como texto sin formato en la lista de procesos y otros usuarios del sistema pueden capturarla. Ten en cuenta que el comando con el texto sin cifrar también estará en el historial de tu shell.

  echo -n "SECRET_DATA" | \
      gcloud secrets versions add SECRET_ID --location=LOCATION --data-file=-

Haz los cambios siguientes:

  • SECRET_DATA: los datos que quieres almacenar en la versión del secreto
  • SECRET_ID: el ID del secreto o el identificador completo del secreto
  • LOCATION: la Google Cloud ubicación del secreto

Opcional: Añadir una versión a partir del contenido de un archivo al crear un secreto por primera vez

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
  • FILE_PATH: la ruta completa (incluido el nombre del archivo) del archivo que contiene los detalles de la versión

Ejecuta el siguiente comando:

Linux, macOS o Cloud Shell

gcloud secrets create SECRET_ID --location=LOCATION --data-file="FILE_PATH"

Windows (PowerShell)

gcloud secrets create SECRET_ID --location=LOCATION --data-file="FILE_PATH"

Windows (cmd.exe)

gcloud secrets create SECRET_ID --location=LOCATION --data-file="FILE_PATH"

La respuesta contiene la versión del secreto recién creada.

REST

Codifica en Base64 los datos secretos y guárdalos como una variable de shell.

$ SECRET_DATA=$(echo "seCr3t" | base64)

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:

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

Cuerpo JSON de la solicitud:

{"payload": {"data": "${SECRET_DATA}"}}

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 POST \
-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:addVersion"

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 POST `
-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:addVersion" | Select-Object -Expand Content

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

{
  "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID/versions/1",
  "createTime": "2024-03-25T08:24:13.153705Z",
  "state": "ENABLED",
  "etag": "\"161477e6071da9\""
}

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"
	"hash/crc32"
	"io"

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

// addSecretVersion adds a new secret version to the given secret with the
// provided payload.
func AddRegionalSecretVersion(w io.Writer, projectId, locationId, secretId string) error {
	// parent := "projects/my-project/locations/my-location/secrets/my-secret"

	// Declare the payload to store.
	payload := []byte("my super secret data")
	// Compute checksum, use Castagnoli polynomial. Providing a checksum
	// is optional.
	crc32c := crc32.MakeTable(crc32.Castagnoli)
	checksum := int64(crc32.Checksum(payload, crc32c))

	// 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.AddSecretVersionRequest{
		Parent: parent,
		Payload: &secretmanagerpb.SecretPayload{
			Data:       payload,
			DataCrc32C: &checksum,
		},
	}

	// Call the API.
	result, err := client.AddSecretVersion(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to add regional secret version: %w", err)
	}
	fmt.Fprintf(w, "Added regional secret version: %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.SecretManagerServiceClient;
import com.google.cloud.secretmanager.v1.SecretManagerServiceSettings;
import com.google.cloud.secretmanager.v1.SecretName;
import com.google.cloud.secretmanager.v1.SecretPayload;
import com.google.cloud.secretmanager.v1.SecretVersion;
import com.google.protobuf.ByteString;
import java.io.IOException;
import java.util.zip.CRC32C;
import java.util.zip.Checksum;

public class AddRegionalSecretVersion {

  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";
    addRegionalSecretVersion(projectId, locationId, secretId);
  }

  // Add a new version to the existing regional secret.
  public static SecretVersion addRegionalSecretVersion(
      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 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)) {
      SecretName secretName = 
          SecretName.ofProjectLocationSecretName(projectId, locationId, secretId);
      byte[] data = "my super secret data".getBytes();
      // Calculate data checksum. The library is available in Java 9+.
      // For Java 8, use:
      // https://cloud.google.com/appengine/docs/standard/java/javadoc/com/google/appengine/api/files/Crc32c
      Checksum checksum = new CRC32C();
      checksum.update(data, 0, data.length);

      // Create the secret payload.
      SecretPayload payload =
          SecretPayload.newBuilder()
              .setData(ByteString.copyFrom(data))
              // Providing data checksum is optional.
              .setDataCrc32C(checksum.getValue())
              .build();

      // Add the secret version.
      SecretVersion version = client.addSecretVersion(secretName, payload);
      System.out.printf("Added regional secret version %s\n", version.getName());

      return version;
    }
  }
}

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 = '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);

// Payload is the plaintext data to store in the secret
const payload = Buffer.from('my super secret data', 'utf8');

async function addRegionalSecretVersion() {
  const [version] = await client.addSecretVersion({
    parent: parent,
    payload: {
      data: payload,
    },
  });

  console.log(`Added regional secret version ${version.name}`);
}

addRegionalSecretVersion();

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.

from google.cloud import secretmanager_v1
import google_crc32c


def add_regional_secret_version(
    project_id: str,
    location_id: str,
    secret_id: str,
    payload: str,
) -> secretmanager_v1.SecretVersion:
    """
    Adds a new secret version to the given secret with the provided payload.
    """

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

    # Convert the string payload into a bytes. This step can be omitted if you
    # pass in bytes instead of a str for the payload argument.
    payload_bytes = payload.encode("UTF-8")

    # Calculate payload checksum. Passing a checksum in add-version request
    # is optional.
    crc32c = google_crc32c.Checksum()
    crc32c.update(payload_bytes)

    # Add the secret version.
    response = client.add_secret_version(
        request={
            "parent": parent,
            "payload": {
                "data": payload_bytes,
                "data_crc32c": int(crc32c.hexdigest(), 16),
            },
        }
    )

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

Estados de las versiones de secretos

Una versión de secreto puede tener uno de los siguientes estados en cualquier momento:

  • Habilitada: en este estado, se puede acceder a la versión del secreto y describirla. Este es el estado predeterminado de una versión de secreto nueva.

  • Inhabilitada: en este estado, no se puede acceder a la versión del secreto, pero el contenido del secreto sigue existiendo. La versión del secreto se puede volver a habilitar para restaurar el acceso.

  • Destruida: en este estado, se descarta el contenido de la versión del secreto. La versión del secreto no se puede cambiar a otro estado.

Se te factura tanto por las versiones de secretos habilitadas como por las inhabilitadas. No se te cobra por las versiones de secretos que estén en estado destruido.

Siguientes pasos