Configuring Pub/Sub notifications

You can receive notifications from Pub/Sub for the changes to a Docker repository. Notifications apply to any container image stored in the repository, including Helm 3 charts packaged in OCI format.

Pub/Sub publishes messages about your repositories to named resources called topics. Applications that subscribe to Pub/Sub topics receive these messages and receive notifications when a repository's state changes.

Artifact Registry publishes messages for the following changes:

  • Image uploads
  • New tags added to images
  • Image deletion

Additionally, you can configure roles and permissions for publishing or subscribing to notifications.

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

Overview

Artifact Registry publishes messages about changes to repositories in a topic named gcr.

To receive notifications, you must:

  1. Create a topic named gcr in the project with Artifact Registry.
  2. Create a subscription to the topic.
  3. Set up your subscriber application to receive messages about repository changes.
  4. If appropriate, configure permissions to control access to your topic and subscription.

Creating the Artifact Registry topic

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.

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.

Creating a subscription

After you have created a topic for repository changes, you can configure a subscription to it that uses either push delivery or pull delivery. We recommend using pull delivery since CI/CD systems can generate numerous changes to stored artifacts, and pull delivery is more effective for a large volume of messages.

To create a subscription with pull delivery:

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/subscriptions/[SUBSCRIPTION-NAME]

    Leave Delivery Type set to Pull.

  5. Click Create.

gcloud

Run the following command:

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

Replace SUBSCRIPTION-NAME with a name for the subscription

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

You now have a subscription to the gcr topic. The next step is configuring permissions for the identities that trigger changes in repositories.

Configuring your subscriber application

After you have created a topic and a subscription to that topic, you can set up your subscriber application, the application that receive messages about changes to repositories. Subscriber applications fulfill tasks like event notifications, system logging, and communication between applications.

When a repository user pushes or deletes an image, the following steps occur:

  1. The Artifact Registry service account publishes the change to your gcr topic. The service account is service-PROJECT-NUMBER@gcp-sa-artifactregistry.iam.gserviceaccount.com, where PROJECT-NUMBER is your Google Cloud project number. The Artifact Registry service account has the pubsub.topics.publish permission by default so that it can publish changes to your topic.

    If an administrator has revoked the pubsub.topics.publish permissions for the Artifact Registry service account, Artifact Registry attempts to publish the message as the repository user. In this situation, the repository user's account must have the pubsub.topics.publish permission to successfully publish the message.

  2. Pub/Sub forwards the message from the topic to your subscription.

  3. When your subscriber application makes a request for messages, it pulls the new message from the subscription.

    The identity that pulls messages on behalf of the subscriber must have permissions to access the subscription. You can use the Pub/Sub Subscriber role to grant this permission.

To learn about setting up a subscriber to receive messages from a subscription with pull delivery, see Receiving messages using Pull.

Configuring permissions

You can use Pub/Sub permissions to control access to your topics and subscriptions.

For more information about Pub/Sub permissions and granting access to topics and subscriptions, see the Pub/Sub access control documentation.

Notification examples

Pub/Sub sends notifications as JSON-formatted strings. Review the following examples to learn what to expect when receiving Artifact Registry notifications from Pub/Sub.

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

{
  "action":"INSERT",
  "digest":"us-east1-docker.pkg.dev/my-project/my-repo/hello-world@sha256:6ec128e26cd5..."
}

When a new image tag is pushed to Artifact Registry, the notification payload looks like this:

{
  "action":"INSERT",
  "digest":"us-east1-docker.pkg.dev/my-project/my-repo/hello-world@sha256:6ec128e26cd5...",
  "tag":"us-east1-docker.pkg.dev/my-project/my-repo/hello-world:1.1"
}

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

When an image tag is deleted from Artifact Registry, the notification payload might look like this:

{
  "action":"DELETE",
  "tag":"us-east1-docker.pkg.dev/my-project/my-repo/hello-world:1.1"
}

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

What's next