En esta página se explica cómo configurar y usar las notificaciones de eventos de tus secretos en Secret Manager.
Información general
Secret Manager se integra con Pub/Sub para proporcionar notificaciones de eventos sobre los cambios en los secretos y en las versiones de secretos. Puedes usar estas notificaciones para iniciar flujos de trabajo, como reiniciar una aplicación cuando se añade una nueva versión de un secreto o notificar a los ingenieros de seguridad cuando se elimina un secreto. Para obtener más información sobre cómo usar estas notificaciones para 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 Get
, List
y Access
no dan lugar a 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 ha creado o modificado. Este JSON es una cadena codificada en UTF-8 que representa el recurso Secret
o SecretVersion
exactamente en el formato especificado por la API pública de Secret Manager, codificado en JSON tal como se indica en proto3 JSON Mapping.
Tipos de eventos
A continuación se muestra una lista de los tipos de eventos admitidos por Secret Manager.
Tipo de evento | Descripción |
---|---|
SECRET_CREATE |
Se envía cuando se crea un secreto correctamente. |
SECRET_UPDATE |
Se envía cuando se actualiza correctamente un nuevo secreto. |
SECRET_DELETE |
Se envía cuando se elimina un secreto, ya sea por una solicitud iniciada por el usuario o porque ha caducado. |
SECRET_VERSION_ADD |
Se envía cuando se añade correctamente una nueva versión de secreto. |
SECRET_VERSION_ENABLE |
Se envía cuando se habilita una versión de secreto. |
SECRET_VERSION_DISABLE |
Se envía cuando se inhabilita una versión de un secreto. |
SECRET_VERSION_DESTROY |
Se envía cuando se destruye una versión de un secreto. |
SECRET_VERSION_DESTROY_SCHEDULED |
Se envía cuando se configura una duración del retraso de la destrucción en el secreto y el usuario intenta destruir una versión del secreto. |
SECRET_ROTATE |
Se envía cuando es el momento de rotar un secreto. Consulta más información en el artículo Crear programaciones de rotación. |
TOPIC_CONFIGURED |
Este es un mensaje de prueba sin cuerpo ni atributos que no sean Si la operación se ha realizado correctamente, se envía un mensaje Cada vez que se actualizan los temas de un secreto, se envía un mensaje de |
Formato de las notificaciones
Las notificaciones enviadas al tema de Pub/Sub constan de dos partes:
-
Atributos: un conjunto de pares clave-valor que describen el evento.
-
Datos: cadena 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, excepto los mensajes de prueba de TOPIC_CONFIGURED
, siempre contienen el siguiente conjunto de pares clave-valor, independientemente de los datos de la notificación:
Ejemplo | Descripción | |
---|---|---|
eventType |
SECRET_CREATE |
El tipo de evento que acaba de producirse Consulta la lista de valores posibles en Tipos de eventos. |
dataFormat |
JSON_API_V1 |
El formato de los datos del objeto. |
secretId |
projects/p/secrets/my-secret |
Nombre completo del recurso del secreto en el que se ha producido el evento. |
timestamp |
2021-01-20T11:17:45.081104-08:00 |
La hora a la que se produjo el evento. |
Además, las notificaciones a veces contienen el siguiente conjunto de pares clave-valor:
Ejemplo | Descripción | |
---|---|---|
versionId |
projects/p/secrets/my-secret/versions/456 |
Nombre de la versión del secreto en la que se ha producido el evento.
Solo está presente en las notificaciones de eventos |
deleteType |
REQUESTED |
Indica si un usuario ha solicitado la eliminación (REQUESTED )
o si se ha debido a la caducidad de un secreto (EXPIRATION ). Solo se incluye en las notificaciones de eventos SECRET_DELETE .
|
Datos
El campo de datos es una cadena UTF-8 que contiene los metadatos del objeto modificado. Los datos son un secreto o una versión de un secreto.
En el caso de las notificaciones SECRET_DELETE
, los metadatos incluidos en el campo de datos representan los metadatos del objeto tal como estaban antes de la eliminación. En el resto de las notificaciones, los metadatos incluidos en el campo de datos representan los metadatos del objeto después de que se produzca el cambio.
Limitaciones
Las notificaciones de eventos solo están disponibles en la API Secret Manager v1 y en la CLI de Google Cloud.
Antes de empezar
Puedes almacenar todos los recursos en el mismo proyecto o almacenar los secretos y los temas de Pub/Sub en proyectos independientes.
-
Para configurar Secret Manager, haz lo siguiente:
-
Crea un proyecto o usa uno ya creado para alojar tus recursos de Secret Manager.
-
Si es necesario, completa los pasos que se mencionan en la página Habilitar la API Secret Manager.
-
-
Para configurar Pub/Sub, haz lo siguiente:
-
Crea un proyecto o usa uno ya creado para alojar tus recursos de Pub/Sub.
-
Si es necesario, habilita la API Pub/Sub.
-
-
Autentícate en Google Cloud con el siguiente comando:
$ gcloud auth login --update-adc
Crear 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:
-
Para crear una identidad de servicio con la CLI de Google Cloud, ejecuta el siguiente comando:
$ gcloud beta services identity create \ --service "secretmanager.googleapis.com" \ --project "PROJECT_ID"
Este comando devuelve el nombre de una cuenta de servicio con el siguiente formato:
service-PROJECT_NUMBER@gcp-sa-secretmanager.iam.gserviceaccount.com
-
Concede a esta cuenta de servicio permiso para publicar en los temas de Pub/Sub configurados en tus secretos.
-
Guarda el nombre de la cuenta de servicio como 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, del proyecto de Pub/Sub y de la cuenta de servicio de Secret Manager deben estar definidas durante todo el procedimiento.
Crear 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 . También puedes crear temas en la CLI de Google Cloud con el siguiente comando:
gcloud
Antes de usar los datos de los comandos que se indican a continuación, haz los siguientes cambios:
- PUBSUB_PROJECT_ID: el ID del proyecto en el que se crearán las suscripciones.
- PUBSUB_TOPIC_NAME: el nombre del tema
Ejecuta el siguiente comando:
Linux, macOS o Cloud Shell
gcloud pubsub topics create "projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME"
Windows (PowerShell)
gcloud pubsub topics create "projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME"
Windows (cmd.exe)
gcloud pubsub topics create "projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME"
Repite este paso varias veces si quieres crear varios temas de Pub/Sub en el secreto.
Concede a la cuenta de servicio de Secret Manager permiso para publicar en los temas
Puedes conceder permisos a la cuenta de servicio de Secret Manager a través de la Google Cloud consola o de la CLI de Google Cloud.
Para asignar el rol Editor de Pub/Sub (roles/pubsub.publisher
) en el tema de Pub/Sub, usa el siguiente comando:
gcloud
Antes de usar los datos de los comandos que se indican a continuación, haz los siguientes cambios:
- PUBSUB_TOPIC_NAME: el nombre del tema
Ejecuta el siguiente comando:
Linux, macOS o Cloud Shell
gcloud pubsub topics add-iam-policy-binding PUBSUB_TOPIC_NAME \ --member "serviceAccount:${SM_SERVICE_ACCOUNT}" \ --role "roles/pubsub.publisher"
Windows (PowerShell)
gcloud pubsub topics add-iam-policy-binding PUBSUB_TOPIC_NAME ` --member "serviceAccount:${SM_SERVICE_ACCOUNT}" ` --role "roles/pubsub.publisher"
Windows (cmd.exe)
gcloud pubsub topics add-iam-policy-binding PUBSUB_TOPIC_NAME ^ --member "serviceAccount:${SM_SERVICE_ACCOUNT}" ^ --role "roles/pubsub.publisher"
Crear suscripciones de 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 Google Cloud consola. También puedes crear temas en la CLI de Google Cloud con el siguiente comando:
gcloud
Antes de usar los datos de los comandos que se indican a continuación, haz los siguientes cambios:
- PUBSUB_PROJECT_ID: el ID del proyecto en el que se crearán las suscripciones.
- PUBSUB_SUBSCRIPTION_NAME: el nombre de la suscripción
- PUBSUB_TOPIC_NAME: el nombre del tema
Ejecuta el siguiente comando:
Linux, macOS o Cloud Shell
gcloud pubsub subscriptions create projects/PUBSUB_PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_NAME \ --topic projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME
Windows (PowerShell)
gcloud pubsub subscriptions create projects/PUBSUB_PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_NAME ` --topic projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME
Windows (cmd.exe)
gcloud pubsub subscriptions create projects/PUBSUB_PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_NAME ^ --topic projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME
Crear 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 el secreto o una de sus versiones cambia.
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 o el identificador completo del secreto
- PUBSUB_TOPIC_NAME: el nombre del tema
Ejecuta el siguiente comando:
Linux, macOS o Cloud Shell
gcloud secrets create SECRET_ID --topics PUBSUB_TOPIC_NAME
Windows (PowerShell)
gcloud secrets create SECRET_ID --topics PUBSUB_TOPIC_NAME
Windows (cmd.exe)
gcloud secrets create SECRET_ID --topics PUBSUB_TOPIC_NAME
REST
Antes de usar los datos de la solicitud, haz las siguientes sustituciones:
- PROJECT_ID: el ID del proyecto Google Cloud
- SECRET_ID: el ID del secreto o el identificador completo del secreto
- TOPIC_NAME: el nombre del tema
Método HTTP y URL:
POST https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets?secretId=SECRET_ID
Cuerpo JSON de la solicitud:
{ "replication":{ "automatic":{} }, "topics":{ "name": "TOPIC_NAME" } }
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.googleapis.com/v1/projects/PROJECT_ID/secrets?secretId=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 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
Deberías recibir una respuesta JSON similar a la siguiente:
{ "name": "/projects/my-project/locations/me-central2/secrets/my-drz-secret", "createTime": "2024-03-25T08:24:13.153705Z", "etag": "\"161477e6071da9\"" }
Actualizar temas secretos
Modifica los temas de Pub/Sub configurados en un secreto actualizando el secreto con los nuevos nombres de recursos de temas de Pub/Sub. Con la CLI de Google Cloud, puedes añadir o quitar uno o varios temas de un secreto, así como eliminar todos los temas del secreto.
Añadir temas
Para añadir uno o varios temas a un secreto, usa el siguiente comando:
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 o el identificador completo del secreto
- PROJECT_ID: el ID del proyecto Google Cloud que contiene el secreto
- PUBSUB_PROJECT_ID: el ID del proyecto en el que se crearán las suscripciones.
- PUBSUB_TOPIC_1_NAME y PUBSUB_TOPIC_2_NAME: los nombres de los temas que vas a añadir al secreto
Ejecuta el siguiente comando:
Linux, macOS o Cloud Shell
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
Windows (PowerShell)
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
Windows (cmd.exe)
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 eliminar uno o varios temas de un secreto, usa el siguiente comando:
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 o el identificador completo del secreto
- PROJECT_ID: el Google Cloud proyecto que contiene el secreto
- PUBSUB_PROJECT_ID: el ID del proyecto en el que se crearán las suscripciones.
- PUBSUB_TOPIC_1_NAME y PUBSUB_TOPIC_2_NAME: los nombres de los temas que quieres quitar del secreto
Ejecuta el siguiente comando:
Linux, macOS o Cloud Shell
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
Windows (PowerShell)
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
Windows (cmd.exe)
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
Borrar temas
Para eliminar todos los temas de un secreto, usa el siguiente comando:
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 o el identificador completo del secreto
- PROJECT_ID: el Google Cloud proyecto que contiene el secreto
Ejecuta el siguiente comando:
Linux, macOS o Cloud Shell
gcloud secrets update SECRET_ID \ --project PROJECT_ID \ --clear-topics
Windows (PowerShell)
gcloud secrets update SECRET_ID ` --project PROJECT_ID ` --clear-topics
Windows (cmd.exe)
gcloud secrets update SECRET_ID ^ --project PROJECT_ID ^ --clear-topics
Consumir notificaciones de eventos con Cloud Run Functions
Las notificaciones de eventos se pueden usar para iniciar flujos de trabajo creando funciones de Cloud Run que consuman los mensajes de Pub/Sub. Para obtener más información, consulta la documentación de Cloud Run Functions. El siguiente código de ejemplo es para una función de Cloud Run que imprime eventType
, secretId
y metadatos cada vez que se publica un evento en el tema.
C#
Para ejecutar este código, primero debes configurar un entorno de desarrollo de C# e instalar el SDK de C# de Secret Manager. En Compute Engine o GKE, debes autenticarte con el ámbito cloud-platform.
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; } } }
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.
Java
Para saber cómo instalar y usar la biblioteca de cliente de Secret Manager, consulta el artículo Bibliotecas de cliente de Secret Manager.
Para autenticarte en Secret Manager, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local.
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.
/** * 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}.`); };
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.
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 "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 ver una lista de todos los tipos de eventos, consulta Tipos de eventos.
Temas mal configurados
Si se añaden temas de Pub/Sub 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 un error de configuración, la operación falla y se muestra un mensaje de error que indica por qué no se ha podido publicar. Esto puede ocurrir, por ejemplo, si el tema no existe o si la cuenta de servicio de Secret Manager no tiene permiso para publicar.
Si se añaden temas de Pub/Sub a un secreto y, después, se cambia el tema de forma que Secret Manager ya no pueda publicar mensajes (por ejemplo, si se elimina el tema o se quitan los permisos de la cuenta de servicio de Secret Manager), Secret Manager escribe registros en el Secret
de Secret Manager con un mensaje que indica por qué no se ha podido publicar.
Siguientes pasos
- Consulta cómo analizar secretos con Inventario de Recursos de Cloud.