Como configurar notificações do Pub/Sub

Você pode receber notificações do Pub/Sub sobre as alterações em um repositório do Docker. As notificações se aplicam a qualquer imagem de contêiner armazenados no repositório, incluindo gráficos do Helm 3 empacotadas no formato OCI.

O Pub/Sub publica mensagens sobre os repositórios em recursos nomeados, chamados de tópicos. Os aplicativos que se inscrevem nos tópicos do Pub/Sub recebem essas mensagens e recebem notificações quando o estado de um repositório é alterado.

O Artifact Registry publica mensagens sobre as seguintes mudanças:

  • Uploads de imagens
  • Novas tags adicionadas às imagens
  • Exclusão de imagens

Além disso, é possível configurar papéis e permissões para publicar ou se inscrever para receber notificações.

Para mais informações sobre como configurar notificações do Artifact Analysis sobre atividades como novos resultados de verificação de vulnerabilidades, consulte a documentação do Artifact Analysis.

Visão geral

O Artifact Registry publica mensagens sobre alterações nos repositórios em um tópico chamado gcr.

Para receber notificações, é preciso:

  1. Crie um tópico chamado gcr no projeto com o Artifact Registry.
  2. Crie uma assinatura no tópico.
  3. Configure o aplicativo de assinante para receber mensagens sobre alterações no repositório.
  4. Se apropriado, configure permissões para controlar o acesso ao seu tópico e à sua assinatura.

Como criar o tópico do Artifact Registry

Quando você ativa a API Artifact Registry em um projeto do Google Cloud, o Artifact Registry cria automaticamente um tópico do Pub/Sub com o ID gcr. Se o Container Registry estiver ativado no mesmo projeto do Google Cloud, o tópico já poderá existir, já que os dois serviços de registro usam o mesmo tópico para publicar mensagens.

Se o tópico gcr estiver ausente ou tiver sido excluído acidentalmente, você poderá adicioná-lo você mesmo. Por exemplo, o tópico pode estar ausente se sua instância do Google Cloud organização tem uma restrição de política da organização que exige com chaves de criptografia gerenciadas pelo cliente (CMEK). Quando a API Pub/Sub está na lista de negação dessa restrição, os serviços não podem criar automaticamente tópicos com chaves gerenciadas e de propriedade do Google.

Para visualizar uma lista de tópicos existentes, consulte o Página de tópicos do Pub/Sub no console do Google Cloud ou execute o seguinte comando:

gcloud pubsub topics list

Para criar o tópico gcr com chaves de propriedade e gerenciadas pelo Google:

Console

  1. Acesse a página de tópicos do Pub/Sub no console do Google Cloud.

    Acesse a página de tópicos do Cloud Pub/Sub

  2. Clique em Criar tópico.

  3. Digite o código do tópico gcr.

  4. Clique em Criar tópico.

gcloud

Execute este comando:

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

Substitua PROJECT-ID pelo ID do projeto do Google Cloud. Se você omitir a flag --project, o comando usará o projeto atual.

Para saber mais sobre o comando gcloud pubsub topics, consulte a documentação de topics.

Para criar o tópico gcr com criptografia CMEK, consulte as instruções do Pub/Sub para criptografar tópicos.

Depois de criar o tópico gcr ou verificar se ele existe, será possível criar uma assinatura para o tópico.

Como criar uma assinatura

Depois de criar um tópico para alterações no repositório, você pode configurar uma assinatura nele que use entrega por push ou entrega por pull. Recomendamos o uso da entrega por pull, porque os sistemas de CI/CD podem gerar inúmeras alterações em artefatos armazenados, e a entrega por pull é mais eficaz para um grande volume de mensagens.

Para criar uma assinatura com entrega por pull:

Console

  1. Acesse a página de tópicos do Pub/Sub no console do Google Cloud.

    Acesse a página de tópicos do Cloud Pub/Sub

  2. Clique no tópico do projeto.

  3. Clique em Criar assinatura.

  4. Insira o nome da assinatura:

    projects/PROJECT/subscriptions/[SUBSCRIPTION-NAME]

    Deixe o Tipo de entrega configurado como Pull.

  5. Clique em Criar.

gcloud

Execute este comando:

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

Substitua SUBSCRIPTION-NAME por um nome para a assinatura

Para saber mais sobre o comando gcloud pubsub subscriptions, consulte a documentação de subscriptions.

Agora você tem uma assinatura do tópico gcr. A próxima etapa é configurar permissões para as identidades que acionam alterações nos repositórios.

Como configurar o aplicativo de assinante

Depois de criar um tópico e uma assinatura para ele, é possível configurar seu aplicativo de assinante, que recebe mensagens sobre alterações nos repositórios. Os aplicativos de assinante realizam tarefas como: notificações de eventos, geração de registros do sistema e comunicação entre aplicativos.

Quando um usuário de repositório envia ou exclui uma imagem, as seguintes etapas ocorrem:

  1. A conta de serviço do Artifact Registry publica a alteração no seu tópico gcr. A conta de serviço é service-PROJECT-NUMBER@gcp-sa-artifactregistry.iam.gserviceaccount.com, em que PROJECT-NUMBER é o número do projeto do Google Cloud. O A conta de serviço do Artifact Registry tem o pubsub.topics.publish permissão por padrão para que possa publicar alterações em seu tópico.

    Se um administrador tiver revogado as permissões pubsub.topics.publish da conta de serviço do Artifact Registry, o Artifact Registry tentará publicar a mensagem como o usuário do repositório. Nessa situação, a conta do usuário do repositório precisa ter a permissão pubsub.topics.publish para publicar a mensagem.

  2. O Pub/Sub encaminha a mensagem do tópico para sua assinatura.

  3. Quando seu aplicativo de assinante solicita mensagens, ele extrai a nova mensagem da assinatura.

    A identidade que extrai mensagens em nome do assinante precisa ter permissões para acessar a assinatura. Use o papel de assinante do Pub/Sub para conceder essas permissões.

Para saber como configurar um assinante para receber mensagens de uma assinatura com entrega por pull, consulte Como receber mensagens usando pull.

Como configurar permissões

É possível usar permissões do Pub/Sub para controlar o acesso aos seus tópicos e suas assinaturas.

Para mais informações sobre permissões do Pub/Sub e concessão de acesso a tópicos e assinaturas, consulte a documentação de controle de acesso do Pub/Sub.

Exemplos de notificação

O Pub/Sub envia notificações como strings formatadas em JSON. Analise os exemplos a seguir para saber o que esperar ao receber notificações do Artifact Registry do Pub/Sub.

Quando uma imagem é enviada para o Container Registry, o payload da notificação pode ter o seguinte aspecto:

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

Quando uma nova tag de imagem é enviada para o Artifact Registry, o payload da notificação tem esta aparência:

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

A mensagem identifica a imagem relevante usando uma tecla digest ou tag.

Quando uma tag de imagem é excluída do Artifact Registry, o payload da notificação pode ter o seguinte aspecto:

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

A mensagem pode conter DELETE ou INSERT como valores para a tecla action.

A seguir