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 armazenada no repositório, incluindo gráficos Helm 3 empacotados 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 informações sobre como configurar notificações do Artifact Analysis para atividades, como novos resultados de verificação de vulnerabilidades, consulte a documentação do Artifact Analysis.

Informações gerais

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 de tópico gcr. Se o Container Registry estiver ativado no mesmo projeto do Google Cloud, o tópico poderá já existir, já que os dois serviços de registro usam o mesmo tópico para publicar mensagens.

Se o tópico gcr tiver sido excluído acidentalmente ou estiver ausente, você poderá adicioná-lo por conta própria. Por exemplo, o tópico pode estar ausente se a organização do Google Cloud tiver uma restrição de política da organização que exija criptografia com chaves 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 tópicos automaticamente com chaves de criptografia gerenciadas pelo Google.

Para ver uma lista de tópicos atuais, consulte a 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 criptografia gerenciadas pelo Google:

Console

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

   Acessar a página de tópicos do 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 sinalização --project, o comando usará o projeto atual.

Observação :se esse comando retornar a mensagem de erro "O recurso já existe no projeto", o tópico gcr já existe no projeto.

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 criptografia de tópicos.

Depois de criar o tópico gcr ou verificar se ele existe, crie uma assinatura para ele.

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.

   Acessar a página de tópicos do 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

Observação: Use a sinalização opcional --ack-deadline para configurar quantos segundos o sistema aguardará a confirmação do assinante antes de tentar exibi-lo novamente. Sem a sinalização, o prazo padrão é de 10 segundos.

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 do 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 é [e-mail], em que PROJECT-NUMBER é o número do projeto do Google Cloud. Por padrão, a conta de serviço do Artifact Registry tem a permissão pubsub.topics.publish para publicar alterações no tópico.

   Se um administrador tiver revogado as permissões pubsub.topics.publish da conta de serviço do Artifact Registry, o Artifact Registry vai 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

• Leia a documentação do Pub/Sub.
• Para ver uma explicação detalhada do Pub/Sub, consulte O que é o Pub/Sub?
• Saiba mais sobre os papéis de controle de acesso do Pub/Sub.