Configure Pub/Sub notifications for Cloud Storage (original) (raw)

Skip to main content

• Technology areas

  • Overview
  • Guides
  • Reference
  • Samples
  • Resources
  • Storage Intelligence dashboards

• Cross-product tools

• Console

• Discover

• Product overview

• Storage Intelligence overview

• Get started

• Terraform support for Cloud Storage

• Set up storage

• About buckets

• Create a bucket

• Bucket locations

• Storage classes

• Folder types

• Domain-named bucket verification

• Store data

• About objects

• Upload objects

  • About object uploads
  • Upload objects from files
  • Upload objects from memory
  • XML API multipart uploads
  • Parallel composite uploads
  • Streaming uploads

• Copy, rename, or move objects

• Object transcoding

• Manage buckets

• List buckets

• Move data between buckets

• Change the default storage class of a bucket

• Delete buckets

• Access data

• Folder types in Cloud Storage

• List objects

• Access public data

• Send batched requests

• Analyze data storage

• Analyze stored data with Gemini Cloud Assist

• Optimize

• Optimize AI/ML and analytics with Cloud Storage Rapid

• AI zones

• Built-in caching

• Directory data structure

  • About hierarchical namespace
  • About folders in buckets with hierarchical namespace enabled
  • Create buckets with hierarchical namespace enabled
  • Create and manage folders
  • Rename and move folders
  • Use hierarchical namespace-enabled buckets for Hadoop workloads
  • Optimize performance when using hierarchical namespace

• Request rate and access distribution guidelines

• Mount buckets using Cloud Storage FUSE

• About Cloud Storage FUSE

• Quickstart to Cloud Storage FUSE

• Install Cloud Storage FUSE

• Mount buckets as a file system

• Performance

  • Performance tuning best practices
  • Profile-based configurations for AI/ML workloads
  • Automated configuration values for high-performance machine types
  • Use pre-configured GKE YAML files to optimize Cloud Storage FUSE performance

• Authenticate and manage requests

• Authenticate to Cloud Storage

• Access data on a user's behalf

• OAuth 2.0 scopes

• Retry requests

• Use long-running operations

• Paginate results

• URI wildcards

• Secure and control access

• About access control in Cloud Storage

• Make data public

• Bucket IP filtering

  • About bucket IP filtering
  • Create a bucket with IP filtering rules
  • Create or update IP filtering rules on a bucket
  • Get IP bucket filtering rules
  • List bucket IP filtering rules
  • Delete bucket IP filtering rules
  • Disable bucket IP filtering
  • Bypass bucket IP filtering rules

• Protection, backup, and recovery

• Data protection, backup, and recovery options

• Recover deleted data

  • About soft delete
  • Set and manage soft delete policies
  • Restore soft-deleted objects
  • Restore soft-deleted buckets
  • Set a default soft delete retention duration
  • Use soft delete recommendations
  • Disable soft delete

• Monitor

• Use Cloud Logs with storage batch operations

• Usage logs and storage logs

• Use gRPC client-side metrics

• Use client-side traces

• Migrate and integrate

• Best practices for media workloads

• Use Cloud Storage with big data

• Integration with Google Cloud services and tools

• Use the Cloud Storage MCP server

• Connect LLMs with MCP toolbox for databases

• Interoperability

• Troubleshoot

• Troubleshoot common issues

• Troubleshoot Storage Insights issues

• Troubleshoot Cloud Storage FUSE issues

Configure Pub/Sub notifications for Cloud Storage

Overview

This page describes how to configure your bucket to send notifications about object changes to a Pub/Sub topic. For information on subscribing to a Pub/Sub topic that receives notifications, seeChoose a subscription type.

Before you begin

Before using this feature, complete the following instructions.

Enable the Pub/Sub API

Enable the Pub/Sub API for the project that will receive notifications.

Enable the API

Make sure you have an existing Pub/Sub topic

If you haven't already, create a Pub/Sub topic to which you want to send notifications. This step is not necessary if you plan on using the Google Cloud CLI or Terraform to perform the instructions on this page.

Get required roles

IAM role requirements differ depending on whether you'reconfiguring the notification or delivering the event data:

• If you use the Google Cloud CLI or Terraform to configure a notification, your identity only needs permissions to update bucket metadata and view the Pub/Sub topic. To get all the permissions required, follow the instructions inGet roles for viewing bucket metadata and the Pub/Sub topic.
• If your Cloud Storage service agent is delivering notifications, it must have the Pub/Sub Publisher role (roles/pubsub.publisher) on the Pub/Sub topic. Once this role is configured for the service agent, the service agent acts as a background "worker" to push events to your topic.
  To grant your service agent the permissions required to push event notifications to your topic, follow the instructions inGrant roles to your project's service agent.

Get roles for viewing bucket metadata and the Pub/Sub topic

To get the permissions that you need to configure and view Pub/Sub notifications for a bucket, ask your administrator to grant you the following roles. These predefined roles contain the permissions required to configure and view Pub/Sub notifications.

• Storage Admin (roles/storage.admin) role on the bucket for which you want to configure Pub/Sub notifications
• Pub/Sub Admin (roles/pubsub.admin) role on the project in which you want to receive Pub/Sub notifications

You might be able to get these permissions with other predefined roles orcustom roles.

See Set and manage IAM policies on buckets for instructions on granting roles on buckets. See Controlling access for instructions on granting roles on projects and setting access controls for topics and subscriptions.

Grant required role to your project's service agent

This section shows you how to grant the permissions required for your service agent to deliver notifications.

1. Get the email address of the service agent associated with the project that contains your Cloud Storage bucket. The service agent email address follows the format:

service-PROJECT_NUMBER@gs-project-accounts.iam.gserviceaccount.com  

1. Grant the service agent the Pub/Sub Publisher (roles/pubsub.publisher) role for the relevant Pub/Sub topic. See Controlling access for instructions on granting roles for topics.

Apply a notification configuration

The following steps add a notification configuration to your bucket that sends notifications for all supported events.

Console

You cannot manage Pub/Sub notifications with the Google Cloud console. Use the gcloud CLI or one of the available client libraries instead.

Command line

Use the gcloud storage buckets notifications create command:

gcloud storage buckets notifications create gs://BUCKET_NAME --topic=TOPIC_NAME

Where:

• BUCKET_NAME is the name of the relevant bucket. For example, my-bucket.
• TOPIC_NAME is the Pub/Sub topic to send notifications to. If you specify a topic that doesn't exist in your project, the command creates one for you.

To send notifications for a subset of events, include the--event-types flag.

Client libraries

C++

For more information, see theCloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

C#

For more information, see theCloud Storage C# API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Go

For more information, see theCloud Storage Go API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Java

For more information, see theCloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Node.js

For more information, see theCloud Storage Node.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

PHP

For more information, see theCloud Storage PHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To create a notification configuration for a bucket using PHP, see the Google Cloud Client Library reference documentation.

Python

For more information, see theCloud Storage Python API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Ruby

For more information, see theCloud Storage Ruby API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Terraform

You can use a Terraform resource to add a notification configuration to a bucket.

REST APIs

JSON API

1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.
2. Create a JSON file that contains the following information:
   {
   "topic": "projects/PROJECT_ID/topics/TOPIC_NAME",
   "payload_format": "JSON_API_V1"
   }
   Where:
   • PROJECT_ID is the ID for the project associated with the Pub/Sub topic that you want to send notifications to. For example, my-pet-project.
   • TOPIC_NAME is the Pub/Sub topic to send notifications to. For example, my-topic.
     To send notifications for a subset of events, include theevent_types field in the body of your JSON request.
3. Use cURL to call the JSON API with aPOST notificationConfigs request:
   curl -X POST --data-binary @JSON_FILE_NAME \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/notificationConfigs"
   Where:
   • JSON_FILE_NAME is the path for the file that you created in Step 2.
   • BUCKET_NAME is the name of the bucket you want notifications to be generated for. For example, my-bucket.

XML API

You cannot manage Pub/Sub notifications with the XML API.

Apply a notification configuration across projects

Your bucket might be in a different project than the Pub/Sub topic you want to send notifications to. For example, your bucket might be in Project A while the Pub/Sub topic is in Project B. In this scenario, ensure the following:

• In Project B, grant the Pub/Sub Publisher role (roles/pubsub.publisher) to Project A's Cloud Storage service agent on the target topic. For more details, seeGrant required permission to service agent.
• When creating the notification configuration in Project A, provide the full path to the topic in Project B. For example:

projects/PROJECT_B_ID/topics/TOPIC_NAME  

Get a notification configuration

To get a specific notification configuration that's associated with your bucket, complete the following steps:

Console

You cannot manage Pub/Sub notifications with the Google Cloud console. Use the Google Cloud CLI or one of the available client libraries instead.

Command line

Use the gcloud storage buckets notifications describe command:

gcloud storage buckets notifications describe projects/_/buckets/BUCKET_NAME/notificationConfigs/NOTIFICATION_ID

Where:

• BUCKET_NAME is the name of the bucket whose notification configuration you want to retrieve For example,my-bucket.
• NOTIFICATION_ID is the ID number of the relevant configuration. For example, 5.

If successful, the response looks similar to the following example:

etag: '132' id: '132' kind: storage#notification payload_format: JSON_API_V1 selfLink: https://www.googleapis.com/storage/v1/b/my-bucket/notificationConfigs/132 topic: //pubsub.googleapis.com/projects/my-project/topics/my-bucket

Client libraries

C++

For more information, see theCloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

C#

For more information, see theCloud Storage C# API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Go

For more information, see theCloud Storage Go API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Java

For more information, see theCloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Node.js

For more information, see theCloud Storage Node.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

PHP

For more information, see theCloud Storage PHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To get a notification configuration for a bucket using PHP, see the Google Cloud Client Library reference documentation.

Python

For more information, see theCloud Storage Python API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Ruby

For more information, see theCloud Storage Ruby API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

REST APIs

JSON API

1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.
2. Use cURL to call the JSON API with aGET notificationConfigs request:
   curl -X GET \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/notificationConfigs/NOTIFICATION_ID"
   Where:
   • BUCKET_NAME is the name of the bucket whose notification configuration you want to retrieve. For example, my-bucket.
   • NOTIFICATION_ID is the ID number of the notification configuration you want to retrieve. For example, 5.

XML API

You cannot manage Pub/Sub Notifications with the XML API.

List notification configurations for a bucket

To list all the notification configurations associated with a particular bucket:

Console

You cannot manage Pub/Sub notifications with the Google Cloud console. Use the gcloud CLI or one of the available client libraries instead.

Command line

Use the gcloud storage buckets notifications list command:

gcloud storage buckets notifications list gs://BUCKET_NAME

Where BUCKET_NAME is the name of the bucket whose notification configurations you want to list. For example,my-bucket.

Client libraries

C++

For more information, see theCloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

C#

For more information, see theCloud Storage C# API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Go

For more information, see theCloud Storage Go API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Java

For more information, see theCloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Node.js

For more information, see theCloud Storage Node.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

PHP

For more information, see theCloud Storage PHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To list notification configurations associated with a bucket using PHP, see the Google Cloud Client Library reference documentation.

Python

For more information, see theCloud Storage Python API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Ruby

For more information, see theCloud Storage Ruby API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

REST APIs

Remove a notification configuration

To remove an existing notification configuration from your bucket:

Console

You cannot manage Pub/Sub notifications with the Google Cloud console. Use the gcloud CLI or one of the available client libraries instead.

Command line

Use the gcloud storage buckets notifications delete command:

gcloud storage buckets notifications delete projects/_/buckets/BUCKET_NAME/notificationConfigs/NOTIFICATION_ID

Where:

• BUCKET_NAME is the name of the bucket whose notification configuration you want to delete. For example,my-bucket.
• NOTIFICATION_ID is the ID number of the configuration you want to delete. For example, 5.

If successful, the response looks similar to the following example:

Completed 1

Once sent, it might take up to 30 seconds for all notifications triggered by the notification configuration to stop.

Client libraries

C++

For more information, see theCloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

C#

For more information, see theCloud Storage C# API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Go

For more information, see theCloud Storage Go API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Java

For more information, see theCloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Node.js

For more information, see theCloud Storage Node.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

PHP

For more information, see theCloud Storage PHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To delete a notification configuration for a bucket using PHP, see the Google Cloud Client Library reference documentation.

Python

For more information, see theCloud Storage Python API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Ruby

For more information, see theCloud Storage Ruby API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Terraform

To remove the notification configuration you created, runterraform destroy from the folder containing your Terraform file.

REST APIs

JSON API

1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.
2. Use cURL to call the JSON API with aDELETE notificationConfigs request:
   curl -X DELETE \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/notificationConfigs/NOTIFICATION_ID"
   Where:
   • BUCKET_NAME is the name of the bucket whose notification configuration you want to delete. For example, my-bucket.
   • NOTIFICATION_ID is the ID number of the notification configuration you want to delete. For example, 5.

Once sent, it may take up to 30 seconds for all notifications triggered by the notification configuration to stop.

XML API

You cannot manage Pub/Sub notifications with the XML API.

What's next

• Learn more aboutPub/Sub notifications for Cloud Storage.
• Create a subscription in Pub/Sub to view notifications sent by Cloud Storage.
• See a Python example app that polls for notifications on GitHub.
• Use Cloud Run functions to deliver events with a Cloud Storage trigger.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-06-15 UTC.