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 apportate sia ai secret sia 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 ingegneri della 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 con codifica 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.

Tipo di evento Descrizione
SECRET_CREATE Inviata quando viene creato un nuovo secret.
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 una nuova versione del secret viene aggiunta correttamente.
SECRET_VERSION_ENABLE Inviato quando viene attivata una versione del secret.
SECRET_VERSION_DISABLE Inviato quando una versione del secret viene disattivata.
SECRET_VERSION_DESTROY Inviato quando una versione del secret viene eliminata.
SECRET_VERSION_DESTROY_SCHEDULED Inviato quando viene configurata una durata del ritardo di eliminazione del secret e l'utente tenta di eliminare una versione del secret.
SECRET_ROTATE Inviato quando è il momento di ruotare un secret. Per saperne di più, consulta Creare pianificazioni della rotazione.
TOPIC_CONFIGURED

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

Un messaggio SECRET_CREATE o SECRET_UPDATE viene inviato immediatamente dopo se l'operazione è andata a buon fine.

Ogni volta che gli argomenti vengono aggiornati in un secret, viene inviato un messaggio TOPIC_CONFIGURED a tutti gli argomenti del secret, 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.

  • Data: 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:

Nome dell'attributo Esempio Descrizione
eventType SECRET_CREATE Il tipo di evento che si è appena verificato. Consulta Tipi di eventi per un elenco dei valori possibili.
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 secret in cui si è verificato l'evento.

Questo campo è presente solo nelle notifiche di eventi SECRET_VERSION_ADD, SECRET_VERSION_ENABLE, SECRET_VERSION_DISABLE e SECRET_VERSION_DESTROY.

deleteType REQUESTED Se l'eliminazione è stata richiesta da un utente (REQUESTED) o a causa della scadenza del segreto (EXPIRATION). Presente solo nelle notifiche degli eventi 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 dati rappresentano i metadati dell'oggetto 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 in Google Cloud CLI.

  • Non puoi utilizzare in modo affidabile le notifiche di eventi con argomenti Pub/Sub che hanno una policy di archiviazione dei messaggi in cui enforceInTransit è impostato su true.

    Secret Manager pubblica tutte le notifiche di eventi da un endpoint globale. Se un argomento Pub/Sub ha enforceInTransit impostato su true, la pubblicazione è limitata a allowedPersistenceRegions specifici. La limitazione regionale è in conflitto con l'endpoint di pubblicazione globale per Secret Manager, causando l'esito negativo della richiesta di pubblicazione con un errore FAILED_PRECONDITION.

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 il seguente 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 il seguente comando:

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