Configurare le notifiche per un segreto

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

Panoramica

Secret Manager si integra con Pub/Sub per fornire notifiche degli eventi per le modifiche sia ai secret sia alle versioni dei secret. Puoi utilizzare queste notifiche per avviare flussi di lavoro, ad esempio per riavviare un'applicazione quando viene aggiunta una nuova versione del secret o per notificare agli addetti alla sicurezza l'eliminazione di un secret. Per ulteriori informazioni su come utilizzare queste notifiche per avviare i flussi di lavoro, consulta la documentazione di Pub/Sub.

Come funzionano le notifiche di eventi in Secret Manager

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

I messaggi Pub/Sub hanno un insieme di coppie chiave-valore dell'attributo 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 nel formato specificato dall'API pubblica Secret Manager, codificata in JSON come specificato nella mappatura JSON proto3.

Tipi di evento

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

Tipo di evento Descrizione
SECRET_CREATE Inviata quando un nuovo secret viene creato correttamente.
SECRET_UPDATE Inviata quando un nuovo secret viene aggiornato correttamente.
SECRET_DELETE Inviato quando un secret viene eliminato, a causa di una richiesta avviata dall'utente o della scadenza del secret.
SECRET_VERSION_ADD Inviata quando viene aggiunta una nuova versione del secret.
SECRET_VERSION_ENABLE Inviata quando viene abilitata una versione del secret.
SECRET_VERSION_DISABLE Inviata quando una versione del secret viene disattivata.
SECRET_VERSION_DESTROY Inviata quando una versione del secret viene eliminata.
SECRET_VERSION_DESTROY_SCHEDULED Inviata quando viene eseguita una distruzione la durata del ritardo è configurata sul secret e l'utente tenta di eliminare una versione del secret.
SECRET_ROTATE Inviata quando è il momento di ruotare una secret. Consulta: Per ulteriori informazioni, crea pianificazioni della rotazione.
TOPIC_CONFIGURED

Questo è un messaggio di prova senza corpo o attributi diversi da eventType: TOPIC_CONFIGURED. Viene inviato quando viene creato o aggiornato un secret con un elenco di argomenti Pub/Sub, ma non indica che l'operazione è andata a buon fine.

Se l'operazione è andata a buon fine, viene inviato immediatamente un messaggio SECRET_CREATE o SECRET_UPDATE.

Ogni volta che gli argomenti vengono aggiornati in un segreto, viene inviato un messaggio TOPIC_CONFIGURED a tutti gli argomenti del segreto, inclusi quelli già presenti.

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 contenente 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 diverse dai messaggi di test TOPIC_CONFIGURED contengono sempre il seguente insieme di coppie chiave:valore, indipendentemente dai dati della notifica:

Nome attributo Esempio Descrizione
eventType SECRET_CREATE Il tipo di evento che si è appena verificato. Vedi Tipi di evento per un elenco di possibili valori.
dataFormat JSON_API_V1 Il formato dei dati dell'oggetto.
secretId projects/p/secrets/my-secret Il nome completo della risorsa del secret in cui si è verificato l'evento.
timestamp 2021-01-20T11:17:45.081104-08:00 L'ora in cui si è verificato l'evento.

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

Nome dell'attributo Esempio Descrizione
versionId projects/p/secrets/my-secret/versions/456

Il nome della versione del secret in cui si è verificato l'evento.

Presente solo su SECRET_VERSION_ADD, SECRET_VERSION_ENABLE, SECRET_VERSION_DISABLE e Notifiche di eventi SECRET_VERSION_DESTROY.

deleteType REQUESTED Indica se l'eliminazione è stata richiesta da un utente (REQUESTED) o a causa della scadenza della chiave segreta (EXPIRATION). Presente solo nelle notifiche evento SECRET_DELETE.

Dati

Il campo 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 dei dati rappresentano i metadati dell'oggetto prima dell'eliminazione. Per tutte le altre notifiche, i metadati inclusi nei rappresenta i metadati dell'oggetto dopo la modifica.

Limitazioni

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

Prima di iniziare

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

  1. Per configurare Secret Manager:

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

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

  2. Per configurare Pub/Sub:

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

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

  3. Esegui l'autenticazione su Google Cloud utilizzando il seguente comando:

        $ gcloud auth login --update-adc

Crea un'identità dell'agente di servizio

Per creare un'identità di agente di servizio per ogni progetto che richiede segreti con notifiche di eventi:

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

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

    Questo comando restituisce il nome di un account di servizio con il 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 dell'account di servizio come variabile di ambiente utilizzando il seguente comando:

        # 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 l'account di servizio Secret Manager deve essere impostato per tutta la durata di 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 questo comando:

gcloud

Prima di utilizzare uno qualsiasi dei dati di comando riportati di seguito, effettua le seguenti sostituzioni:

  • PROJECT_ID: l'ID progetto Google Cloud che contiene il segreto
  • PUBSUB_PROJECT_ID: l'ID del progetto in cui creare abbonamenti
  • PUBSUB_TOPIC_NAME: il nome dell'argomento

Esegui la persone che seguo :

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"

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

Concedi all'account di servizio per Secret Manager l'autorizzazione di pubblicazione negli argomenti

Puoi concedere le autorizzazioni all'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) in Pub/Sub, utilizza il comando seguente:

gcloud

Prima di utilizzare uno qualsiasi dei dati di comando riportati di seguito, effettua le seguenti sostituzioni:

  • PUBSUB_TOPIC_NAME: il nome dell'argomento

Esegui la persone che seguo :

Linux, macOS o Cloud Shell

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

Windows (PowerShell)

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

Windows (cmd.exe)

gcloud pubsub topics create 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 introduttiva a Pub/Sub per creare sottoscrizioni nel tuo progetto Pub/Sub nella console Google Cloud. In alternativa, crea gli argomenti in Google Cloud CLI utilizzando il seguente comando:

gcloud

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • PUBSUB_PROJECT_ID: l'ID del progetto in cui creare abbonamenti
  • PUBSUB_SUBSCRIPTION_NAME: il nome dell'abbonamento
  • PUBSUB_TOPIC_NAME: il nome dell'argomento

Esegui la persone che seguo :

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

Crea un secret con 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 viene modificato.

gcloud

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • SECRET_ID: l'ID del secret o dell'identificatore completo del secret
  • PUBSUB_TOPIC_NAME: il nome dell'argomento
  • LOCATION: la località di Google Cloud del segreto

Esegui la persone che seguo :

Linux, macOS o Cloud Shell

gcloud secrets create SECRET_ID --topics PUBSUB_TOPIC_NAME --location=LOCATION

Windows (PowerShell)

gcloud secrets create SECRET_ID --topics PUBSUB_TOPIC_NAME --location=LOCATION

Windows (cmd.exe)

gcloud secrets create SECRET_ID --topics PUBSUB_TOPIC_NAME --location=LOCATION

Aggiorna gli argomenti dei secret

Modifica gli argomenti Pub/Sub configurati su un secret aggiornando il secret con nuovi nomi delle risorse dell'argomento Pub/Sub. Con Google Cloud CLI puoi aggiungere o rimuovere uno più argomenti da un segreto, oltre a cancellare tutti gli argomenti dal segreto.

Aggiungi argomenti

Per aggiungere uno o più argomenti a un secret, utilizza il seguente comando:

gcloud

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • SECRET_ID: l'ID del segreto o l'identificatore completo del segreto
  • LOCATION: la località Google Cloud del secret
  • PROJECT_ID: l'ID progetto Google Cloud che contiene il secret
  • PUBSUB_PROJECT_ID: l'ID del progetto in cui creare gli abbonamenti
  • PUBSUB_TOPIC_1_NAME e PUBSUB_TOPIC_2_NAME: i nomi degli argomenti che che stai aggiungendo al secret

Esegui il seguente comando:

Linux, macOS o Cloud Shell

gcloud secrets update SECRET_ID --location=LOCATION \
  --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 --location=LOCATION `
  --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 --location=LOCATION ^
  --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 segreto, utilizza il seguente comando:

gcloud

Prima di utilizzare uno qualsiasi dei dati di comando riportati di seguito, effettua le seguenti sostituzioni:

  • SECRET_ID: l'ID del secret o dell'identificatore completo del secret
  • LOCATION: la località di Google Cloud del segreto
  • PROJECT_ID: il progetto Google Cloud che contiene il segreto
  • PUBSUB_PROJECT_ID: l'ID del progetto in cui creare gli abbonamenti
  • PUBSUB_TOPIC_1_NAME e PUBSUB_TOPIC_2_NAME: i nomi degli argomenti che che stai rimuovendo dal secret

Esegui il seguente comando:

Linux, macOS o Cloud Shell

gcloud secrets update SECRET_ID --location=LOCATION \
  --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 --location=LOCATION `
  --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 --location=LOCATION ^
  --project PROJECT_ID ^
  --remove-topics "projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_1_NAME,projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_2__NAME

Argomenti chiari

Per rimuovere tutti gli argomenti da un secret, utilizza il seguente comando:

gcloud

Prima di utilizzare uno qualsiasi dei dati di comando riportati di seguito, effettua le seguenti sostituzioni:

  • SECRET_ID: l'ID del segreto o l'identificatore completo del segreto
  • PROJECT_ID: il progetto Google Cloud che contiene il secret
  • LOCATION: la località Google Cloud del secret

Esegui il seguente comando:

Linux, macOS o Cloud Shell

gcloud secrets update SECRET_ID --location=LOCATION \
  --project PROJECT_ID \
  --clear-topics

Windows (PowerShell)

gcloud secrets update SECRET_ID --location=LOCATION `
  --project PROJECT_ID `
  --clear-topics

Windows (cmd.exe)

gcloud secrets update SECRET_ID --location=LOCATION ^
  --project PROJECT_ID ^
  --clear-topics

Utilizza le notifiche di eventi con le funzioni di Cloud Run

Le notifiche di eventi possono essere utilizzate per avviare i flussi di lavoro creando funzioni Cloud Run per consumere i messaggi Pub/Sub. Consulta la documentazione sulle funzioni di Cloud Run per ulteriori informazioni. Il seguente codice di esempio è per una funzione Cloud Run che stampa eventType, secretId e i metadati ogni volta che viene pubblicato un evento nell'argomento.

C#

Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo C# e installare l'SDK C# di Secret Manager. Su Compute Engine o GKE, devi autenticarti con l'ambito 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

Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Go e installare l'SDK Go di Secret Manager. Su Compute Engine o GKE, devi autenticarti con l'ambito cloud-platform. 

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
}

Java

Per scoprire come installare e utilizzare la libreria client per Secret Manager, vedi Librerie client di Secret Manager.

Per eseguire l'autenticazione su Secret Manager, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale. 


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;
  }
}

Node.js

Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Node.js e installare l'SDK Node.js di Secret Manager. Su Compute Engine o GKE, devi autenticarti con l'ambito 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

Per eseguire questo codice, configura prima un ambiente di sviluppo Python e installare l'SDK per Python di Secret Manager. In Compute Engine o GKE, devi eseguire l'autenticazione con l'ambito cloud-platform. 

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

Ruby

Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Ruby e installare l'SDK Ruby di Secret Manager. Su Compute Engine o GKE, devi autenticarti con l'ambito 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

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

Argomenti con configurazione errata

Se gli argomenti Pub/Sub vengono aggiunti a un secret in un'operazione di creazione o aggiornamento, Secret Manager non può pubblicare messaggi nell'argomento a causa di una configurazione errata, l'operazione con un messaggio di errore che indica il motivo per cui la pubblicazione non è riuscita. Questo potrebbe accadere, ad esempio, se o se l'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 con un messaggio che indica il motivo dell'errore di pubblicazione.

Passaggi successivi