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 Container Analysis notifications for activity such as new vulnerability scan results, see the Container Analysis documentation.
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.
To create a topic:
Console
Go to the Pub/Sub topics page in the Cloud Console.
Click Create Topic.
Enter the ID
gcr
.Click Create Topic.
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 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.
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
Go to the Pub/Sub topics page in the Cloud Console.
Click your project's topic.
Click Create Subscription.
Enter a subscription name:
projects/[PROJECT-ID]/subscriptions/[SUBSCRIPTION-NAME]
Leave Delivery Type set to Pull.
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
- 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.