In questo argomento viene illustrato il supporto delle notifiche degli eventi in Secret Manager.
Panoramica
Le notifiche degli eventi inviano le informazioni sulle modifiche ai secret e alle versioni dei secret a Pub/Sub. Queste notifiche possono essere utilizzate per attivare flussi di lavoro arbitrari, come il riavvio di un'applicazione quando viene aggiunta una nuova versione del secret o la notifica ai tecnici della sicurezza quando viene eliminato un secret. Per ulteriori informazioni su come utilizzare queste notifiche per attivare flussi di lavoro, 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 pubblicherà automaticamente un messaggio in ciascuno degli argomenti Pub/Sub su quel secret. Le chiamate Get, List e Access non portano alla pubblicazione di messaggi.
I messaggi Pub/Sub hanno un insieme di coppie chiave-valore "attribute" contenenti metadati sull'evento, nonché un campo "data" contenente una serializzazione JSON completa della risorsa Secret o SecretVersion che è stata creata o modificata. Questo JSON è una stringa con codifica UTF-8 che rappresenta la risorsa Secret o SecretVersion esattamente nel formato specificato dall'API pubblica di 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 |
Inviato quando viene creato un nuovo secret. |
SECRET_UPDATE |
Inviato 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 |
Inviato quando viene aggiunta correttamente una nuova versione del secret. |
SECRET_VERSION_ENABLE |
Inviata quando è abilitata una versione del secret. |
SECRET_VERSION_DISABLE |
Inviata quando una versione del secret è disabilitata. |
SECRET_VERSION_DESTROY |
Inviato quando viene eliminata una versione del secret. |
SECRET_VERSION_DESTROY_SCHEDULED |
Inviato quando nel secret è configurata una durata del ritardo di distruzione 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 Creazione e gestione dei criteri di rotazione sui secret. |
TOPIC_CONFIGURED |
Questo è un messaggio di prova senza corpo o attributi diversi da
Se l'operazione è riuscita, verrà inviato un messaggio
Ogni volta che gli argomenti vengono aggiornati su un secret, viene inviato un messaggio |
Formato delle notifiche
Le notifiche inviate all'argomento Pub/Sub sono composte da due parti:
- Attributi: un set 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 tranne i messaggi di test TOPIC_CONFIGURED
contengono sempre il seguente insieme di coppie chiave-valore, indipendentemente dai dati della notifica:
Esempio | Descrizione | |
---|---|---|
eventType |
SECRET_CREATE |
Il tipo di evento che si è appena verificato. Consulta la sezione Tipi di evento per un elenco dei 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 su cui si è verificato l'evento. |
timestamp |
2021-01-20T11:17:45.081104-08:00 |
L'ora in cui si è verificato l'evento. |
A volte, inoltre, le notifiche contengono il seguente insieme di coppie chiave-valore:
Esempio | Descrizione | |
---|---|---|
versionId |
projects/p/secrets/my-secret/versions/456 |
Il nome della versione del secret in cui si è verificato l'evento.
È presente solo nelle notifiche degli eventi
|
deleteType |
REQUESTED |
Indica se l'eliminazione è stata richiesta da un utente (REQUESTED ) o a causa della scadenza del secret (EXPIRATION ). È presente solo nelle notifiche degli eventi SECRET_DELETE .
|
Dati
Il campo dati è una stringa UTF-8 contenente i metadati dell'oggetto modificato. I dati sono una versione secret o un secret.
Per le notifiche SECRET_DELETE
, i metadati contenuti nel campo dei dati rappresentano
i metadati dell'oggetto com'erano prima dell'eliminazione. Per tutte le altre notifiche, i metadati inclusi nel campo dei dati rappresentano i metadati dell'oggetto dopo che la modifica viene apportata.
Limitazioni
Le notifiche degli eventi sono disponibili solo nell'API Secret Manager v1
e in 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. Completa i seguenti prerequisiti per configurare Secret Manager e Pub/Sub:
Secret Manager:
- Crea o utilizza un progetto esistente per contenere le risorse Secret Manager.
- Se necessario, completa i passaggi menzionati nella pagina Abilitare l'API Secret Manager della guida di Secret Manager.
Pub/Sub:
- Crea o utilizza un progetto esistente per contenere le risorse Pub/Sub.
- Se necessario, abilita l'API Pub/Sub.
Autenticazione in Google Cloud:
$ gcloud auth login --update-adc
Crea un'identità dell'agente di servizio
Devi creare un'identità dell'agente di servizio per ogni progetto che richiede secret con notifiche di eventi.
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"
Il comando precedente restituisce un nome di account di servizio nel seguente formato:
service-PROJECT_NUMBER@gcp-sa-secretmanager.iam.gserviceaccount.com
Concederai a questo account di servizio l'autorizzazione a pubblicare negli argomenti Pub/Sub che verranno configurati nei tuoi secret.
Salva il nome dell'account di servizio come variabile di ambiente:
# 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 devono essere impostate 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, puoi creare argomenti con Google Cloud CLI come in questo esempio.
$ 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 all'account di servizio l'autorizzazione di pubblicazione di Secret Manager negli argomenti appena creati. Questo può essere fatto tramite la console Google Cloud o con Google Cloud CLI. Il comando seguente concede all'account di servizio il ruolo Publisher Pub/Sub (roles/pubsub.publisher
) nell'argomento my-topic
Pub/Sub.
$ gcloud pubsub topics add-iam-policy-binding PUBSUB_TOPIC_NAME \
--member "serviceAccount:${SM_SERVICE_ACCOUNT}" \
--role "roles/pubsub.publisher"
Creazione di sottoscrizioni Pub/Sub
Per visualizzare i messaggi pubblicati in un argomento, devi creare anche una sottoscrizione per quell'argomento. Segui la guida rapida di Pub/Sub per creare sottoscrizioni nel tuo progetto Pub/Sub nella console Google Cloud. In alternativa, puoi creare abbonamenti con Google Cloud CLI, come in questo esempio.
$ 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 su un secret riceveranno notifiche degli eventi in caso di modifica del secret o di una delle sue versioni. Il comando seguente crea un secret in cui è configurato my-topic
.
gcloud
Per utilizzare Secret Manager nella riga di comando, devi prima installare Google Cloud CLI o eseguirne l'upgrade alla versione 378.0.0 o successiva. In Compute Engine o GKE, devi eseguire l'autenticazione con l'ambito cloud-platform.
$ gcloud secrets create SECRET_ID --topics TOPIC_NAME
API
In questi esempi viene utilizzato curl per dimostrare l'utilizzo dell'API. Puoi generare token di accesso con gcloud auth print-access-token. In Compute Engine o GKE, devi eseguire l'autenticazione con l'ambito cloud-platform.
$ curl "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets?secretId=SECRET_ID" \
--request "POST" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer $(gcloud auth print-access-token)" \
--data-binary @- <<EOF
{
"replication":{
"automatic":{}
},
"topics":{
"name": "TOPIC_NAME"
}
}
EOF
Aggiorna argomenti dei secret
Per modificare gli argomenti Pub/Sub configurati su un secret, aggiorna il secret con i nuovi nomi delle risorse dell'argomento Pub/Sub. Con Google Cloud CLI puoi aggiungere o rimuovere uno o più argomenti da un secret, nonché cancellare tutti gli argomenti dal secret.
Aggiungi argomenti
Aggiunge uno o più argomenti a un secret. L'aggiunta di un argomento già presente non avrà alcun effetto.
$ gcloud secrets update "SECRET_ID" \
--project "PROJECT_ID" \
--add-topics "projects/PUBSUB_PROJECT_ID/topics/my-topic-2,projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME"
Rimuovi argomenti
Rimuove uno o più argomenti da un secret. La rimozione di un argomento non presente non avrà alcun effetto.
$ gcloud secrets update "SECRET_ID" \
--project "PROJECT_ID" \
--remove-topics "projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME,projects/PUBSUB_PROJECT_ID/topics/PUBSUB_OTHER_TOPIC_NAME"
Cancella argomenti
Rimuovi tutti gli argomenti da un secret.
$ gcloud secrets update SECRET_ID \
--project "PROJECT_ID" \
--clear-topics
Utilizza le notifiche degli eventi con Cloud Functions
Le notifiche di eventi possono essere utilizzate per attivare flussi di lavoro arbitrari creando funzioni Cloud Functions per utilizzare i messaggi Pub/Sub. Per una guida completa, consulta la documentazione di Cloud Functions. Il seguente codice campione è relativo a una funzione Cloud Functions che stampa eventType, secretId e metadati ogni volta che un evento viene pubblicato nell'argomento. Qui è disponibile un elenco di tutti i tipi di eventi per Secret Manager.
C#
Per eseguire questo codice, prima configura un ambiente di sviluppo C# e installa l'SDK C# di Secret Manager. In Compute Engine o GKE, devi eseguire l'autenticazione 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 prima configurare un ambiente di sviluppo Go e installare l'SDK Secret Manager Go. In Compute Engine o GKE, devi eseguire l'autenticazione con l'ambito cloud-platform.
Java
Per scoprire come installare e utilizzare la libreria client per Secret Manager, consulta librerie client di Secret Manager.
Per eseguire l'autenticazione in Secret Manager, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per eseguire questo codice, prima configura un ambiente di sviluppo Node.js e installa l'SDK Node.js di Secret Manager. In Compute Engine o GKE, devi eseguire l'autenticazione 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, prima configura un ambiente di sviluppo Python e installa l'SDK Python di Secret Manager. In Compute Engine o GKE, devi eseguire l'autenticazione con l'ambito cloud-platform.
Ruby
Per eseguire questo codice, devi prima configurare un ambiente di sviluppo Ruby e poi installare l'SDK Ruby di Secret Manager. In Compute Engine o GKE, devi eseguire l'autenticazione 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
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 un errore di configurazione, l'operazione non andrà a buon fine e verrà visualizzato un messaggio di errore che indica il motivo per cui la pubblicazione non è riuscita. Questo potrebbe accadere, ad esempio, se l'argomento non esiste 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 in seguito 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 scriverà i log nella risorsa Secret
di Secret Manager con un messaggio che indica il motivo per cui la pubblicazione non è riuscita.
Passaggi successivi
- Scopri come analizzare i secret con Cloud Asset Inventory.