Menyiapkan notifikasi pada secret

Halaman ini menjelaskan cara mengonfigurasi dan menggunakan notifikasi peristiwa untuk secret Anda di Secret Manager.

Ringkasan

Secret Manager terintegrasi dengan Pub/Sub untuk memberikan notifikasi peristiwa terkait perubahan pada secret dan versi secret. Anda dapat menggunakan notifikasi ini untuk memulai alur kerja, seperti memulai ulang aplikasi saat versi secret baru ditambahkan, atau memberi tahu engineer keamanan saat secret dihapus. Untuk mengetahui informasi selengkapnya tentang cara menggunakan notifikasi ini untuk memulai alur kerja, lihat dokumentasi Pub/Sub.

Cara kerja notifikasi peristiwa di Secret Manager

Secret dapat dikonfigurasi dengan daftar hingga 10 topik Pub/Sub. Setiap kali operasi dilakukan yang mengubah secret atau salah satu versinya, Secret Manager akan otomatis memublikasikan pesan ke setiap topik Pub/Sub pada secret tersebut. Panggilan Get, List, dan Access tidak menghasilkan publikasi pesan.

Pesan Pub/Sub memiliki serangkaian pasangan nilai kunci atribut yang berisi metadata tentang peristiwa, serta kolom data yang berisi serialisasi JSON lengkap dari resource Secret atau SecretVersion yang dibuat atau diubah. JSON ini adalah string yang dienkode UTF-8 yang merepresentasikan resource Secret atau SecretVersion dalam bentuk yang persis seperti yang ditentukan oleh Secret Manager public API, dienkode dalam JSON seperti yang ditentukan dalam Pemetaan JSON proto3.

Jenis peristiwa

Berikut adalah daftar jenis peristiwa yang didukung oleh Secret Manager.

Format notifikasi

Notifikasi yang dikirim ke topik Pub/Sub terdiri dari dua bagian:

• Atribut: Kumpulan key-value pair yang mendeskripsikan acara.

• Data: String yang berisi metadata objek yang diubah.

Atribut

Atribut adalah key-value pair yang terdapat dalam notifikasi yang dikirim oleh Secret Manager ke topik Pub/Sub Anda. Semua notifikasi selain TOPIC_CONFIGUREDpesan pengujian selalu berisi serangkaian key:value pair berikut, terlepas dari data notifikasi:

Selain itu, notifikasi terkadang berisi serangkaian key-value pair berikut:

Data

Kolom data adalah string UTF-8 yang berisi metadata objek yang diubah. Data berupa secret atau versi secret.

Untuk notifikasi SECRET_DELETE, metadata yang dimuat dalam kolom data menampilkan metadata objek seperti sebelum penghapusan. Untuk semua notifikasi lainnya, metadata yang disertakan dalam kolom data mewakili metadata objek setelah perubahan terjadi.

Batasan

Notifikasi peristiwa hanya tersedia di Secret Manager API v1 dan Google Cloud CLI.

Sebelum memulai

Anda dapat memilih untuk menyimpan semua resource dalam project yang sama atau menyimpan topik Pub/Sub dan secret dalam project yang berbeda.

1. Untuk menyiapkan Secret Manager, selesaikan langkah-langkah berikut:

   • Buat atau gunakan project yang ada untuk menyimpan resource Secret Manager Anda.

   • Jika perlu, selesaikan langkah-langkah yang disebutkan di halaman Mengaktifkan Secret Manager API.

2. Untuk menyiapkan Pub/Sub, selesaikan langkah-langkah berikut:

   • Buat atau gunakan project yang ada untuk menyimpan resource Pub/Sub Anda.

   • Jika perlu, aktifkan Pub/Sub API.

3. Lakukan autentikasi ke Google Cloud menggunakan perintah berikut:

       $ gcloud auth login --update-adc
       

Membuat identitas agen layanan

Untuk membuat identitas agen layanan untuk setiap project yang memerlukan rahasia dengan notifikasi peristiwa, ikuti langkah-langkah berikut:

1. Untuk membuat identitas layanan dengan Google Cloud CLI, jalankan perintah berikut:

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

   Perintah ini menampilkan nama akun layanan, dengan format berikut:

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

2. Beri akun layanan ini izin untuk memublikasikan di topik Pub/Sub yang dikonfigurasi di rahasia Anda.

3. Simpan nama akun layanan sebagai variabel lingkungan menggunakan perintah berikut:

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

Variabel lingkungan untuk project Secret Manager, project Pub/Sub, dan akun layanan Secret Manager harus disetel selama Anda mengikuti prosedur ini.

Membuat topik Pub/Sub

Ikuti panduan memulai Pub/Sub untuk membuat topik di project Pub/Sub Anda di konsol Google Cloud . Atau, buat topik di Google Cloud CLI menggunakan perintah berikut:

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"

Ulangi langkah ini beberapa kali jika Anda ingin membuat beberapa topik Pub/Sub pada rahasia.

Memberi akun layanan untuk Secret Manager izin untuk memublikasikan di topik

Anda dapat memberikan izin ke akun layanan Secret Manager melalui konsol Google Cloud atau melalui Google Cloud CLI.

Untuk memberikan peran Pub/Sub Publisher (roles/pubsub.publisher) di topik Pub/Sub, gunakan perintah berikut:

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

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

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

Membuat langganan Pub/Sub

Untuk melihat pesan yang dipublikasikan ke suatu topik, Anda juga harus membuat langganan ke topik tersebut. Ikuti panduan memulai Pub/Sub untuk membuat langganan di project Pub/Sub Anda di konsol Google Cloud . Atau, buat topik di Google Cloud CLI menggunakan perintah berikut:

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

Membuat secret dengan topik yang dikonfigurasi

Buat rahasia dengan daftar hingga 10 topik yang dikonfigurasi. Semua topik yang dikonfigurasi pada secret menerima notifikasi peristiwa saat secret atau salah satu versinya berubah.

gcloud secrets create SECRET_ID --topics PUBSUB_TOPIC_NAME

gcloud secrets create SECRET_ID --topics PUBSUB_TOPIC_NAME

gcloud secrets create SECRET_ID --topics PUBSUB_TOPIC_NAME

POST https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets?secretId=SECRET_ID

{
  "replication":{
    "automatic":{}
  },
  "topics":{
    "name": "TOPIC_NAME"
  }
}

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets?secretId=SECRET_ID"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets?secretId=SECRET_ID" | Select-Object -Expand Content

{
  "name": "/projects/my-project/locations/me-central2/secrets/my-drz-secret",
  "createTime": "2024-03-25T08:24:13.153705Z",
  "etag": "\"161477e6071da9\""
}

Memperbarui topik rahasia

Ubah topik Pub/Sub yang dikonfigurasi pada secret dengan memperbarui secret menggunakan nama resource topik Pub/Sub yang baru. Dengan Google Cloud CLI, Anda dapat menambahkan atau menghapus satu atau beberapa topik dari secret, serta menghapus semua topik dari secret.

Menambahkan topik

Untuk menambahkan satu atau beberapa topik ke secret, gunakan perintah berikut:

gcloud secrets update SECRET_ID \
  --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 `
  --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 ^
  --project PROJECT_ID ^
  --add-topics projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_1_NAME,projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_2_NAME

Menghapus topik

Untuk menghapus satu atau beberapa topik dari secret, gunakan perintah berikut:

gcloud secrets update SECRET_ID \
  --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 `
  --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 ^
  --project PROJECT_ID ^
  --remove-topics projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_1_NAME,projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_2_NAME

Hapus topik

Untuk menghapus semua topik dari secret, gunakan perintah berikut:

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

gcloud secrets update SECRET_ID `
  --project PROJECT_ID `
  --clear-topics

gcloud secrets update SECRET_ID ^
  --project PROJECT_ID ^
  --clear-topics

Menggunakan notifikasi peristiwa dengan fungsi Cloud Run

Notifikasi peristiwa dapat digunakan untuk memulai alur kerja dengan membuat fungsi Cloud Run untuk menggunakan pesan Pub/Sub. Lihat dokumentasi Cloud Run Functions untuk mengetahui informasi selengkapnya. Contoh kode berikut adalah untuk fungsi Cloud Run yang mencetak eventType, secretId, dan metadata setiap kali peristiwa dipublikasikan ke topik.

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

Untuk mengetahui daftar semua jenis peristiwa, lihat Jenis Peristiwa.

Topik yang salah dikonfigurasi

Jika topik Pub/Sub ditambahkan ke secret dalam operasi Buat atau Perbarui, tetapi Secret Manager tidak dapat memublikasikan pesan ke topik karena salah konfigurasi, operasi akan gagal dengan pesan error yang menunjukkan alasan kegagalan publikasi. Hal ini dapat terjadi, misalnya, jika topik tidak ada, atau jika akun layanan Secret Manager tidak memiliki izin untuk memublikasikan.

Jika topik Pub/Sub ditambahkan ke secret, lalu topik tersebut diubah sehingga Secret Manager tidak dapat lagi memublikasikan pesan (misalnya, topik dihapus, atau izin akun layanan Secret Manager dihapus), Secret Manager akan menulis log ke Secret Secret Manager dengan pesan yang menunjukkan alasan kegagalan publikasi.

Langkah berikutnya

• Pelajari cara menganalisis secret dengan Inventaris Aset Cloud.