设置 Secret 的通知

本页介绍了如何在 Secret Manager 中为 Secret 配置和使用事件通知。

概览

Secret Manager 与 Pub/Sub 集成，可针对密钥和密钥版本的更改提供事件通知。您可以使用这些通知启动工作流，例如在添加新的 Secret 版本时重启应用，或在删除 Secret 时通知安全工程师。如需详细了解如何使用这些通知启动工作流，请参阅 Pub/Sub 文档。

事件通知在 Secret Manager 中的运作方式

密文最多可配置 10 个 Pub/Sub 主题的列表。每当执行修改密文或其某个版本的操作时，Secret Manager 都会自动向该密文的每个 Pub/Sub 主题发布一条消息。Get、List 和 Access 调用不会导致消息发布。

Pub/Sub 消息具有一组属性键值对（包含有关事件的元数据）以及“数据”字段（包含已创建或修改的 Secret 或 SecretVersion 资源的完整 JSON 序列化）。此 JSON 是采用 UTF-8 编码的字符串，该字符串以 Secret Manager 公共 API 指定的形式表示 Secret 或 SecretVersion 资源，并按照 proto3 JSON 映射中指定的进行 JSON 编码。

事件类型

以下是 Secret Manager 支持的事件类型的列表。

通知格式

发送到 Pub/Sub 主题的通知由以下两部分组成：

• 特性：描述事件的一组键值对。

• 数据：包含已更改对象的元数据的字符串。

属性

属性是指 Secret Manager 发送到 Pub/Sub 主题的通知中包含的键值对。无论通知的数据如何，除 TOPIC_CONFIGURED 测试消息之外的所有通知始终包含下列一组键值对：

此外，通知有时会包含下列一组键值对：

数据

数据字段是一个 UTF-8 字符串，其中包含发生更改的对象的元数据。数据是密钥或密钥版本。

对于 SECRET_DELETE 通知，数据字段中包含的元数据代表删除前的对象元数据。对于其他所有通知，data 字段中包含的元数据代表发生更改后的对象元数据。

限制

事件通知仅在 Secret Manager v1 API 和 Google Cloud CLI 中可用。

准备工作

您可以选择将所有资源存储在同一项目中，也可以将密文和 Pub/Sub 主题存储在不同的项目中。

1. 如需设置 Secret Manager，请完成以下操作：

   • 创建或使用现有项目来保存您的 Secret Manager 资源。

   • 如有必要，请完成启用 Secret Manager API 页面中提及的步骤。

2. 如需设置 Pub/Sub，请完成以下操作：

   • 创建或使用现有项目来保存您的 Pub/Sub 资源。

   • 如有必要，请启用 Pub/Sub API。

3. 使用以下命令向 Google Cloud 进行身份验证：

       $ gcloud auth login --update-adc
       

创建服务代理身份

如需为每个需要包含事件通知的密文的项目创建服务代理身份，请按以下步骤操作：

1. 如需使用 Google Cloud CLI 创建服务身份，请运行以下命令：

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

   此命令会返回以下格式的服务账号名称：

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

2. 向此服务账号授予针对为密文配置的 Pub/Sub 主题进行发布的权限。

3. 使用以下命令将服务账号名称保存为环境变量：

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

在遵循此流程的全过程中，您必须设置 Secret Manager 项目、Pub/Sub 项目和 Secret Manager 服务账号的环境变量。

创建 Pub/Sub 主题

按照 Pub/Sub 快速入门中的说明，在 Google Cloud 控制台中的 Pub/Sub 项目中创建主题。或者，您也可以使用以下命令在 Google Cloud CLI 中创建主题：

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"

如果您要在密文上创建多个 Pub/Sub 主题，请重复此操作多次。

向 Secret Manager 的服务账号授予针对主题发布消息的权限

您可以通过 Google Cloud 控制台或 Google Cloud CLI 向 Secret Manager 服务账号授予权限。

如需授予对 Pub/Sub 主题的 Pub/Sub Publisher 角色 (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"

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

创建 Pub/Sub 订阅

如需查看发布到某个主题的消息，您还必须创建对该主题的订阅。按照 Pub/Sub 快速入门中的说明，在 Google Cloud 控制台中的 Pub/Sub 项目中创建订阅。或者，您也可以使用以下命令在 Google Cloud CLI 中创建主题：

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

创建配置了主题的密文

创建一个最多配置了 10 个主题列表的密文。如果密文或其某个版本发生更改，则在密文上配置的所有主题都会收到事件通知。

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 主题

通过使用新的 Pub/Sub 主题资源名称更新密文，修改在密文上配置的 Pub/Sub 主题。您可以使用 Google Cloud CLI 在密文中添加或移除一个或多个主题，以及从密文中清除所有主题。

添加主题

如需向密文添加一个或多个主题，请使用以下命令：

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

移除主题

如需从密钥中移除一个或多个主题，请使用以下命令：

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

清除主题

如需从密文中移除所有主题，请使用以下命令：

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

通过 Cloud Run functions 使用事件通知

您可以通过创建 Cloud Run 函数来使用事件通知启动工作流，以便使用 Pub/Sub 消息。如需了解详情，请参阅 Cloud Run 函数文档。以下示例代码适用于 Cloud Run 函数，该函数会在有事件发布到主题时输出 eventType、secretId 和元数据。

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

如需查看所有事件类型的列表，请参阅事件类型。

主题配置有误

如果在“创建或更新”操作中向密文添加了 Pub/Sub 主题，但 Secret Manager 因配置错误而无法向主题发布消息，则操作将失败并显示错误消息，表明发布失败的原因。例如，如果主题不存在，或者 Secret Manager 服务账号没有发布权限，则可能会发生这种情况。

如果向密文添加了 Pub/Sub 主题，但之后主题发生更改，导致 Secret Manager 无法再发布消息（例如，主题被删除或 Secret Manager 服务账号权限被移除），Secret Manager 会将日志写入 Secret Manager Secret，并附带一条消息，说明发布失败的原因。

后续步骤

• 了解如何使用 Cloud Asset Inventory 分析 Secret。