Benachrichtigungen für ein Secret einrichten

In diesem Thema wird die Unterstützung von Ereignisbenachrichtigungen in Secret Manager erläutert.

Überblick

Ereignisbenachrichtigungen senden Informationen zu Änderungen an Ihren Secrets und Secret-Versionen an Pub/Sub. Diese Benachrichtigungen können zum Auslösen beliebiger Workflows verwendet werden, z. B. zum Neustart einer Anwendung, wenn eine neue Secret-Version hinzugefügt wird, oder zur Benachrichtigung von Sicherheitstechnikern, wenn ein Secret gelöscht wird. Weitere Informationen zur Verwendung dieser Benachrichtigungen zum Auslösen von Workflows finden Sie in der Pub/Sub-Dokumentation.

Funktionsweise von Ereignisbenachrichtigungen in Secret Manager

Secrets können mit einer Liste von bis zu 10 Pub/Sub-Themen konfiguriert werden. Immer wenn ein Vorgang ausgeführt wird, der das Secret oder eine seiner Versionen ändert, veröffentlicht Secret Manager automatisch eine Nachricht in jedem Pub/Sub-Thema für dieses Secret. Get-, List- und Access-Aufrufe führen nicht zu Nachrichtenveröffentlichungen.

Pub/Sub-Nachrichten haben eine Reihe von "Attribut"-Schlüssel/Wert-Paaren, die Metadaten zum Ereignis enthalten, sowie ein "Daten"-Feld, das eine vollständige JSON-Serialisierung der Secret- oderSecretVersion-Ressource enthält, die erstellt oder geändert wurde. Diese JSON-Datei ist ein UTF-8-codierter String, der die Secret- oder SecretVersion-Ressource genau in der Form darstellt, die von der öffentlichen Secret Manager API angegeben wurde, codiert in JSON, wie in der proto3-JSON-Zuordnung angegeben.

Ereignistypen

Im Folgenden finden Sie eine Liste der von Secret Manager unterstützten Ereignistypen:

Ereignistyp Beschreibung
SECRET_CREATE Wird gesendet, wenn ein neues Secret erstellt wurde.
SECRET_UPDATE Wird gesendet, wenn ein neues Secret erfolgreich aktualisiert wurde.
SECRET_DELETE Wird gesendet, wenn ein Secret gelöscht wird, entweder aufgrund einer vom Nutzer initiierten Anfrage oder des Ablaufs eines Secrets.
SECRET_VERSION_ADD Wird gesendet, wenn eine neue Secret-Version erfolgreich hinzugefügt wurde.
SECRET_VERSION_ENABLE Wird gesendet, wenn eine Secret-Version aktiviert wird.
SECRET_VERSION_DISABLE Wird gesendet, wenn eine Secret-Version deaktiviert wird.
SECRET_VERSION_DESTROY Wird gesendet, wenn eine Secret-Version gelöscht wird.
SECRET_VERSION_DESTROY_SCHEDULED Wird gesendet, wenn für das Secret eine Dauer der Löschverzögerung konfiguriert ist und der Nutzer versucht, eine Secret-Version zu löschen.
SECRET_ROTATE Wird gesendet, wenn ein Secret rotiert werden muss. Weitere Informationen finden Sie unter Rotationsrichtlinien für Secrets erstellen und verwalten.
TOPIC_CONFIGURED

Dies ist eine Testnachricht ohne anderen Text oder andere Attribute als eventType: TOPIC_CONFIGURED. Dies wird gesendet, wenn ein Secret mit einer Liste von Pub/Sub-Themen erstellt oder aktualisiert wird. Dies bedeutet jedoch nicht, dass der Vorgang erfolgreich war.

Wenn der Vorgang erfolgreich war, wird unmittelbar danach eine SECRET_CREATE- oder SECRET_UPDATE-Nachricht gesendet.

Wenn Themen für ein Secret aktualisiert werden, wird eine TOPIC_CONFIGURED-Nachricht an alle Themen im Secret gesendet, einschließlich der Themen, die bereits vorhanden sind.

Benachrichtigungsformat

Benachrichtigungen, die an ein Pub/Sub-Thema gesendet werden, bestehen aus zwei Teilen:

  • Attribute: Eine Reihe von Schlüssel/Wert-Paaren, die das Ereignis beschreiben
  • Daten: Ein String, der die Metadaten des geänderten Objekts enthält

Attribute

Attribute sind Schlüssel/Wert-Paare, die in Benachrichtigungen enthalten sind, die von Secret Manager an Ihr Pub/Sub-Thema gesendet werden. Alle Benachrichtigungen außer TOPIC_CONFIGURED-Testnachrichten enthalten immer die folgenden Schlüssel/Wert-Paare, unabhängig von den Daten der Benachrichtigung:

Attributname Beispiel Beschreibung
eventType SECRET_CREATE Die Art des Ereignisses, das gerade aufgetreten ist. Eine Liste möglicher Werte finden Sie unter Ereignistypen.
dataFormat JSON_API_V1 Das Format der Objektdaten.
secretId projects/p/secrets/my-secret Der vollständige Ressourcenname des Secrets, bei dem das Ereignis aufgetreten ist.
timestamp 2021-01-20T11:17:45.081104-08:00 Zeit, zu der das Ereignis aufgetreten ist.

Darüber hinaus enthalten Benachrichtigungen manchmal die folgenden Schlüssel/Wert-Paare:

Attributname Beispiel Beschreibung
versionId projects/p/secrets/my-secret/versions/456

Der Name der Secret-Version, bei der das Ereignis aufgetreten ist.

Dies ist nur bei Ereignisbenachrichtigungen für SECRET_VERSION_ADD, SECRET_VERSION_ENABLE, SECRET_VERSION_DISABLE und SECRET_VERSION_DESTROY vorhanden.

deleteType REQUESTED Gibt an, ob der Löschvorgang von einem Nutzer (REQUESTED) oder aufgrund eines Secret-Ablaufs (EXPIRATION) angefordert wurde. Nur für SECRET_DELETE-Ereignisbenachrichtigungen vorhanden.

Daten

Das Datenfeld ist ein UTF-8-String, der die Metadaten des geänderten Objekts enthält. Daten sind entweder ein Secret oder eine Secret-Version.

Bei SECRET_DELETE-Benachrichtigungen stellen die im Datenfeld enthaltenen Metadaten die Objektmetadaten vor dem Löschvorgang dar. Bei allen anderen Benachrichtigungen repräsentieren die im Datenfeld enthaltenen Metadaten die Objektmetadaten nach der Änderung.

Beschränkungen

Ereignisbenachrichtigungen sind nur in der Secret Manager v1 API und der Google Cloud CLI verfügbar.

Hinweise

Sie können alle Ressourcen im selben Projekt speichern oder Secrets und Pub/Sub-Themen in separaten Projekten speichern. Erfüllen Sie die folgenden Voraussetzungen, um Secret Manager und Pub/Sub einzurichten:

  • Secret Manager:

    • Erstellen oder verwenden Sie ein vorhandenes Projekt für Ihre Secret Manager-Ressourcen.
    • Führen Sie bei Bedarf die Schritte auf der Seite Secret Manager API aktivieren der Secret Manager-Anleitung aus.

  • Pub/Sub:

Authentifizieren Sie sich bei Google Cloud:

$ gcloud auth login --update-adc

Dienst-Agent-Identität erstellen

Sie müssen eine Dienst-Agent-Identität für jedes Projekt erstellen, das Secrets mit Ereignisbenachrichtigungen erfordert.

Führen Sie den folgenden Befehl aus, um eine Dienstidentität mit der Google Cloud CLI zu erstellen:

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

Der vorherige Befehl gibt den Namen eines Dienstkontos in diesem Format zurück:

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

Sie erteilen diesem Dienstkonto die Berechtigung, in den Pub/Sub-Themen zu veröffentlichen, die für Ihre Secrets konfiguriert werden.

Speichern Sie den Namen des Dienstkontos als Umgebungsvariable:

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

Die Umgebungsvariablen für das Secret Manager-Projekt, das Pub/Sub-Projekt und das Secret Manager-Dienstkonto müssen während der gesamten Dauer der Anleitung festgelegt sein.

Pub/Sub-Themen erstellen

Folgen Sie der Pub/Sub-Kurzanleitung, um Themen in Ihrem Pub/Sub-Projekt in der Google Cloud Console zu erstellen. Alternativ können Sie Themen mit der Google Cloud CLI wie in diesem Beispiel erstellen.

$ gcloud pubsub topics create "projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME"

Wiederholen Sie diesen Vorgang mehrmals, wenn Sie mehrere Pub/Sub-Themen für das Secret erstellen möchten.

Gewähren Sie dem Dienstkonto für Secret Manager die Berechtigung, in den soeben erstellten Themen zu veröffentlichen. Das ist über die Google Cloud Console oder die Google Cloud CLI möglich. Mit dem folgenden Befehl wird dem Dienstkonto die Pub/Sub-Publisher-Rolle (roles/pubsub.publisher) für das Pub/Sub-Thema my-topic zugewiesen.

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

Pub/Sub-Abos erstellen

Um sich die in einem Thema veröffentlichten Nachrichten ansehen zu können, müssen Sie auch ein Abo für das Thema erstellen. Folgen Sie der Pub/Sub-Kurzanleitung, um Abos in Ihrem Pub/Sub-Projekt in der Google Cloud Console zu erstellen. Alternativ können Sie Abos mit der Google Cloud CLI erstellen, wie in diesem Beispiel.

$ gcloud pubsub subscriptions create "projects/PUBSUB_PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_NAME" \
    --topic "projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME"

Secret mit konfigurierten Themen erstellen

Erstellen Sie ein Secret mit einer Liste von bis zu 10 konfigurierten Themen. Alle in einem Secret konfigurierten Themen erhalten Ereignisbenachrichtigungen, wenn das Secret oder eine seiner Versionen geändert wird. Mit dem folgenden Befehl wird ein Secret mit konfiguriertem my-topic erstellt.

gcloud

Wenn Sie Secret Manager in der Befehlszeile verwenden möchten, müssen Sie zuerst die Google Cloud CLI installieren oder ein Upgrade auf Version 378.0.0 oder höher ausführen. In Compute Engine oder GKE müssen Sie sich mit dem Bereich cloud-platform authentifizieren. 

$ gcloud secrets create SECRET_ID --topics TOPIC_NAME

API

In diesen Beispielen wird curl verwendet, um die Verwendung mit der API zu demonstrieren. Sie können Zugriffstokens mit gcloud auth print-access-token generieren. In Compute Engine oder GKE müssen Sie sich mit dem Bereich cloud-platform authentifizieren. 

$ 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

Secret-Themen aktualisieren

Ändern Sie die für ein Secret konfigurierten Pub/Sub-Themen, indem Sie das Secret mit den neuen Ressourcennamen der Pub/Sub-Themen aktualisieren. Mit der Google Cloud CLI können Sie ein oder mehrere Themen zu einem Secret hinzufügen oder daraus entfernen sowie alle Themen aus dem Secret löschen.

Themen hinzufügen

Fügt einem Secret ein oder mehrere Themen hinzu. Das Hinzufügen eines Themas, das bereits vorhanden ist, hat keine Auswirkungen.

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

Themen entfernen

Entfernt ein oder mehrere Themen aus einem Secret. Das Entfernen eines Themas, das nicht vorhanden ist, hat keine Auswirkungen.

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

Themen löschen

Entfernt alle Themen aus einem Secret.

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

Ereignisbenachrichtigungen mit Cloud Functions verarbeiten

Ereignisbenachrichtigungen können verwendet werden, um beliebige Workflows auszulösen. Dazu erstellen Sie Cloud Functions-Funktionen, die die Pub/Sub-Nachrichten verarbeiten. Eine vollständige Anleitung finden Sie in der Cloud Functions-Dokumentation. Der folgende Beispielcode bezieht sich auf eine Cloud Functions-Funktion, die bei jeder Veröffentlichung eines Ereignisses im Thema „eventType“, „secretId“ und „metadata“ ausgibt. Eine Liste aller Ereignistypen für Secret Manager finden Sie hier.

C#

Um diesen Code auszuführen, müssen Sie eine C#-Entwicklungsumgebung einrichten und das Secret Manager C# SDK installieren. In Compute Engine oder GKE müssen Sie sich mit dem Bereich cloud-platform authentifizieren. 

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

Um diesen Code auszuführen, müssen Sie zuerst eine Go-Entwicklungsumgebung einrichten und das Secret Manager Go SDK installieren. In Compute Engine oder GKE müssen Sie sich mit dem Bereich cloud-platform authentifizieren. 

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

Informationen zum Installieren und Verwenden der Clientbibliothek für Secret Manager finden Sie unter Secret Manager-Clientbibliotheken.

Richten Sie Standardanmeldedaten für Anwendungen ein, um sich bei Secret Manager zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten. 


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

Um diesen Code auszuführen, müssen Sie zuerst eine Node.js-Entwicklungsumgebung einrichten und das Cloud KMS Node.js SDK installieren. In Compute Engine oder GKE müssen Sie sich mit dem Bereich cloud-platform authentifizieren. 

/**
* 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

Um diesen Code auszuführen, müssen Sie zuerst eine Python-Entwicklungsumgebung einrichten und das Secret Manager Python SDK installieren. In Compute Engine oder GKE müssen Sie sich mit dem Bereich cloud-platform authentifizieren. 

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

Um diesen Code auszuführen, müssen Sie zuerst eine Ruby-Entwicklungsumgebung einrichten und das Secret Manager Ruby SDK installieren. In Compute Engine oder GKE müssen Sie sich mit dem Bereich cloud-platform authentifizieren. 

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

Falsch konfigurierte Themen

Wenn Pub/Sub-Themen bei einem Erstellungs- oder Aktualisierungsvorgang einem Secret hinzugefügt werden, aber Secret Manager aufgrund einer falschen Konfiguration keine Nachrichten im Thema veröffentlichen kann, schlägt der Vorgang mit einer Fehlermeldung fehl, die angibt, warum die Veröffentlichung fehlgeschlagen ist. Dies kann beispielsweise der Fall sein, wenn das Thema nicht vorhanden ist oder das Secret Manager-Dienstkonto keine Berechtigung zur Veröffentlichung hat.

Wenn Pub/Sub-Themen einem Secret hinzugefügt und anschließend das Thema geändert wird, sodass Secret Manager keine Nachrichten mehr veröffentlichen kann (z. B. wird das Thema gelöscht oder die Berechtigungen des Secret Manager-Dienstkontos werden entfernt), schreibt Secret Manager Logs in die Secret Manager-Secret-Ressource mit einer Nachricht dazu, warum die Veröffentlichung fehlgeschlagen ist.

Nächste Schritte