このページでは、Secret Manager でシークレットのイベント通知を構成して使用する方法について説明します。
概要
Secret Manager は Pub/Sub と統合されており、シークレットとシークレット バージョンの両方の変更に関するイベント通知を提供します。これらの通知を使用して、ワークフローを開始できます。たとえば、新しいシークレット バージョンが追加されたときにアプリケーションを再起動したり、シークレットが削除されたときにセキュリティ エンジニアに通知したりできます。これらの通知を使用してワークフローを開始する方法の詳細については、Pub/Sub のドキュメントをご覧ください。
Secret Manager でのイベント通知の仕組み
シークレットは、最大 10 個の Pub/Sub トピックのリストで構成できます。シークレットまたはそのバージョンの 1 つを変更するオペレーションが実行されるたびに、Secret Manager はそのシークレットのそれぞれの Pub/Sub トピックにメッセージを自動的にパブリッシュします。Get
、List
、Access
の呼び出しでは、メッセージはパブリッシュされません。
Pub/Sub メッセージには、イベントに関するメタデータを含む属性 Key-Value ペアのセットと、作成または変更された Secret
リソースまたは SecretVersion
リソースの完全な JSON シリアル化が含まれます。この JSON は、UTF-8 でエンコードされた文字列です。この文字列は、Secret Manager の公開 API(proto3 JSON マッピングで指定された JSON でエンコードされている)によって指定された形式で Secret
または SecretVersion
リソースを厳密に表しています。
イベントタイプ
Secret Manager でサポートされているイベントタイプのリストは次のとおりです。
イベントタイプ | 説明 |
---|---|
SECRET_CREATE |
新しいシークレットが正常に作成されると送信されます。 |
SECRET_UPDATE |
新しいシークレットが正常に更新されると送信されます。 |
SECRET_DELETE |
ユーザーによって開始されたリクエスト、またはシークレットの有効期限によってシークレットが削除されると送信されます。 |
SECRET_VERSION_ADD |
新しいシークレット バージョンが正常に追加されると送信されます。 |
SECRET_VERSION_ENABLE |
シークレット バージョンを有効にすると送信されます。 |
SECRET_VERSION_DISABLE |
シークレット バージョンが有効になると送信されます。 |
SECRET_VERSION_DESTROY |
シークレット バージョンを破棄すると送信されます。 |
SECRET_VERSION_DESTROY_SCHEDULED |
シークレットに破棄の遅延期間が構成され、ユーザーがシークレット バージョンを破棄しようとすると送信されます。 |
SECRET_ROTATE |
シークレットをローテーションするタイミングになると送信されます。詳細については、ローテーション スケジュールを作成するをご覧ください。 |
TOPIC_CONFIGURED |
これは、 オペレーションが成功した場合は、直後に シークレットでトピックが更新されるたびに、すでに存在しているトピックを含むすべてのシークレットのトピックに |
通知形式
Pub/Sub トピックに送信される通知は、次の 2 つの部分で構成されます。
-
属性: イベントを記述する Key-Value ペア。
-
データ: 変更されたオブジェクトのメタデータを含む文字列
属性
属性は、Secret Manager から Pub/Sub トピックに送信される通知に含まれる Key-Value ペアです。TOPIC_CONFIGURED
テスト メッセージ以外のすべての通知には、通知のデータに関係なく、常に次の Key-Value ペアのセットが含まれます。
例 | 説明 | |
---|---|---|
eventType |
SECRET_CREATE |
発生したイベントの種類。有効な値については、イベントの種類をご覧ください。 |
dataFormat |
JSON_API_V1 |
オブジェクト データの形式。 |
secretId |
projects/p/secrets/my-secret |
イベントが発生したシークレットの完全なリソース名。 |
timestamp |
2021-01-20T11:17:45.081104-08:00 |
イベントの発生時間。 |
また、次の Key-Value ペアのセットが通知に含まれる場合もあります。
例 | 説明 | |
---|---|---|
versionId |
projects/p/secrets/my-secret/versions/456 |
イベントが発生したシークレット バージョンの名前。
これは |
deleteType |
REQUESTED |
削除がユーザーによりリクエストされた(REQUESTED )か、シークレットの有効期限(EXPIRATION )により削除されたかのどちらか。SECRET_DELETE イベント通知のみに表示されます。 |
データ
データ フィールドは、変更されたオブジェクトのメタデータを含む UTF-8 文字列です。データはシークレットまたはシークレット バージョンのいずれかです。
SECRET_DELETE
通知の場合、データ フィールドに含まれるメタデータは、削除前のオブジェクトのメタデータを表します。それ以外の通知では、データ フィールドに含まれるメタデータは、変更発生後のオブジェクトのメタデータを表します。
制限事項
イベント通知は、Secret Manager v1 API と Google Cloud CLI でのみ使用できます。
始める前に
すべてのリソースを同じプロジェクトに保存することも、シークレットと Pub/Sub トピックを別のプロジェクトに保存することもできます。
-
Secret Manager を設定するには、次の操作を行います。
-
Secret Manager リソースを保持するプロジェクトを作成するか、既存のプロジェクトを使用します。
-
必要に応じて、Secret Manager API を有効にするページに記載されている手順を完了します。
-
-
Pub/Sub を設定する手順は次のとおりです。
-
Pub/Sub リソースを保持するプロジェクトを作成するか、既存のプロジェクトを使用します。
-
必要に応じて、Pub/Sub API を有効にします。
-
-
次のコマンドを使用して Google Cloud に対する認証を行います。
$ gcloud auth login --update-adc
サービス エージェント ID を作成する
イベント通知を使用するシークレットが必要なプロジェクトごとにサービス エージェント ID を作成するには、次の操作を行います。
-
Google Cloud CLI でサービス ID を作成するには、次のコマンドを実行します。
$ gcloud beta services identity create \ --service "secretmanager.googleapis.com" \ --project "PROJECT_ID"
このコマンドは、次の形式でサービス アカウント名を返します。
service-PROJECT_ID@gcp-sa-secretmanager.iam.gserviceaccount.com
-
シークレットに構成された Pub/Sub トピックに対してパブリッシュする権限を、このサービス アカウントに付与します。
-
次のコマンドを使用して、サービス アカウント名を環境変数として保存します。
# 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
後述のコマンドデータを使用する前に、次のように置き換えます。
- PROJECT_ID: シークレットを含む Google Cloud プロジェクト ID
- PUBSUB_PROJECT_ID: サブスクリプションを作成するプロジェクトの ID
- PUBSUB_TOPIC_NAME: トピックの名前
次のコマンドを実行します。
Linux、macOS、Cloud Shell
gcloud pubsub topics create "projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME"
Windows(PowerShell)
gcloud pubsub topics create "projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME"
Windows(cmd.exe)
gcloud pubsub topics create "projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME"
シークレットに複数の Pub/Sub トピックを作成する場合は、この手順を複数回繰り返します。
サービス アカウントに Secret Manager の権限を付与し、トピックで公開します。
Secret Manager サービス アカウントに権限を付与するには、Google Cloud コンソールまたは Google Cloud CLI を使用します。
Pub/Sub トピックに Pub/Sub パブリッシャーのロール(roles/pubsub.publisher
)を付与するには、次のコマンドを使用します。
gcloud
後述のコマンドデータを使用する前に、次のように置き換えます。
- PUBSUB_TOPIC_NAME: トピックの名前
次のコマンドを実行します。
Linux、macOS、Cloud Shell
gcloud pubsub topics create add-iam-policy-binding PUBSUB_TOPIC_NAME \ --member "serviceAccount:${SM_SERVICE_ACCOUNT}" \ --role "roles/pubsub.publisher"
Windows(PowerShell)
gcloud pubsub topics create add-iam-policy-binding PUBSUB_TOPIC_NAME ` --member "serviceAccount:${SM_SERVICE_ACCOUNT}" ` --role "roles/pubsub.publisher"
Windows(cmd.exe)
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_PROJECT_ID: サブスクリプションを作成するプロジェクトの ID
- PUBSUB_SUBSCRIPTION_NAME: サブスクリプションの名前
- PUBSUB_TOPIC_NAME: トピックの名前
次のコマンドを実行します。
Linux、macOS、Cloud Shell
gcloud pubsub subscriptions create projects/PUBSUB_PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_NAME \ --topic projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME
Windows(PowerShell)
gcloud pubsub subscriptions create projects/PUBSUB_PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_NAME ` --topic projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME
Windows(cmd.exe)
gcloud pubsub subscriptions create projects/PUBSUB_PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_NAME ^ --topic projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME
トピックが構成されたシークレットの作成
最大 10 個のトピックのリストを構成してシークレットを作成します。シークレットまたはシークレットのバージョンのいずれかが変更されると、シークレットで構成されているすべてのトピックがイベント通知を受信します。
gcloud
後述のコマンドデータを使用する前に、次のように置き換えます。
- SECRET_ID: シークレットの ID またはシークレットの完全修飾識別子
- PUBSUB_TOPIC_NAME: トピックの名前
- LOCATION: シークレットの Google Cloud ロケーション
次のコマンドを実行します。
Linux、macOS、Cloud Shell
gcloud secrets create SECRET_ID --topics PUBSUB_TOPIC_NAME --location=LOCATION
Windows(PowerShell)
gcloud secrets create SECRET_ID --topics PUBSUB_TOPIC_NAME --location=LOCATION
Windows(cmd.exe)
gcloud secrets create SECRET_ID --topics PUBSUB_TOPIC_NAME --location=LOCATION
シークレット トピックを更新する
新しい Pub/Sub トピックのリソース名でシークレットを更新し、シークレットで構成されている Pub/Sub トピックを変更します。Google Cloud CLI を使用すると、シークレットへの 1 つ以上のトピックの追加、またはシークレットからトピックの削除に加えて、シークレットからすべてのトピックの消去を行うことができます。
トピックの追加
シークレットに 1 つ以上のトピックを追加するには、次のコマンドを使用します。
gcloud
後述のコマンドデータを使用する前に、次のように置き換えます。
- SECRET_ID: シークレットの ID またはシークレットの完全修飾識別子
- LOCATION: シークレットの Google Cloud ロケーション
- PROJECT_ID: シークレットを含む Google Cloud プロジェクト ID
- PUBSUB_PROJECT_ID: サブスクリプションを作成するプロジェクトの ID
- PUBSUB_TOPIC_1_NAME、PUBSUB_TOPIC_2_NAME: シークレットに追加するトピックの名前
次のコマンドを実行します。
Linux、macOS、Cloud Shell
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
Windows(PowerShell)
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
Windows(cmd.exe)
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
トピックの削除
シークレットから 1 つ以上のトピックを削除するには、次のコマンドを使用します。
gcloud
後述のコマンドデータを使用する前に、次のように置き換えます。
- SECRET_ID: シークレットの ID またはシークレットの完全修飾識別子
- LOCATION: シークレットの Google Cloud ロケーション
- PROJECT_ID: シークレットが含まれる Google Cloud プロジェクト
- PUBSUB_PROJECT_ID: サブスクリプションを作成するプロジェクトの ID
- PUBSUB_TOPIC_1_NAME と PUBSUB_TOPIC_2_NAME: シークレットから削除するトピックの名前
次のコマンドを実行します。
Linux、macOS、Cloud Shell
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
Windows(PowerShell)
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
Windows(cmd.exe)
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
後述のコマンドデータを使用する前に、次のように置き換えます。
- SECRET_ID: シークレットの ID またはシークレットの完全修飾識別子
- PROJECT_ID: シークレットが含まれる Google Cloud プロジェクト
- LOCATION: シークレットの Google Cloud ロケーション
次のコマンドを実行します。
Linux、macOS、Cloud Shell
gcloud secrets update SECRET_ID --location=LOCATION \ --project PROJECT_ID \ --clear-topics
Windows(PowerShell)
gcloud secrets update SECRET_ID --location=LOCATION ` --project PROJECT_ID ` --clear-topics
Windows(cmd.exe)
gcloud secrets update SECRET_ID --location=LOCATION ^ --project PROJECT_ID ^ --clear-topics
Cloud Run 関数でのイベント通知の使用
イベント通知を使用すると、Pub/Sub メッセージを使用する Cloud Run 関数を作成し、ワークフローを開始できます。詳細については、Cloud Run functions のドキュメントをご覧ください。次のサンプルコードは、イベントがトピックに公開されるたびに eventType
、secretId
、メタデータを出力する Cloud Run 関数用です。
C#
このコードを実行するには、まず C# 開発環境を設定し、Secret Manager C# SDK をインストールします。 Compute Engine または GKE では、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
このコードを実行するには、まず Go 開発環境を設定し、Secret Manager Go SDK をインストールします。 Compute Engine または GKE では、cloud-platform スコープを使用して認証する必要があります。
Java
Secret Manager 用のクライアント ライブラリをインストールして使用する方法については、Secret Manager クライアント ライブラリをご覧ください。
Secret Manager に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Node.js
このコードを実行するには、まず Node.js 開発環境を設定し、Secret Manager Node.js SDK をインストールします。 Compute Engine または GKE では、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
このコードを実行するには、まず Python 開発環境を設定し、Secret Manager Python SDK をインストールします。 Compute Engine または GKE では、cloud-platform スコープを使用して認証する必要があります。
Ruby
このコードを実行するには、まず Ruby 開発環境を設定し、Secret Manager Ruby SDK をインストールします。 Compute Engine または GKE では、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
すべてのイベントタイプの一覧については、イベントタイプをご覧ください。
正しく構成されていないトピック
作成または更新オペレーションで Pub/Sub トピックがシークレットに追加されたものの、構成ミスにより Secret Manager がトピックにメッセージをパブリッシュできない場合、パブリッシュ エラーの理由を示すエラー メッセージが表示され、オペレーションは失敗します。たとえば、トピックが存在しない場合や、Secret Manager のサービス アカウントにパブリッシュの権限がない場合などに、このエラーが発生することがあります。
Pub/Sub トピックがシークレットに追加された後、トピックが変更され、Secret Manager がメッセージをパブリッシュできなくなった場合(トピックが削除された場合や、Secret Manager サービス アカウントの権限が削除された場合など)、Secret Manager は、パブリッシュが失敗した理由を示すメッセージを Secret Manager Secret
に書き込みます。