Set up notifications on a secret

This page explains how to configure and use event notifications for your secrets in Secret Manager.

Overview

Secret Manager integrates with Pub/Sub to provide event notifications for changes to both secrets and secret versions. You can use these notifications to initiate workflows, such as restarting an application when a new secret version is added, or notifying security engineers when a secret is deleted. For more information on how to use these notifications to start workflows, see the Pub/Sub documentation.

How event notifications work in Secret Manager

Secrets can be configured with a list of up to 10 Pub/Sub topics. Whenever an operation is performed that modifies the secret or one of its versions, Secret Manager automatically publishes a message to each of the Pub/Sub topics on that secret. Get, List, and Access calls don't result in message publications.

Pub/Sub messages have a set of attribute key-value pairs containing metadata about the event, as well as a data field containing a full JSON serialization of the Secret or SecretVersion resource which was created or modified. This JSON is a UTF-8 encoded string that represents the Secret or SecretVersion resource in exactly the form specified by the Secret Manager public API, encoded in JSON as specified in the proto3 JSON Mapping.

Event types

The following is a list of event types supported by Secret Manager.

Notification format

Notifications sent to the Pub/Sub topic consist of two parts:

• Attributes: A set of key-value pairs describing the event.

• Data: A string that contains the metadata of the changed object.

Attributes

Attributes are key-value pairs contained in notifications sent by Secret Manager to your Pub/Sub topic. All notifications other than TOPIC_CONFIGURED test messages always contain the following set of key:value pairs, regardless of the notification's data:

In addition, notifications sometimes contain the following set of key-value pairs:

Data

The data field is a UTF-8 string that contains the metadata of the changed object. Data is either a secret or secret version.

For SECRET_DELETE notifications, the metadata contained in the data field represents the object metadata as it was before the delete. For all other notifications, the metadata included in the data field represents the object metadata after the change occurs.

Limitations

• Event notifications is available only in the Secret Manager v1 API and Google Cloud CLI.

• You can't reliably use event notifications with Pub/Sub topics that have a message storage policy where enforceInTransit is set to true.

  Secret Manager publishes all event notifications from a global endpoint. If a Pub/Sub topic has enforceInTransit set to true, it restricts publishing to specific allowedPersistenceRegions. The regional restriction conflicts with the global publishing endpoint for Secret Manager, causing the publish request to fail with a FAILED_PRECONDITION error.

Before you begin

You may choose to store all resources in the same project or to store secrets and Pub/Sub topics in separate projects.

1. To set up Secret Manager, complete the following:

   • Create or use an existing project to hold your Secret Manager resources.

   • If necessary, complete the steps mentioned in the Enable the Secret Manager API page.

2. To set up Pub/Sub, complete the following:

   • Create or use an existing project to hold your Pub/Sub resources.

   • If necessary, enable the Pub/Sub API.

3. Authenticate to Google Cloud using the following command:

       $ gcloud auth login --update-adc
       

Create a service agent identity

To create a service agent identity for each project that requires secrets with event notifications, follow these steps:

1. To create a service identity with Google Cloud CLI, run the following command:

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

   This command returns a service account name, with the following format:

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

2. Grant this service account permission to publish on the Pub/Sub topics configured on your secrets.

3. Save the service account name as an environment variable using the following command:

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

The environment variables for the Secret Manager project, Pub/Sub project, and Secret Manager service account must be set the entire time you are following this procedure.

Create Pub/Sub topics

Follow the Pub/Sub quickstart to create topics in your Pub/Sub project in the Google Cloud console. Alternatively, create topics in the Google Cloud CLI using the following command:

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"

Repeat this multiple times if you want to create multiple Pub/Sub topics on the secret.

Grant the service account for Secret Manager permission to publish on the topics

You can grant permissions to the Secret Manager service account through the Google Cloud console or through Google Cloud CLI.

To grant the Pub/Sub Publisher role (roles/pubsub.publisher) on the Pub/Sub topic, use the following command:

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