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.

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