Menyiapkan notifikasi pada secret

Topik ini membahas dukungan untuk notifikasi peristiwa di Secret Manager.

Ringkasan

Notifikasi peristiwa mengirimkan informasi tentang perubahan pada secret dan versi secret Anda ke Pub/Sub. Notifikasi ini dapat digunakan untuk memicu alur kerja arbitrer, seperti memulai ulang aplikasi saat versi secret baru ditambahkan, atau memberi tahu engineer keamanan saat secret dihapus. Untuk informasi selengkapnya tentang cara menggunakan notifikasi ini untuk memicu 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 kumpulan 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 mewakili resource Secret atau SecretVersion dalam bentuk yang sama persis dengan yang ditentukan oleh API publik Pengelola Rahasia, yang dienkode dalam JSON seperti yang ditentukan dalam Pemetaan JSON proto3.

Jenis peristiwa

Berikut adalah daftar jenis peristiwa yang didukung oleh Pengelola Secret:

Jenis peristiwa Deskripsi
SECRET_CREATE Dikirim saat secret baru berhasil dibuat.
SECRET_UPDATE Dikirim saat secret baru berhasil diperbarui.
SECRET_DELETE Dikirim saat secret dihapus, baik karena permintaan yang dimulai pengguna atau masa berlaku secret berakhir.
SECRET_VERSION_ADD Dikirim saat versi secret baru berhasil ditambahkan.
SECRET_VERSION_ENABLE Dikirim saat versi secret diaktifkan.
SECRET_VERSION_DISABLE Dikirim saat versi secret dinonaktifkan.
SECRET_VERSION_DESTROY Dikirim saat versi secret dihancurkan.
SECRET_VERSION_DESTROY_SCHEDULED Dikirim saat durasi penundaan pemusnahan dikonfigurasi pada secret dan pengguna mencoba menghancurkan versi secret.
SECRET_ROTATE Dikirim saat tiba waktunya untuk merotasi secret. Lihat Membuat dan mengelola kebijakan rotasi pada secret untuk mengetahui informasi selengkapnya.
TOPIC_CONFIGURED

Ini adalah pesan pengujian tanpa isi atau atribut selain eventType: TOPIC_CONFIGURED. Peristiwa ini dikirim saat secret dibuat atau diperbarui dengan daftar topik Pub/Sub, tetapi tidak menunjukkan bahwa operasi berhasil.

Pesan SECRET_CREATE atau SECRET_UPDATE akan segera dikirim setelahnya jika operasi berhasil.

Setiap kali topik diperbarui di secret, pesan TOPIC_CONFIGURED akan dikirim ke semua topik di secret, termasuk yang sudah ada.

Format notifikasi

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

  • Atribut: Kumpulan key:value pair yang mendeskripsikan peristiwa.
  • 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 pesan pengujian TOPIC_CONFIGURED selalu berisi serangkaian key-value pair berikut, terlepas dari data notifikasi:

Nama atribut Contoh Deskripsi
eventType SECRET_CREATE Jenis peristiwa yang baru saja terjadi. Lihat Jenis peristiwa untuk daftar kemungkinan nilai.
dataFormat JSON_API_V1 Format data objek.
secretId projects/p/secrets/my-secret Nama resource lengkap secret tempat peristiwa terjadi.
timestamp 2021-01-20T11:17:45.081104-08:00 Waktu peristiwa terjadi.

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

Nama atribut Contoh Deskripsi
versionId projects/p/secrets/my-secret/versions/456

Nama versi secret tempat peristiwa terjadi.

Ini hanya ada di notifikasi peristiwa SECRET_VERSION_ADD, SECRET_VERSION_ENABLE, SECRET_VERSION_DISABLE, dan SECRET_VERSION_DESTROY.

deleteType REQUESTED Apakah penghapusan diminta oleh pengguna (REQUESTED) atau karena masa berlaku secret berakhir (EXPIRATION). Hanya ada di notifikasi peristiwa SECRET_DELETE.

Data

Kolom data adalah string UTF-8 yang berisi metadata objek yang diubah. Data adalah Secret atau Versi Secret.

Untuk notifikasi SECRET_DELETE, metadata yang dimuat dalam kolom data mewakili 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 v1 API dan Google Cloud CLI.

Sebelum memulai

Anda dapat memilih untuk menyimpan semua resource dalam project yang sama atau menyimpan secret dan topik Pub/Sub dalam project terpisah. Selesaikan prasyarat berikut untuk menyiapkan Secret Manager dan Pub/Sub:

  • Secret Manager:

    • 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 dalam panduan Secret Manager.

  • Pub/Sub:

    • Buat atau gunakan project yang ada untuk menyimpan resource Pub/Sub Anda.
    • Jika perlu, aktifkan Pub/Sub API.

Lakukan autentikasi ke Google Cloud:

$ gcloud auth login --update-adc

Membuat identitas agen layanan

Anda perlu membuat identitas agen layanan untuk setiap project yang memerlukan secret dengan notifikasi peristiwa.

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

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

Perintah sebelumnya menampilkan nama akun layanan, menggunakan format berikut:

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

Anda akan memberikan izin kepada akun layanan ini untuk memublikasikan di topik Pub/Sub yang akan dikonfigurasi di secret Anda.

Simpan nama akun layanan sebagai variabel lingkungan:

# 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 ditetapkan selama Anda mengikuti prosedur ini.

Membuat topik Pub/Sub

Ikuti panduan memulai Pub/Sub untuk membuat topik di project Pub/Sub di konsol Google Cloud. Atau, Anda dapat membuat topik dengan Google Cloud CLI seperti dalam contoh ini.

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

Ulangi beberapa kali jika Anda ingin membuat beberapa topik Pub/Sub pada secret.

Berikan izin publikasi ke akun layanan untuk Secret Manager di topik yang baru saja dibuat. Hal ini dapat dilakukan melalui Konsol Google Cloud atau dengan Google Cloud CLI. Perintah berikut memberikan peran Pub/Sub Publisher (roles/pubsub.publisher) di topik Pub/Sub my-topic ke akun layanan.

$ 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, Anda dapat membuat langganan dengan Google Cloud CLI seperti dalam contoh ini.

$ 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 secret dengan daftar hingga 10 topik yang dikonfigurasi. Semua topik yang dikonfigurasi pada secret akan menerima notifikasi peristiwa saat secret atau salah satu versinya diubah. Perintah berikut membuat secret dengan my-topic yang dikonfigurasi.

gcloud

Untuk menggunakan Secret Manager di command line, pertama-tama Instal atau upgrade ke Google Cloud CLI versi 378.0.0 atau yang lebih tinggi. Di Compute Engine atau GKE, Anda harus melakukan autentikasi dengan cakupan cloud-platform. 

$ gcloud secrets create SECRET_ID --topics TOPIC_NAME

API

Contoh ini menggunakan curl untuk menunjukkan penggunaan API. Anda dapat membuat token akses dengan gcloud auth print-access-token. Di Compute Engine atau GKE, Anda harus melakukan autentikasi dengan cakupan 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

Memperbarui topik rahasia

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

Menambahkan topik

Menambahkan satu atau beberapa topik ke secret. Menambahkan topik yang sudah ada tidak akan berpengaruh.

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

Menghapus topik

Menghapus satu atau beberapa topik dari secret. Menghapus topik yang tidak ada tidak akan berdampak apa pun.

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

Menghapus topik

Menghapus semua topik dari secret.

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

Menggunakan notifikasi peristiwa dengan fungsi Cloud Run

Notifikasi peristiwa dapat digunakan untuk memicu alur kerja arbitrer dengan membuat fungsi Cloud Run untuk menggunakan pesan Pub/Sub. Lihat dokumentasi fungsi Cloud Run untuk panduan selengkapnya. Contoh kode berikut adalah untuk fungsi cloud yang mencetak eventType, secretId, dan metadata setiap kali peristiwa dipublikasikan ke topik. Daftar semua Jenis Peristiwa untuk Pengelola Secret dapat ditemukan di sini.

C#

Untuk menjalankan kode ini, pertama-tama siapkan lingkungan pengembangan C# dan instal Secret Manager C# SDK. Di Compute Engine atau GKE, Anda harus melakukan autentikasi dengan cakupan 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

Untuk menjalankan kode ini, siapkan lingkungan pengembangan Go terlebih dahulu dan instal Secret Manager Go SDK. Di Compute Engine atau GKE, Anda harus melakukan autentikasi dengan cakupan 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

Untuk mempelajari cara menginstal dan menggunakan library klien untuk Secret Manager, lihat library klien Secret Manager.

Untuk mengautentikasi ke Secret Manager, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 


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

Untuk menjalankan kode ini, siapkan lingkungan pengembangan Node.js terlebih dahulu dan instal Secret Manager Node.js SDK. Di Compute Engine atau GKE, Anda harus melakukan autentikasi dengan cakupan 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

Untuk menjalankan kode ini, pertama-tama siapkan lingkungan pengembangan Python dan instal Secret Manager Python SDK. Di Compute Engine atau GKE, Anda harus melakukan autentikasi dengan cakupan 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

Untuk menjalankan kode ini, siapkan lingkungan pengembangan Ruby terlebih dahulu dan instal Secret Manager Ruby SDK. Di Compute Engine atau GKE, Anda harus melakukan autentikasi dengan cakupan 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

Topik yang salah dikonfigurasi

Jika topik Pub/Sub ditambahkan ke secret dalam operasi Create atau Update, tetapi Pengelola Secret tidak dapat memublikasikan pesan ke topik karena kesalahan konfigurasi, operasi akan gagal dengan pesan error yang menunjukkan penyebab 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 resource Secret Secret Manager dengan pesan yang menunjukkan alasan kegagalan publikasi.

Langkah selanjutnya