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.

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  
 "serviceAccount: 
 ${ 
 SM_SERVICE_ACCOUNT 
 } 
 " 
  
^  
--role  
 "roles/pubsub.publisher" 

Create Pub/Sub subscriptions

To view the messages published to a topic, you must also create a subscription to the topic. Follow the Pub/Sub quickstart to create subscriptions in your Pub/Sub project in the Google Cloud console. Alternatively, create topics in the Google Cloud CLI using the following command:

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 

Create a secret with topics configured

Create a secret with a list of up to 10 topics configured. All topics configured on a secret receive event notifications when the secret or one of its versions changes.

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\""
}

Update secret topics

Modify the Pub/Sub topics configured on a secret by updating the secret with the new Pub/Sub topic resource names. With Google Cloud CLI you can add or remove one or more topics from a secret, as well as clear all topics from the secret.

Add topics

To add one or more topics to a secret, use the following command:

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 

Remove topics

To remove one or more topics from a secret, use the following command:

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 

Clear topics

To remove all topics from a secret, use the following command:

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

Consume event notifications with Cloud Run functions

Event notifications can be used to initiate workflows by creating Cloud Run functions to consume the Pub/Sub messages. See the Cloud Run functions documentation for more information. The following sample code is for a Cloud Run function that prints eventType , secretId , and metadata whenever an event is published to the topic.

 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 

For a list of all event types, see Event Types .

Misconfigured topics

If Pub/Sub topics are added to a secret in a Create or Update operation but Secret Manager cannot publish messages to the topic due to a misconfiguration, the operation fails with an error message indicating why the publish failed. This could happen, for example, if the topic does not exist, or if the Secret Manager service account does not have permission to publish.

If Pub/Sub topics are added to a secret and then afterwards the topic is changed so that Secret Manager can no longer publish messages (for instance, the topic is deleted, or the Secret Manager service account permissions are removed), Secret Manager writes logs to the Secret Manager Secret with a message indicating why the publish failed.

What's next

• Learn how to analyze secrets with Cloud Asset Inventory .