Configuring Pub/Sub notifications

When changes are made to your Container Registry repository, such as when images are pushed, tagged, or deleted, you can receive notifications using Pub/Sub.

Pub/Sub publishes messages about your repository to named resources called topics. These messages are received by applications subscribed to Pub/Sub topics. Subscriber applications send notifications when your repository's state changes.

Additionally, you can configure roles and permissions for your Pub/Sub topics to control how users interact with your repository.

To support the transition from Container Registry to Artifact Registry, Artifact Registry publishes messages to the same topic as Container Registry.

For information about configuring Container Analysis notifications for activity such as new vulnerability scan results, see the Container Analysis documentation.

Create a Pub/Sub topic

For each Container Registry project for which you'd like notifications, you need to create a Pub/Sub topic using a Pub/Sub publisher application.

A publisher application sends messages to your repository's topic when your repository's state changes. You can create a topic using either the Cloud Console or the gcloud command-line tool.

To create a topic:

Console

1. Go to the Pub/Sub topics page in the Cloud Console.

   Go to the Pub/Sub topics page

2. Click Create Topic.

3. Enter the ID gcr.

4. Click Create Topic.

gcloud

From the system where Docker images are pushed or tagged, run the following command in your shell or terminal window:

gcloud pubsub topics create gcr --project=PROJECT-ID

Replace PROJECT-ID with your Google Cloud project ID. If you omit the --project flag, the command uses the current project.

Note: If this command returns a "Resource already exists in the project" error, you may already have a Container Registry topic.

To learn more about the gcloud pubsub topics command, see the topics documentation.

Create a Pub/Sub subscription

Every Pub/Sub topic should have a subscription.

A subscriber application receives messages from your repository's topic. Subscribers fulfill tasks like event notifications, system logging, and communication between applications.

Subscriptions can be configured to use a push model or a pull model.

To create a subscription:

Console

1. Go to the Pub/Sub topics page in the Cloud Console.

   Go to the Pub/Sub topics page

2. Click your project's topic.

3. Click Create Subscription.

4. Enter a subscription name:

   projects/[PROJECT-ID]/subscriptions/[SUBSCRIPTION-NAME]
   

   Leave Delivery Type set to Pull.

5. Click Create.

gcloud

From the system where Docker images are pushed or tagged run the following command:

gcloud pubsub subscriptions create [SUBSCRIPTION-NAME] --topic=gcr

Note: Use the optional flag --ack-deadline to configure how many seconds the system will wait for acknowledgement from the subscriber before re-attempting delivery. Without this flag, the default deadline is 10 seconds.

To learn more about the gcloud pubsub subscriptions command, see the subscriptions documentation.

Configuring Pub/Sub permissions

You can use Pub/Sub access control to configure permissions for your project and resources. Access controls keep your repository secure and allow you to manage user permissions using role-based access.

You can configure Pub/Sub access controls in the Cloud Console's IAM page or via the IAM API.

• To configure permissions for publishing, use any of the following roles: owner, editor, pubsub.admin, pubsub.editor, pubsub.publisher

• To configure permissions for subscribing, use any of the following roles: owner, editor, pubsub.admin, pubsub.editor, pubsub.subscriber

Notification examples

Notifications are sent as JSON-formatted strings. Below are examples of what to expect when receiving Container Registry notifications from Pub/Sub.

When an image is pushed to Container Registry, the notification payload might look like this:

{
  "action":"INSERT",
  "digest":"gcr.io/my-project/hello-world@sha256:6ec128e26cd5..."
}

When a new tag is pushed to Container Registry, the notification payload might look like this:

{
  "action":"INSERT",
  "digest":"gcr.io/my-project/hello-world@sha256:6ec128e26cd5...",
  "tag":"gcr.io/my-project/hello-world:1.1"
}

The message identifies the relevant image using either a digest or tag key.

When a tag is deleted from Container Registry, the notification payload might look like this:

{
  "action":"DELETE",
  "tag":"gcr.io/my-project/hello-world:1.1"
}

The message might contain either DELETE or INSERT as values for the action key.

What's next

• Read the Pub/Sub documentation.
• For an in-depth explanation of Pub/Sub, see What is Pub/Sub?
• Learn more about Pub/Sub access control roles.