Configurare le notifiche per un segreto

Questo argomento illustra il supporto per le notifiche degli eventi in Secret Manager.

Panoramica

Le notifiche di eventi inviano informazioni sulle modifiche ai secret e alle versioni dei secret a Pub/Sub. Queste notifiche possono essere utilizzate per attivare flussi di lavoro arbitrari, ad esempio il riavvio di un'applicazione quando viene aggiunta una nuova versione del secret o la notifica ai tecnici della sicurezza quando un secret viene eliminato. Per ulteriori informazioni su come utilizzare queste notifiche per attivare 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 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 presenti nel secret. Le chiamate Get, List e Access non generano la pubblicazione di messaggi.

I messaggi Pub/Sub hanno un insieme di "attribute" coppie chiave-valore contenenti metadati relativi all'evento, oltre a "dati" campo contenente una serializzazione JSON completa della risorsa Secret o SecretVersion che è stata 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 nel proto3 JSON Mapping.

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 disabilitata.
SECRET_VERSION_DESTROY Inviata quando viene eliminata una versione del secret.
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 Inviato quando è il momento di ruotare un secret. Per ulteriori informazioni, consulta la sezione Creare e gestire i criteri di rotazione sui secret.
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 è riuscita.

Un messaggio SECRET_CREATE o SECRET_UPDATE verrà inviata subito dopo se l'operazione è riuscita.

Ogni volta che gli argomenti vengono aggiornati su un secret, viene restituito un TOPIC_CONFIGURED a tutti gli argomenti nel secret, inclusi quelli che erano sono già presenti.

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 da Secret Manager all'argomento Pub/Sub. Tutte le notifiche tranne i TOPIC_CONFIGURED messaggi di prova sono sempre contengono il seguente set di coppie chiave:valore, indipendentemente dallo stato della notifica dati:

Nome attributo Esempio Descrizione
eventType SECRET_CREATE Il tipo di evento che si è appena verificato. Per l'elenco dei valori possibili, consulta la sezione Tipi di evento.
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 attributo Esempio Descrizione
versionId projects/p/secrets/my-secret/versions/456

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

Questo valore è presente solo nelle notifiche di eventi SECRET_VERSION_ADD, SECRET_VERSION_ENABLE, SECRET_VERSION_DISABLE e 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 di dati è una stringa UTF-8 che contiene i metadati dell'oggetto modificato. I dati sono un secret o una versione secret.

Per le notifiche SECRET_DELETE, i metadati contenuti nel campo dei dati rappresentano i metadati dell'oggetto come erano prima dell'eliminazione. Per tutte le altre notifiche, i metadati inclusi nei rappresenta i metadati dell'oggetto dopo il campo un cambiamento.

Limitazioni

Le notifiche di 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 di Secret Manager.
    • Se necessario, completa i passaggi menzionati nella Abilita la pagina dell'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à agente di servizio per ogni che richiede secret con notifiche di eventi.

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"

Il comando precedente restituisce un nome account di servizio utilizzando il seguente formato:

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

Concederai a questo account di servizio l'autorizzazione per 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 Secret Manager a pubblicare sugli argomenti appena creati. Questa operazione può essere eseguita mediante la console Google Cloud o con Google Cloud CLI. Il seguente comando concede all'account di servizio il ruolo Publisher Pub/Sub (roles/pubsub.publisher) per l'argomento Pub/Sub my-topic.

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

Creare 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 abbonamenti 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"

Creare un secret con gli argomenti configurati

Crea un secret con un elenco di massimo 10 argomenti configurati. Tutti gli argomenti configurati in un secret riceveranno le notifiche degli eventi quando il secret o una delle sue versioni vengono modificati. Il seguente comando crea un segreto con my-topic configurato.

gcloud

Per utilizzare Secret Manager nella riga di comando, devi prima Installa o esegui l'upgrade alla versione 378.0.0 o successive di Google Cloud CLI. In Compute Engine o GKE, devi eseguire l'autenticazione con l'ambito cloud-platform. 

$ gcloud secrets create SECRET_ID --topics TOPIC_NAME

API

Questi esempi utilizzano 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 gli argomenti dei secret

Modifica gli argomenti Pub/Sub configurati in un segreto aggiornando il segreto 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 e cancellare tutti gli argomenti dal secret.

Aggiungere 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"

Argomenti chiari

Rimuovi tutti gli argomenti da un secret.

$ gcloud secrets update SECRET_ID \
    --project "PROJECT_ID" \
    --clear-topics

Utilizzare le notifiche di eventi con le funzioni Cloud Run

Le notifiche di eventi possono essere utilizzate per attivare flussi di lavoro arbitrari creando funzioni Cloud Run per consumare i messaggi Pub/Sub. Per una guida completa, consulta la documentazione sulle funzioni di Cloud Run. Il codice campione riportato di seguito è per una funzione Cloud Functions che stampa eventType, secretId e metadati ogni volta che un evento viene pubblicato nell'argomento. Qui puoi trovare l'elenco di tutti i tipi di eventi per Secret Manager.

C#

Per eseguire questo codice, per prima cosa configura un ambiente di sviluppo C# e installare l'SDK Secret Manager C#. 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 innanzitutto configurare un ambiente di sviluppo Go e installare l'SDK Go di Secret Manager. In Compute Engine o GKE, devi eseguire l'autenticazione 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 autenticarti in Secret Manager, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura 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 prima configurare un ambiente di sviluppo Node.js e installare 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, configura prima un ambiente di sviluppo Python e installare l'SDK per Python di Secret Manager. Su Compute Engine o GKE, devi autenticarti 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, prima configura un ambiente di sviluppo Ruby e installa 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'errata configurazione, l'operazione non riuscirà e verrà visualizzato un messaggio di errore che indica il motivo per cui la pubblicazione non è riuscita. Questo può 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 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 di Secret Manager vengono rimosse), Secret Manager scriverà i log nella risorsa Secret di Secret Manager Secret con un messaggio che indica il motivo per cui la pubblicazione non è riuscita.

Passaggi successivi