Menyiapkan notifikasi pada secret

Topik ini membahas dukungan untuk notifikasi peristiwa di Secret Manager.

Ringkasan

Notifikasi peristiwa mengirimkan informasi tentang perubahan versi secret dan 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 jika 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

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

Pesan Pub/Sub memiliki kumpulan key-value pair "atribut" yang berisi metadata tentang peristiwa, serta kolom "data" yang berisi serialisasi JSON lengkap dari resource Secret atau SecretVersion yang telah dibuat atau diubah. JSON ini adalah string berenkode UTF-8 yang merepresentasikan resource Secret atau SecretVersion, persis dalam bentuk yang ditentukan oleh API publik Secret Manager, yang dienkode dalam JSON seperti yang ditentukan dalam Pemetaan JSON proto3.

Jenis peristiwa

Berikut adalah daftar jenis peristiwa yang didukung oleh Secret Manager:

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 habisnya masa berlaku secret.
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 penghancuran dikonfigurasi pada secret dan pengguna mencoba menghancurkan versi secret.
SECRET_ROTATE Dikirim saat tiba waktunya untuk memutar 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. 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 secara rahasia, pesan TOPIC_CONFIGURED akan dikirim ke semua topik yang dirahasiakan, termasuk pesan 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 kumpulan key:value pair berikut, apa pun 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 rahasia tempat peristiwa terjadi.
timestamp 2021-01-20T11:17:45.081104-08:00 Waktu peristiwa itu 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 rahasia 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 rahasia (EXPIRATION). Hanya ada di notifikasi peristiwa SECRET_DELETE.

Data

Kolom data berupa string UTF-8 yang berisi metadata objek yang diubah. Data bisa berupa Versi Rahasia atau Rahasia.

Untuk notifikasi SECRET_DELETE, metadata yang dimuat dalam kolom data mewakili metadata objek seperti sebelum dihapus. Untuk semua notifikasi lainnya, metadata yang disertakan dalam kolom data merepresentasikan 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. Lengkapi prasyarat berikut untuk menyiapkan Secret Manager dan Pub/Sub:

  • Secret Manager:

    • Buat atau gunakan project yang sudah 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:

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

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 memberi akun layanan ini izin untuk memublikasikan 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 sepanjang waktu 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 hal ini beberapa kali jika Anda ingin membuat beberapa topik Pub/Sub secara rahasia.

Beri akun layanan izin Secret Manager untuk memublikasikan 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) pada 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 topik, Anda juga harus membuat langganan ke topik tersebut. Ikuti panduan memulai Pub/Sub untuk membuat langganan di project Pub/Sub 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 rahasia 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, Instal atau upgrade Google Cloud CLI ke versi 378.0.0 atau yang lebih baru terlebih dahulu. 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 cara menggunakan 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 secara rahasia dengan memperbarui secret dengan nama resource topik Pub/Sub baru. Dengan Google Cloud CLI, Anda dapat menambahkan atau menghapus satu atau beberapa topik dari suatu secret, serta menghapus semua topik dari secret.

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

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

Hapus topik

Hapus semua topik dari secret.

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

Menggunakan notifikasi peristiwa dengan Cloud Functions

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

C#

Untuk menjalankan kode ini, siapkan lingkungan pengembangan C# terlebih dahulu, lalu 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, lalu 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, baca 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, lalu 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, siapkan lingkungan pengembangan Python terlebih dahulu, lalu 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, lalu 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 Buat atau Update, tetapi Secret Manager tidak dapat memublikasikan pesan ke topik tersebut karena kesalahan konfigurasi, operasi akan gagal dengan pesan error yang menunjukkan alasan publikasi gagal. Hal ini dapat terjadi, misalnya, jika topik tidak ada, atau jika akun layanan Secret Manager tidak memiliki izin untuk melakukan publikasi.

Jika topik Pub/Sub ditambahkan ke secret, lalu topik 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 penyebab kegagalan publikasi.

Langkah selanjutnya