Configurare le notifiche per un segreto

Questa pagina spiega come configurare e utilizzare le notifiche relative agli eventi per i tuoi secret in Secret Manager.

Panoramica

Secret Manager si integra con Pub/Sub per fornire notifiche degli eventi per le modifiche apportate ai secret e alle versioni dei secret. Puoi utilizzare queste notifiche per avviare flussi di lavoro, ad esempio riavviare un'applicazione quando viene aggiunta una nuova versione del secret o inviare una notifica agli esperti di sicurezza quando un secret viene eliminato. Per saperne di più su come utilizzare queste notifiche per avviare i workflow, consulta la documentazione di Pub/Sub.

Come funzionano le notifiche degli eventi in Secret Manager

I secret possono essere configurati con un elenco di massimo 10 argomenti Pub/Sub. Ogni volta che viene eseguita un'operazione che modifica il secret o una delle sue versioni, Secret Manager pubblica automaticamente un messaggio in ciascuno degli argomenti Pub/Sub di quel secret. Le chiamate Get, List e Access non comportano la pubblicazione di messaggi.

I messaggi Pub/Sub hanno un insieme di coppie chiave-valore di attributi contenenti metadati sull'evento, nonché un campo data contenente una serializzazione JSON completa della risorsa Secret o SecretVersion creata o modificata. Questo JSON è una stringa codificata in UTF-8 che rappresenta la risorsa Secret o SecretVersion esattamente nella forma specificata dall'API pubblica Secret Manager, codificata in JSON come specificato nel mapping JSON proto3.

Tipi di evento

Di seguito è riportato un elenco dei tipi di eventi supportati da Secret Manager.

Formato delle notifiche

Le notifiche inviate all'argomento Pub/Sub sono composte da due parti:

• Attributi: un insieme di coppie chiave-valore che descrivono l'evento.

• Dati: una stringa che contiene i metadati dell'oggetto modificato.

Attributi

Gli attributi sono coppie chiave-valore contenute nelle notifiche inviate da Secret Manager al tuo argomento Pub/Sub. Tutte le notifiche, ad eccezione dei messaggi di test TOPIC_CONFIGURED, contengono sempre il seguente set di coppie chiave-valore, indipendentemente dai dati della notifica:

Inoltre, a volte le notifiche contengono il seguente insieme di coppie chiave-valore:

Dati

Il campo di dati è una stringa UTF-8 che contiene i metadati dell'oggetto modificato. I dati sono un secret o una versione del secret.

Per le notifiche SECRET_DELETE, i metadati contenuti nel campo dati rappresentano i metadati dell'oggetto così com'erano prima dell'eliminazione. Per tutte le altre notifiche, i metadati inclusi nel campo dati rappresentano i metadati dell'oggetto dopo la modifica.

Limitazioni

Le notifiche degli eventi sono disponibili solo nell'API Secret Manager v1 e nella Google Cloud CLI.

Prima di iniziare

Puoi scegliere di archiviare tutte le risorse nello stesso progetto o di archiviare i secret e gli argomenti Pub/Sub in progetti separati.

1. Per configurare Secret Manager:

   • Crea o utilizza un progetto esistente per contenere le risorse Secret Manager.

   • Se necessario, completa i passaggi descritti nella pagina Abilitare l'API Secret Manager.

2. Per configurare Pub/Sub, completa i seguenti passaggi:

   • Crea o utilizza un progetto esistente per contenere le risorse Pub/Sub.

   • Se necessario, abilita l'API Pub/Sub.

3. Autenticati su Google Cloud utilizzando questo comando:

       $ gcloud auth login --update-adc
       

Crea un'identità dell'agente di servizio

Per creare un'identità service agent per ogni progetto che richiede secret con notifiche di eventi:

1. Per creare un'identità di servizio con Google Cloud CLI, esegui questo comando:

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

   Questo comando restituisce un nome di account di servizio nel seguente formato:

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

2. Concedi a questo account di servizio l'autorizzazione a pubblicare negli argomenti Pub/Sub configurati nei tuoi secret.

3. Salva il nome del account di servizio come variabile di ambiente utilizzando il comando seguente:

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

Le variabili di ambiente per il progetto Secret Manager, il progetto Pub/Sub e il account di servizio Secret Manager devono essere impostate per tutto il tempo in cui segui questa procedura.

Crea argomenti Pub/Sub

Segui la guida rapida di Pub/Sub per creare argomenti nel tuo progetto Pub/Sub nella console Google Cloud . In alternativa, crea argomenti in Google Cloud CLI utilizzando il seguente 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"

Ripeti questa operazione più volte se vuoi creare più argomenti Pub/Sub nel secret.

Concedi al account di servizio per Secret Manager l'autorizzazione a pubblicare negli argomenti

Puoi concedere autorizzazioni al account di servizio Secret Manager tramite la console Google Cloud o tramite Google Cloud CLI.

Per concedere il ruolo Publisher Pub/Sub (roles/pubsub.publisher) nell'argomento Pub/Sub, utilizza il seguente 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 sottoscrizioni Pub/Sub

Per visualizzare i messaggi pubblicati in un argomento, devi anche creare una sottoscrizione all'argomento. Segui la guida rapida di Pub/Sub per creare sottoscrizioni nel tuo progetto Pub/Sub nella console Google Cloud . In alternativa, crea argomenti in Google Cloud CLI utilizzando questo 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 secret con gli argomenti configurati

Crea un secret con un elenco di massimo 10 argomenti configurati. Tutti gli argomenti configurati in un secret ricevono notifiche degli eventi quando il secret o una delle sue versioni cambia.

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

Aggiorna argomenti secret

Modifica gli argomenti Pub/Sub configurati in un secret aggiornando il secret con i nuovi nomi delle risorse degli argomenti Pub/Sub. Con Google Cloud CLI puoi aggiungere o rimuovere uno o più argomenti da un secret, nonché cancellare tutti gli argomenti dal secret.

Aggiungere argomenti

Per aggiungere uno o più argomenti a un secret, utilizza il seguente 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

Rimuovere gli argomenti

Per rimuovere uno o più argomenti da un secret, utilizza il seguente 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

Cancella argomenti

Per rimuovere tutti gli argomenti da un secret, utilizza questo 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

Utilizzare le notifiche di eventi con Cloud Run Functions

Le notifiche di eventi possono essere utilizzate per avviare flussi di lavoro creando funzioni Cloud Run per utilizzare i messaggi Pub/Sub. Per saperne di più, consulta la documentazione di Cloud Run Functions. Il seguente codice campione è per una funzione Cloud Run che stampa eventType, secretId e i metadati ogni volta che un evento viene pubblicato nell'argomento.

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

Per un elenco di tutti i tipi di eventi, consulta Tipi di eventi.

Argomenti configurati in modo errato

Se gli argomenti Pub/Sub vengono aggiunti a un secret in un'operazione di creazione o aggiornamento, ma Secret Manager non può pubblicare messaggi nell'argomento a causa di una configurazione errata, l'operazione non va a buon fine e viene visualizzato un messaggio di errore che indica il motivo per cui la pubblicazione non è riuscita. Ciò può accadere, ad esempio, se l'argomento non esiste o se il account di servizio Secret Manager non dispone dell'autorizzazione per la pubblicazione.

Se gli argomenti Pub/Sub vengono aggiunti a un secret e successivamente l'argomento viene modificato in modo che Secret Manager non possa più pubblicare messaggi (ad esempio, l'argomento viene eliminato o le autorizzazioni dell'account di servizio Secret Manager vengono rimosse), Secret Manager scrive log in Secret Manager Secret con un messaggio che indica il motivo per cui la pubblicazione non è riuscita.

Passaggi successivi

• Scopri come analizzare i secret con Cloud Asset Inventory.