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 Artifact Analysis notifications for activity such as new vulnerability scan results, see the Artifact Analysis documentation.

Create a Pub/Sub topic

When you activate the Container Registry API in a Google Cloud project, Container Registry automatically creates a Pub/Sub topic with the topic ID gcr.

If the gcr topic was accidentally deleted or is missing, you can add it yourself. For example, the topic might be missing if your Google Cloud organization has an organization policy constraint that requires encryption with customer-managed encryption keys (CMEK). When the Pub/Sub API is in the deny list of this constraint, services cannot automatically create topics with Google-owned and Google-managed encryption keys.

To create the gcr topic with Google-owned and Google-managed encryption keys:

Console

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

   Go to the Pub/Sub topics page

2. Click Create Topic.

3. Enter the topic ID gcr.

4. Click Create Topic.

gcloud

Run the following command:

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, the topic gcr already exists in the project.

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

To create the gcr topic with CMEK encryption, see the Pub/Sub instructions for encrypting topics.

After you have have created the gcr topic or verified that it exists, you can create a subscription to the topic.

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 Google 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

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 Google 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. Principals that push images or delete images from the registry must have the pubsub.topics.publish permission to publish a message to Pub/Sub.

• 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.