Cómo configurar notificaciones en un secreto

En esta página, se explica cómo configurar y usar las notificaciones de eventos para tus secretos en Secret Manager.

Descripción general

Secret Manager se integra en Pub/Sub para proporcionar notificaciones de eventos sobre los cambios en los secretos y las versiones de los secretos. Puedes usar estas notificaciones para iniciar flujos de trabajo, como reiniciar una aplicación cuando se agrega una nueva versión de un secreto o notificar a los ingenieros de seguridad cuando se borra un secreto. Si deseas obtener más información para usar estas notificaciones a fin de iniciar flujos de trabajo, consulta la documentación de Pub/Sub.

Cómo funcionan las notificaciones de eventos en Secret Manager

Los secretos se pueden configurar con una lista de hasta 10 temas de Pub/Sub. Cada vez que se realiza una operación que modifica el secreto o una de sus versiones, Secret Manager publica automáticamente un mensaje en cada uno de los temas de Pub/Sub de ese secreto. Las llamadas a Get, List y Access no dan como resultado publicaciones de mensajes.

Los mensajes de Pub/Sub tienen un conjunto de pares clave-valor de atributos que contienen metadatos sobre el evento, así como un campo data que contiene una serialización JSON completa del recurso Secret o SecretVersion que se creó o modificó. Este JSON es una cadena codificada en UTF-8 que representa el recurso Secret o SecretVersion exactamente en la forma especificada por la API pública de Secret Manager, codificado en JSON como se especifica en la Asignación de JSON de proto3.

Tipos de eventos

La siguiente es una lista de los tipos de eventos que admite Secret Manager.

Formato de las notificaciones

Las notificaciones que se envían al tema de Pub/Sub constan de dos partes:

• Atributos: Son un conjunto de pares clave-valor que describen el evento.

• Carga útil: Una string que contiene los metadatos del objeto modificado

Atributos

Los atributos son pares clave-valor incluidos en las notificaciones que envía Secret Manager a tu tema de Pub/Sub. Todas las notificaciones que no sean mensajes de prueba de TOPIC_CONFIGURED siempre contienen el siguiente conjunto de pares clave-valor, sin importar los datos de la notificación:

Además, las notificaciones a veces contienen el siguiente conjunto de pares clave-valor:

Datos

El campo de datos es una string UTF-8 que contiene los metadatos del objeto modificado. Los datos pueden ser un secreto o una versión del secreto.

Para las notificaciones SECRET_DELETE, los metadatos que contiene el campo de datos representan los metadatos del objeto como estaban antes de la eliminación. Para todas las demás notificaciones, los metadatos incluidos en el campo de datos representan los metadatos del objeto después de la modificación.

Limitaciones

Las notificaciones de eventos solo están disponibles en la API de v1 de Secret Manager y en Google Cloud CLI.

Antes de comenzar

Puedes elegir almacenar todos los recursos en el mismo proyecto o almacenar secretos y temas de Pub/Sub en proyectos separados.

1. Para configurar Secret Manager, completa los siguientes pasos:

   • Crea o usa un proyecto existente para guardar tus recursos de Secret Manager.

   • Si es necesario, completa los pasos que se mencionan en la página Habilita la API de Secret Manager.

2. Para configurar Pub/Sub, completa los siguientes pasos:

   • Crea o usa un proyecto existente para guardar tus recursos de Pub/Sub.

   • Si es necesario, habilita la API de Pub/Sub.

3. Realiza la autenticación en Google Cloud con el siguiente comando:

       $ gcloud auth login --update-adc
       

Crea una identidad de agente de servicio

Para crear una identidad de agente de servicio para cada proyecto que requiera secretos con notificaciones de eventos, sigue estos pasos:

1. Para crear una identidad de servicio con Google Cloud CLI, ejecuta el siguiente comando:

         $ gcloud beta services identity create \
             --service "secretmanager.googleapis.com" \
             --project "PROJECT_ID"
       

   Este comando devuelve un nombre de cuenta de servicio con el siguiente formato:

       service-PROJECT_ID@gcp-sa-secretmanager.iam.gserviceaccount.com
       

2. Otorga a esta cuenta de servicio permiso para publicar en los temas de Pub/Sub configurados en tus secretos.

3. Guarda el nombre de la cuenta de servicio como una variable de entorno con el siguiente comando:

       # This is from the output of the command above
       $ export SM_SERVICE_ACCOUNT="service-...."
       

Las variables de entorno del proyecto de Secret Manager, el proyecto de Pub/Sub y la cuenta de servicio de Secret Manager deben configurarse todo el tiempo que sigas este procedimiento.

Crea temas de Pub/Sub

Sigue la guía de inicio rápido de Pub/Sub para crear temas en tu proyecto de Pub/Sub en la consola de Google Cloud . Como alternativa, crea temas en Google Cloud CLI con el siguiente comando:

gcloud pubsub topics create "projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME"

gcloud pubsub topics create "projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME"

gcloud pubsub topics create "projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME"

Repite esto varias veces si deseas crear varios temas de Pub/Sub en el secreto.

Otorga a la cuenta de servicio para que Secret Manager pueda publicar en los temas.

Puedes otorgar permisos a la cuenta de servicio de Secret Manager a través de la consola de Google Cloud o de Google Cloud CLI.

Para otorgar el rol de publicador de Pub/Sub (roles/pubsub.publisher) en el tema de Pub/Sub, usa el siguiente comando:

gcloud pubsub topics add-iam-policy-binding PUBSUB_TOPIC_NAME \
    --member "serviceAccount:${SM_SERVICE_ACCOUNT}" \
    --role "roles/pubsub.publisher"

gcloud pubsub topics add-iam-policy-binding PUBSUB_TOPIC_NAME `
    --member "serviceAccount:${SM_SERVICE_ACCOUNT}" `
    --role "roles/pubsub.publisher"

gcloud pubsub topics add-iam-policy-binding PUBSUB_TOPIC_NAME ^
    --member "serviceAccount:${SM_SERVICE_ACCOUNT}" ^
    --role "roles/pubsub.publisher"

Crea suscripciones a Pub/Sub

Para ver los mensajes publicados en un tema, también debes crear una suscripción al tema. Sigue la guía de inicio rápido de Pub/Sub para crear suscripciones en tu proyecto de Pub/Sub en la consola de Google Cloud . Como alternativa, crea temas en Google Cloud CLI con el siguiente comando:

gcloud pubsub subscriptions create projects/PUBSUB_PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_NAME \
  --topic projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME

gcloud pubsub subscriptions create projects/PUBSUB_PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_NAME `
  --topic projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME

gcloud pubsub subscriptions create projects/PUBSUB_PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_NAME ^
  --topic projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME

Crea un secreto con temas configurados

Crea un secreto con una lista de hasta 10 temas configurados. Todos los temas configurados en un secreto reciben notificaciones de eventos cuando se modifica el secreto o una de sus versiones.

gcloud secrets create SECRET_ID --topics PUBSUB_TOPIC_NAME

gcloud secrets create SECRET_ID --topics PUBSUB_TOPIC_NAME

gcloud secrets create SECRET_ID --topics PUBSUB_TOPIC_NAME

POST https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets?secretId=SECRET_ID

{
  "replication":{
    "automatic":{}
  },
  "topics":{
    "name": "TOPIC_NAME"
  }
}

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

$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.googleapis.com/v1/projects/PROJECT_ID/secrets?secretId=SECRET_ID" | Select-Object -Expand Content

{
  "name": "/projects/my-project/locations/me-central2/secrets/my-drz-secret",
  "createTime": "2024-03-25T08:24:13.153705Z",
  "etag": "\"161477e6071da9\""
}

Actualiza temas de secreto

Modifica los temas de Pub/Sub configurados en un secreto actualizando el secreto con los nombres de los recursos del tema de Pub/Sub nuevos. Con Google Cloud CLI, puedes agregar o quitar uno o más temas de un secreto, así como borrar todos los temas del secreto.

Agregar temas

Para agregar uno o más temas a un secreto, usa el siguiente comando:

gcloud secrets update SECRET_ID \
  --project PROJECT_ID \
  --add-topics projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_1_NAME,projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_2_NAME

gcloud secrets update SECRET_ID `
  --project PROJECT_ID `
  --add-topics projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_1_NAME,projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_2_NAME

gcloud secrets update SECRET_ID ^
  --project PROJECT_ID ^
  --add-topics projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_1_NAME,projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_2_NAME

Quitar temas

Para quitar uno o más temas de un secreto, usa el siguiente comando:

gcloud secrets update SECRET_ID \
  --project PROJECT_ID \
  --remove-topics projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_1_NAME,projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_2_NAME

gcloud secrets update SECRET_ID `
  --project PROJECT_ID `
  --remove-topics projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_1_NAME,projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_2_NAME

gcloud secrets update SECRET_ID ^
  --project PROJECT_ID ^
  --remove-topics projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_1_NAME,projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_2_NAME

Borra temas

Para quitar todos los temas de un secreto, usa el siguiente comando:

gcloud secrets update SECRET_ID \
  --project PROJECT_ID \
  --clear-topics

gcloud secrets update SECRET_ID `
  --project PROJECT_ID `
  --clear-topics

gcloud secrets update SECRET_ID ^
  --project PROJECT_ID ^
  --clear-topics

Consume notificaciones de eventos con Cloud Run Functions

Las notificaciones de eventos se pueden usar para iniciar flujos de trabajo creando Cloud Run Functions que consuman los mensajes de Pub/Sub. Consulta la documentación de Cloud Run Functions para obtener más información. El siguiente código de muestra corresponde a una función de Cloud Run que imprime eventType, secretId y metadatos cada vez que se publica un evento en el tema.

using CloudNative.CloudEvents;
using Google.Cloud.Functions.Framework;
using Google.Events.Protobuf.Cloud.PubSub.V1;
using System;
using System.Threading;
using System.Threading.Tasks;

// Triggered from a message on a Cloud Pub/Sub topic.
// The printed value will be visible in Cloud Logging
// (https://cloud.google.com/functions/docs/monitoring/logging).
namespace PubSubSample
{
    public class Function : ICloudEventFunction<MessagePublishedData>
    {
        public Task HandleAsync(CloudEvent cloudEvent, MessagePublishedData data, CancellationToken cancellationToken)
        {
          string eventType = data.Message.Attributes["eventType"];
          string secretId = data.Message.Attributes["secretId"];
          string secretMetadata = data.Message.TextData;
          Console.WriteLine($"Received {eventType} for {secretId}. New metadata: {secretMetadata}.");
          return Task.CompletedTask;
        }
    }
}

import (
	"context"
	"fmt"
)

// PubSubMessage is the payload of a Pub/Sub event.
type PubSubMessage struct {
	Attributes PubSubAttributes `json:"attributes"`
	Data       []byte           `json:"data"`
}

// PubSubAttributes are attributes from the Pub/Sub event.
type PubSubAttributes struct {
	SecretId  string `json:"secretId"`
	EventType string `json:"eventType"`
}

// ConsumeEventNotification demonstrates how to consume and process the Pub/Sub
// notification from Secret Manager.
func ConsumeEventNotification(ctx context.Context, m PubSubMessage) (string, error) {
	// The printed value will be visible in Cloud Logging:
	//
	//     https://cloud.google.com/functions/docs/monitoring/logging
	//
	eventType := m.Attributes.EventType
	secretID := m.Attributes.SecretId
	data := m.Data

	return fmt.Sprintf("Received %s for %s. New metadata: %q.",
		eventType, secretID, data), nil
}

import java.util.Base64;
import java.util.Map;
import java.util.logging.Logger;
import lombok.Data;

// Demonstrates how to consume and process a Pub/Sub notification from Secret Manager. Triggered
// by a message on a Cloud Pub/Sub topic.
// Ideally the class should implement a background function that accepts a Pub/Sub message.
// public class ConsumeEventNotification implements BackgroundFunction<PubSubMessage> { }
public class ConsumeEventNotification {

  // You can configure the logs to print the message in Cloud Logging.
  private static final Logger logger = Logger.getLogger(ConsumeEventNotification.class.getName());

  // Accepts a message from a Pub/Sub topic and writes it to logger.
  public static String accept(PubSubMessage message) {
    String eventType = message.attributes.get("eventType");
    String secretId = message.attributes.get("secretId");
    String data = new String(Base64.getDecoder().decode(message.data));
    String log = String.format("Received %s for %s. New metadata: %s", eventType, secretId, data);
    logger.info(log);
    return log;
  }

  // Event payload. Mock of the actual Pub/Sub message.
  @Data
  public static class PubSubMessage {

    byte[] data;
    Map<String, String> attributes;
    String messageId;
    String publishTime;
    String orderingKey;
  }
}

/**
* Triggered from a message on a Cloud Pub/Sub topic.
* The printed value will be visible in Cloud Logging
* (https://cloud.google.com/functions/docs/monitoring/logging).
*
* @param {!Object} event Event payload.
* @param {!Object} context Metadata for the event.
*/
exports.smEventsFunction = (event, context) => {
  const eventType = event.attributes.eventType;
  const secretID = event.attributes.secretId;
  const secretMetadata = Buffer.from(event.data, 'base64').toString();
  console.log(`Received ${eventType} for ${secretID}. New metadata: ${secretMetadata}.`);
};

import base64


def consume_event_notification(event: dict, unused_context: None) -> str:
    """
    consume_event_notification demonstrates how to consume and process a
    Pub/Sub notification from Secret Manager.
    Args:
          event (dict): Event payload.
          unused_context (google.cloud.functions.Context): Metadata for the event.
    """
    event_type = event["attributes"]["eventType"]
    secret_id = event["attributes"]["secretId"]
    secret_metadata = base64.b64decode(event["data"]).decode("utf-8")
    event_notification = (
        f"Received {event_type} for {secret_id}. New metadata: {secret_metadata}"
    )
    print(event_notification)
    return event_notification

require "functions_framework"
require "base64"

# Triggered from a message on a Cloud Pub/Sub topic.
# The printed value will be visible in Cloud Logging
# (https://cloud.google.com/functions/docs/monitoring/logging).
FunctionsFramework.cloud_event "sm_events_function" do |event|
  message = event.data["message"]
  event_type = message["attributes"]["eventType"]
  secret_id = message["attributes"]["secretId"]
  message_data = Base64.decode64 message["data"]
  FunctionsFramework.logger.info "Received %s for %s. New metadata: %s." % [event_type, secret_id, message_data]
end

Para obtener una lista de todos los tipos de eventos, consulta Tipos de eventos.

Temas mal configurados

Si los temas de Pub/Sub se agregan a un secreto en una operación de creación o actualización, pero Secret Manager no puede publicar mensajes en el tema debido a una configuración incorrecta, la operación falla y muestra un mensaje de error que indica por qué falló la publicación. Esto podría suceder, por ejemplo, si el tema no existe o si la cuenta de servicio de Secret Manager no tiene permiso para publicar.

Si se agregan temas de Pub/Sub a un secreto y, luego, se cambia el tema de modo que Secret Manager ya no pueda publicar mensajes (por ejemplo, se borra el tema o se quitan los permisos de la cuenta de servicio de Secret Manager), Secret Manager escribe registros en Secret de Secret Manager con un mensaje que indica por qué falló la publicación.

¿Qué sigue?

• Aprende a analizar secretos con Cloud Asset Inventory.