配置 Pub/Sub 通知

您可以接收 Pub/Sub 发送的有关 Docker 代码库更改的通知。通知适用于存储在代码库中的任何容器映像，包括以 OCI 格式打包的 Helm 3 图表。

Pub/Sub 会将代码库相关的消息发布到名为主题的指定资源上。订阅 Pub/Sub 主题的应用会收到这些消息，并在代码库的状态发生更改时收到通知。

Artifact Registry 会发布关于以下更改的消息：

• 映像上传
• 已向映像添加了新标记
• 删除映像

此外，您还可以配置角色和权限来发布或订阅通知。

如需了解如何为活动（例如新的漏洞扫描结果）配置 Artifact Analysis 通知，请参阅 Artifact Analysis 文档。

概览

Artifact Registry 会发布主题 gcr 中有关代码库更改的消息。

要接收通知，您必须：

1. 使用 Artifact Registry 在项目中创建主题 gcr。
2. 创建对主题的订阅。
3. 设置订阅者应用以接收有关代码库更改的消息。
4. 在适当的情况下配置权限，以控制对主题和订阅的访问权限。

创建 Artifact Registry 主题

在 Google Cloud 项目中激活 Artifact Registry API 时，Artifact Registry 会自动创建主题 ID 为 gcr 的 Pub/Sub 主题。如果在同一 Google Cloud 项目中启用了 Container Registry，则该主题可能已经存在，因为这两项注册表服务使用同一主题来发布消息。

如果 gcr 主题被意外删除或缺失，您可以自行添加。例如，如果您的 Google Cloud 组织的组织政策限制条件要求使用客户管理的加密密钥 (CMEK) 进行加密，则此主题可能缺失。当 Pub/Sub API 位于此限制条件的拒绝列表中时，服务无法自动使用 Google 拥有的密钥和 Google 管理的密钥创建主题。

如需查看现有主题的列表，您可以查看 Google Cloud 控制台中的 Pub/Sub 主题页面或运行以下命令：

gcloud pubsub topics list

如需使用 Google 拥有的密钥和 Google 管理的密钥创建 gcr 主题，请执行以下操作：

控制台

1. 转到 Google Cloud 控制台中的 Pub/Sub 主题页面。

   转到 Pub/Sub 主题页面

2. 点击创建主题。

3. 输入主题 ID gcr。

4. 点击创建主题。

gcloud

运行以下命令：

gcloud pubsub topics create gcr --project=PROJECT-ID

将 PROJECT-ID 替换为您的 Google Cloud 项目 ID。如果您省略 --project 标志，命令会使用当前项目。

注意 ：如果此命令返回“项目中已存在该资源”错误，则表示项目中已存在主题 gcr。

如需详细了解 gcloud pubsub topics 命令，请参阅 topics 文档。

如需创建使用 CMEK 加密的 gcr 主题，请参阅 Pub/Sub 主题加密说明。

创建 gcr 主题或验证其存在后，您可以创建对该主题的订阅。

创建订阅

为代码库更改创建主题后，您可以配置对该主题的订阅，其使用推送传送或拉取传送。我们建议使用拉取传送，因为 CI/CD 系统可以对存储的工件产生大量更改，而拉取传送对于大量消息来说会更有效。

如需创建采用拉取传送的订阅，请执行以下操作：

控制台

1. 转到 Google Cloud 控制台中的 Pub/Sub 主题页面。

   转到 Pub/Sub 主题页面

2. 点击项目的主题。

3. 点击创建订阅。

4. 输入订阅名称：

   projects/PROJECT/subscriptions/[SUBSCRIPTION-NAME]
   

   将传送类型设置保留为拉取。

5. 点击创建。

gcloud

运行以下命令：

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

将 SUBSCRIPTION-NAME 替换为订阅的名称。

注意：可以使用可选 --ack-deadline 标志来配置系统在重试传送前等待订阅者确认的秒数。如果没有使用此标志，默认时限为 10 秒。

如需详细了解 gcloud pubsub subscriptions 命令，请参阅 subscriptions 文档。

您已订阅 gcr 主题。下一步是为触发代码库更改的身份配置权限。

配置订阅者应用

创建主题并订阅该主题后，您可以设置订阅者应用，即接收关于代码库更改的消息的应用。订阅者应用将执行事件通知、系统日志记录和应用间通信等任务。

代码库用户推送或删除映像时，会执行以下步骤：

1. Artifact Registry 服务账号会发布对 gcr 主题的更改。服务账号是 [e-mail]，其中，PROJECT-NUMBER 是 Google Cloud 项目编号。Artifact Registry 服务帐号默认具有 pubsub.topics.publish 权限，因此可以发布对您的主题所做的更改。

   如果管理员已撤消 Artifact Registry 服务帐号的 pubsub.topics.publish 权限，Artifact Registry 会尝试以代码库用户的身份发布消息。在这种情况下，代码库用户的帐号必须具有 pubsub.topics.publish 权限才能成功发布消息。

2. Pub/Sub 将消息从主题转发到您的订阅。

3. 当订阅者应用请求接收消息时，它会从订阅中拉取新消息。

   代表订阅者拉取消息的身份必须具有访问订阅的权限。您可以使用 Pub/Sub 订阅者角色授予此权限。

如需了解如何设置订阅者以便从使用拉取传送的订阅接收消息，请参阅使用拉取接收消息。

配置权限

您可以使用 Pub/Sub 权限来控制对主题和订阅的访问权限。

如需详细了解 Pub/Sub 权限以及如何授予对主题和订阅的访问权限，请参阅 Pub/Sub 的访问权限控制文档。

通知示例

Pub/Sub 以 JSON 格式字符串形式发送通知。请查看以下示例，了解从 Pub/Sub 接收 Artifact Registry 通知时会发生什么情况。

将映像推送到 Artifact Registry 时，通知载荷可能如下所示：

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

将新映像标记推送到 Artifact Registry 时，通知载荷如下所示：

{
  "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"
}

该消息使用 digest 或 tag 键标识相关映像。

从 Artifact Registry 中删除映像标记时，通知载荷可能如下所示：

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

该消息可能包含 DELETE 或 INSERT 作为 action 键值。

后续步骤

• 阅读 Pub/Sub 文档。
• 如需深入了解 Pub/Sub，请参阅什么是 Pub/Sub？
• 详细了解 Pub/Sub 访问权限控制角色。