Agrega una versión regional del Secret

Los datos del Secret son inmutables y la mayoría de las operaciones se llevan a cabo en las versiones del Secret. Una versión de secreto contiene los datos reales del secreto, junto con el estado y los metadatos sobre el secreto. En esta página, se describe cómo agregar una versión de un secreto.

Para obtener más información sobre el control de versiones, mira este video sobre el tema.

Roles obligatorios

Para obtener los permisos que necesitas para agregar una versión de secreto, pídele a tu administrador que te otorgue los siguientes roles de IAM en un secreto:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.

No se pueden otorgar roles de IAM en una versión secreta.

Agrega una versión del Secret

Para agregar una versión secreta, usa uno de los siguientes métodos:

Console

  1. Ve a la página de Secret Manager en la consola de Google Cloud.

    Ir a Secret Manager

  2. En la página Secret Manager, haz clic en la pestaña Secretos regionales y, luego, busca el secreto para el que deseas agregar la versión nueva.

  3. Haz clic en el menú Acciones asociado con ese secreto y, luego, en Agregar versión nueva. Aparecerá el diálogo Add new version.

  4. En el campo Valor del secreto, ingresa un valor para el secreto, como abcd1234. Como alternativa, puedes subir un archivo que contenga el valor del Secret.

  5. Haz clic en Agregar versión nueva.

gcloud

Agrega una versión secreta del contenido de un archivo en el disco

Antes de usar cualquiera de los datos de comando a continuación, realiza los siguientes reemplazos:

  • SECRET_ID: El ID del Secret o el identificador completamente calificado del Secret
  • LOCATION: La ubicación de Google Cloud del secreto
  • FILE_PATH: Es la ruta de acceso completa (incluido el nombre del archivo) al 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.

Agrega una versión del Secret directamente en la línea de comandos

También puedes agregar una versión del secreto directamente en la línea de comandos, pero no es recomendable porque aparece como texto simple en la lista de procesos y otros usuarios del sistema pueden capturarlo. Ten en cuenta que el comando con el texto simple también estará en el historial de la shell.

Antes de usar cualquiera de los datos de comando a continuación, realiza los siguientes reemplazos:

  • SECRET_DATA: Son los datos que deseas almacenar en la versión del secreto.
  • SECRET_ID: El ID del Secret o el identificador completamente calificado del Secret
  • LOCATION: La ubicación de Google Cloud del secreto

Ejecuta el siguiente comando:

Linux, macOS o Cloud Shell

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

Windows (PowerShell)

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

Windows (cmd.exe)

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

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

Opcional: Agrega una versión del contenido de un archivo cuando creas un secreto por primera vez

Antes de usar cualquiera de los datos de comando a continuación, realiza los siguientes reemplazos:

  • SECRET_ID: El ID del Secret o el identificador completamente calificado del Secret
  • LOCATION: La ubicación de Google Cloud del secreto
  • FILE_PATH: Es la ruta de acceso completa (incluido el nombre del archivo) al 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 los datos secretos en Base64 y guárdalos como una variable de shell.

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

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • LOCATION: La ubicación de Google Cloud del secreto
  • PROJECT_ID: El ID del proyecto de Google Cloud
  • SECRET_ID: El ID del Secret o el identificador completamente calificado del Secret

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 que se muestra a continuación:

{
  "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 configura un entorno de desarrollo de Go e instala el SDK de Go para Secret Manager. En Compute Engine o GKE, debes autenticarte con el permiso 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 configura un entorno de desarrollo de Java e instala el SDK de Java para Secret Manager. En Compute Engine o GKE, debes autenticarte con el permiso 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 configura un entorno de desarrollo de Node.js e instala el SDK de Node.js para Secret Manager. En Compute Engine o GKE, debes autenticarte con el permiso 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 configura un entorno de desarrollo de Python e instala el SDK de Python para Secret Manager. En Compute Engine o GKE, debes autenticarte con el permiso 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 estar en uno de los siguientes estados en cualquier momento:

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

  • Inhabilitada: En este estado, no se puede acceder a la versión del Secret, pero el contenido del Secret aún existe. La versión del secreto se puede volver a habilitar para restablecer el acceso.

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

Se te factura por las versiones de secretos habilitadas y no habilitadas. No se te factura por las versiones de secretos que están en el estado destruido.

¿Qué sigue?