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.

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.

When you create a topic, you need to use a qualified URI for your repository. The qualified URI is:

projects/[PROJECT-ID]/topics/gcr

where [PROJECT-ID] is your Google Cloud project ID.

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 a topic name with the URI:

    projects/[PROJECT-ID]/topics/gcr

    where [PROJECT-ID] is your Google Cloud project ID.

  4. Click Create.

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 projects/[PROJECT-ID]/topics/gcr

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

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