Configuring Cloud 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 Cloud Pub/Sub.

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

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

Create a Cloud Pub/Sub topic

For each Container Registry project for which you'd like notifications, you need to create a Cloud Pub/Sub topic using a Cloud 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 GCP 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 Platform project ID.

Note: Previously, the qualified URI was formatted as projects/my-project/topics/us.gcr.io%2Fmy-project. As of September 18, 2017, this is deprecated.

To create a topic:

Console

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

   Go to the Cloud 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 GCP 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

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 Cloud Pub/Sub subscription

Every Cloud 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 Cloud Pub/Sub topics page in the GCP Console.

   Go to the Cloud 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 Cloud Pub/Sub permissions

You can use Cloud 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 Cloud Pub/Sub access controls in the GCP 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 Cloud 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 Cloud Pub/Sub documentation.
• For an in-depth explanation of Cloud Pub/Sub, see What is Cloud Pub/Sub?
• Learn more about Cloud Pub/Sub access control roles.