Benachrichtigungen für ein Secret einrichten

Auf dieser Seite wird erläutert, wie Sie Ereignisbenachrichtigungen für Ihre Secrets in Secret Manager konfigurieren und verwenden.

Übersicht

Secret Manager ist in Pub/Sub eingebunden, um Ereignisbenachrichtigungen für Änderungen an Secrets und Secret-Versionen zu senden. Sie können diese Benachrichtigungen verwenden, um Workflows zu starten, z. B. eine Anwendung neu zu starten, wenn eine neue Secret-Version hinzugefügt wird, oder Sicherheitsexperten zu benachrichtigen, wenn ein Secret gelöscht wird. Weitere Informationen zur Verwendung dieser Benachrichtigungen zum Starten 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- oder SecretVersion-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

Die folgende Liste enthält die von Secret Manager unterstützten Ereignistypen.

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:

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

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 in 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.

1. So richten Sie Secret Manager ein:

   • 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 aus.

2. So richten Sie Pub/Sub ein:

   • Erstellen oder verwenden Sie ein vorhandenes Projekt für Ihre Pub/Sub-Ressourcen.

   • Aktivieren Sie bei Bedarf die Pub/Sub API.

3. Authentifizieren Sie sich mit dem folgenden Befehl bei Google Cloud:

       $ gcloud auth login --update-adc
       

Dienst-Agent-Identität erstellen

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

1. 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"
       

   Dieser Befehl gibt den Namen eines Dienstkontos im folgenden Format zurück:

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

2. Gewähren Sie diesem Dienstkonto die Berechtigung, in den Pub/Sub-Themen zu veröffentlichen, die für Ihre Secrets konfiguriert wurden.

3. Speichern Sie den Namen des Dienstkontos mit dem folgenden Befehl 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 auch mit dem folgenden Befehl in der Google Cloud CLI erstellen:

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

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

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

Wiederholen Sie diese Schritte 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 Themen zu veröffentlichen

Sie können dem Secret Manager-Dienstkonto Berechtigungen über die Google Cloud Console oder die Google Cloud CLI gewähren.

Mit dem folgenden Befehl wird dem Pub/Sub-Thema die Rolle „Pub/Sub-Publisher“ (roles/pubsub.publisher) zugewiesen:

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

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

gcloud pubsub topics create 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 Themen auch mit dem folgenden Befehl in der Google Cloud CLI erstellen:

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

gcloud pubsub subscriptions create projects/PUBSUB_PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_NAME `
  --topic projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME

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.

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

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

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

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 oder auch alle Themen aus dem Secret löschen.

Themen hinzufügen

Verwenden Sie den folgenden Befehl, um einem Secret ein oder mehrere Themen hinzuzufügen:

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

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

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

Themen entfernen

Verwenden Sie folgenden Befehl, um ein oder mehrere Themen aus einem Secret zu entfernen:

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

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

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

Themen löschen

Verwenden Sie den folgenden Befehl, um alle Themen aus einem Secret zu entfernen:

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

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

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

Ereignisbenachrichtigungen mit Cloud Run-Funktionen verarbeiten

Ereignisbenachrichtigungen können zum Initiieren von Workflows verwendet werden, indem Cloud Run-Funktionen erstellt werden, die die Pub/Sub-Nachrichten verarbeiten. Weitere Informationen finden Sie in der Dokumentation zu Cloud Run-Funktionen. Der folgende Beispielcode gilt für eine Cloud Run-Funktion, die eventType, secretId und Metadaten ausgibt, wenn ein Ereignis im Thema veröffentlicht wird.

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

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
}

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

/**
* 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}.`);
};

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

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

Eine Liste aller Ereignistypen finden Sie unter Ereignistypen.

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 existiert oder das Secret Manager-Dienstkonto nicht zur Veröffentlichung berechtigt ist.

Wenn Pub/Sub-Themen einem Secret hinzugefügt und das Thema dann so geändert wird, dass Secret Manager keine Nachrichten mehr veröffentlichen kann (z. B. das Thema gelöscht oder die Berechtigungen des Secret Manager-Dienstkontos entfernt werden), schreibt Secret Manager Protokolle in das Secret Manager-Log Secret mit einer Meldung, aus der hervorgeht, warum die Veröffentlichung fehlgeschlagen ist.

Nächste Schritte

• Informationen zum Analysieren von Secrets mit Cloud Asset Inventory