Automatize compilações em resposta a eventos Pub/Sub

1.ª geração 2.ª geração

Os acionadores do Cloud Build Pub/Sub permitem-lhe executar compilações em resposta a Google Cloud eventos publicados através do Pub/Sub. Pode usar informações de um evento do Pub/Sub para parametrizar a compilação e decidir se uma compilação deve ser executada em resposta ao evento. Os acionadores do Pub/Sub podem ser configurados para monitorizar qualquer tópico do Pub/Sub.

Esta página explica como pode criar um acionador do Pub/Sub para automatizar compilações em resposta a eventos no Artifact Registry e no Cloud Storage.

Nota: os acionadores do Pub/Sub são um tipo de acionador associado ao Cloud Build. Os acionadores do Pub/Sub usados em contextos adicionais no Google Cloud podem não se referir aos acionadores do Pub/Sub do Cloud Build, salvo indicação explícita.

Limitações

Os acionadores do Cloud Build Pub/Sub não são suportados quando os VPC Service Controls são usados.

Antes de começar

• Enable the Cloud Build API.

  Enable the API

• Certifique-se de que o código-fonte contém um ficheiro de configuração de compilação ou um Dockerfile no repositório.

• Para usar os comandos gcloud nesta página, instale a CLI do Google Cloud.

  Nota: se tiver instalado a CLI gcloud anteriormente, certifique-se de que tem a versão mais recente disponível executando gcloud components update.

Criar um acionador de compilação que responda a eventos do Artifact Registry

Pode criar um acionador do Pub/Sub que responda a eventos do Artifact Registry, como quando as imagens são enviadas, etiquetadas ou eliminadas. Esta secção aborda como pode criar um acionador do Pub/Sub que invoca uma compilação quando uma nova etiqueta é enviada para uma imagem existente. Se não conhece o Artifact Registry, consulte a vista geral do Artifact Registry.

Nota: os acionadores do Pub/Sub não podem criar repositórios do GitHub Enterprise, do Bitbucket Data Center e do Bitbucket Server através da integração nativa do Cloud Build. Para clonar e criar repositórios através do seu sistema de gestão de código-fonte externo, consulte o artigo Criar e gerir acionadores de compilação para saber como especificar uma configuração de compilação inline.

Consola

Para criar um acionador que ouve uma nova etiqueta enviada para uma imagem existente no Artifact Registry através da Google Cloud consola:

1. Abra a página Acionadores:

   Abra a página Acionadores

2. Selecione o projeto na parte superior da página e clique em Abrir.

3. Clique em Criar acionador.

4. Introduza as seguintes definições do acionador:

   • Nome: introduza um nome para o acionador.

   • Região: selecione a região para o seu acionador.

     • Se o ficheiro de configuração de compilação associado ao acionador especificar um pool privado, o Cloud Build usa o pool privado para executar a compilação. Neste caso, a região especificada no acionador tem de corresponder à região onde criou o seu conjunto privado.
     • Se o ficheiro de configuração de compilação associado ao acionador não especificar um conjunto privado, o Cloud Build usa o conjunto predefinido para executar a compilação na mesma região que o acionador.

   • Descrição (opcional): introduza uma descrição para o acionador.

   • Evento: selecione Mensagem do Pub/Sub como o evento para invocar o acionador.

   • Subscrição: selecione o tópico do Pub/Sub ao qual quer subscrever como evento acionador. Vê todos os tópicos existentes no seu projeto no menu pendente.

     • Tópico do Pub/Sub: selecione o tópico gcr no menu pendente ou crie manualmente o tópico seguindo as instruções em Configurar notificações do Pub/Sub.
     Nota: depois de criar o acionador, é criada automaticamente uma subscrição para o acionador. Pode ver a sua subscrição na página Subscrições do Pub/Sub.

   • Origem: selecione a origem a criar quando o acionador do Pub/Sub for executado. Pode especificar 1st generation (1.ª geração) ou 2nd generation (2.ª geração) como origem.

     Nota: a região do seu repositório tem de corresponder à região do seu acionador.

     • Repositório: na lista de repositórios disponíveis, selecione o repositório desejado.

     • Branch ou Tag: especifique uma expressão regular com o valor da ramificação ou da etiqueta a corresponder. Para obter informações sobre a sintaxe de expressões regulares aceitável, consulte a sintaxe RE2.

     • Controlo de comentários: se selecionou Pedido de envio (apenas app GitHub) como Evento, escolha uma das seguintes opções para controlar se uma compilação é executada automaticamente pelo acionador:

       Aviso: qualquer utilizador com acesso de leitura ao repositório pode enviar um pedido de envio, que pode executar uma compilação que inclua alterações ao código-fonte no pedido de envio. Para desativar este comportamento, recomendamos que use aprovações manuais para restringir as compilações quando fizer pedidos de envio em repositórios públicos. Para mais informações sobre os privilégios de tempo de compilação dos acionadores, consulte o artigo Acionadores de compilação e conta de serviço do Cloud Build.

       • Obrigatório, exceto para proprietários e colaboradores: quando um proprietário ou um colaborador do repositório cria ou atualiza um pedido de envio, as compilações são executadas automaticamente pelo acionador. Se um colaborador externo iniciar a ação, as compilações só são executadas depois de um proprietário ou um colaborador comentar /gcbrun no pedido de envio.

       • Obrigatório: quando um pedido de obtenção é criado ou atualizado por qualquer colaborador, as compilações só são executadas depois de um proprietário ou um colaborador comentar /gcbrun no pedido de obtenção. As compilações são executadas sempre que é feita uma alteração a um pedido de obtenção.

       • Não obrigatório: quando um pedido de obtenção é criado ou atualizado por qualquer colaborador, as compilações são executadas automaticamente por acionadores.

   • Configuração: selecione o ficheiro de configuração de compilação (localizado no seu repositório remoto) ou crie um ficheiro de configuração de compilação inline para usar na sua compilação.

     • Tipo: selecione o tipo de configuração a usar para a sua compilação.
       • Ficheiro de configuração do Cloud Build (YAML ou JSON): use um ficheiro de configuração de compilação para a sua configuração.
       • Dockerfile: use um Dockerfile para a sua configuração.
       • Buildpacks: use buildpacks para a sua configuração.

     • Localização: especifique a localização da configuração.

       • Repositório: se o ficheiro de configuração estiver localizado no seu repositório remoto, indique a localização do ficheiro de configuração de compilação, do Dockerfilediretório ou do diretório de pacotes de compilação. Se o seu tipo de configuração de compilação for Dockerfile ou um buildpack, tem de fornecer um nome para a imagem resultante e, opcionalmente, um limite de tempo para a compilação. Quando tiver indicado o nome da imagem Dockerfile ou do buildpack, é apresentada uma pré-visualização do comando docker build ou pack que a sua compilação vai executar.
       • Variáveis de ambiente do buildpack (opcional): se selecionou buildpacks como o tipo de configuração, clique em Adicionar variável de ambiente do pacote para especificar as variáveis de ambiente e os valores do buildpack. Para saber mais acerca das variáveis de ambiente do buildpack, consulte o artigo Variáveis de ambiente.

       • Inline: se selecionou Ficheiro de configuração do Cloud Build (YAML ou JSON) como opção de configuração, pode especificar a configuração de compilação inline. Clique em Abrir editor para escrever o ficheiro de configuração de compilação na Google Cloud consola com a sintaxe YAML ou JSON. Clique em Concluído para guardar a configuração de compilação.

         Nota: o suporte da configuração de compilação inline não está disponível para o Dockerfile ou os buildpacks.

   • Substituições (opcional): se selecionou o ficheiro de configuração de compilação como a opção de configuração de compilação, pode optar por definir variáveis de substituição específicas do acionador através deste campo.

     No exemplo seguinte, queremos obter o nome da etiqueta de imagem do payload e a ação associada ao evento gcr. Para o fazer, crie variáveis de substituição usando vinculações de payload.

     Especifique as seguintes variáveis e valores abaixo:

     Nome da variável	Valor da variável
     _IMAGE_TAG	$(body.message.data.tag)
     _ACTION	$(body.message.data.action)

     body.message refere-se à PubSubMessage publicada pelos publicadores e consumida pelos subscritores. Para ver mais exemplos da carga útil de notificação do Pub/Sub, consulte os exemplos de notificação.

     Nota: embora a definição de variáveis de substituição seja opcional, é necessária se quiser configurar a filtragem personalizada em mensagens do Pub/Sub (consulte Filtros abaixo para mais informações).

   • Filtros (opcional): pode criar filtros num acionador que determinam se o acionador vai executar uma compilação em resposta à carga útil recebida, especificando filtros em variáveis de substituição. A expressão de filtro tem de ser avaliada como true para que seja possível executar uma compilação.

     Recomendamos a utilização da filtragem ao configurar acionadores do Pub/Sub em tópicos com várias mensagens. Os filtros podem ser usados para controlar com precisão as compilações que são executadas em resposta a mensagens Pub/Sub recebidas. Para saber mais sobre os riscos associados à configuração de um acionador sem filtros, consulte a secção Riscos associados a um acionador não filtrado.

     No exemplo seguinte, queremos que o acionador execute uma compilação se uma nova etiqueta for enviada para uma imagem existente. Usamos operadores de condição de filtro para verificar se a variável _IMAGE_TAG corresponde a um nome de etiqueta existente e se a variável _ACTION corresponde a INSERT para procurar dados adicionados recentemente.

     Especifique o seguinte como filtros:

     • _IMAGE_TAG != ""
     • _ACTION == INSERT
     Nota: também pode aninhar condições especificando os seguintes operadores booleanos: && (e) e || (ou). O símbolo ! (não) não é suportado.

     A sintaxe de filtragem nos acionadores do Pub/Sub usa o Idioma de expressão comum (IEC) para a avaliação de expressões. Para saber mais sobre a CEL, consulte o repositório cel-spec.

5. Clique em Criar para criar o acionador de compilação.

gcloud

Para criar um acionador que ouve uma nova etiqueta enviada para uma imagem existente no Artifact Registry através dos comandos gcloud:

1. Abra uma janela de terminal.

2. Execute o comando gcloud para criar um acionador de versão no seu projeto. No exemplo abaixo, o acionador está configurado para responder a compilações com uma etiqueta correspondente a prod e uma ação correspondente a INSERT com base na carga útil especificada, conforme definido pela variável de substituição _IMAGE_TAG.

    gcloud builds triggers create pubsub \
      --region=REGION \
      --name=TRIGGER_NAME \
      --repository=projects/PROJECT_ID/locations/REGION/connections/CONNECTION_NAME/repositories/REPO_NAME \
      --topic=projects/PROJECT_ID/topics/TOPIC_NAME \
      --build-config=BUILD_CONFIG \ # or --inline-config=INLINE_BUILD_CONFIG
      --substitutions=\
        '_IMAGE_TAG_="$(body.message.data.tag)",' \
        '_ACTION="$(body.message.data.action)"' \
      --subscription-filter='_IMAGE_TAG != "" && _ACTION == "INSERT"' \
      --tag=TAG_NAME  # or --branch=BRANCH_NAME
   

Onde:

• REGION é a região do seu acionador.
• TRIGGER_NAME é o nome do acionador.
• PROJECT_ID é o ID do seu projeto do Google Cloud.
• CONNECTION_NAME é o nome da ligação do anfitrião.
• REPO_NAME é o nome do seu repositório.
• TOPIC_NAME é o nome do tópico do Pub/Sub ao qual subscreveu.
• BUILD_CONFIG é o caminho para o ficheiro de configuração de compilação.
• INLINE_BUILD_CONFIG é o caminho para o ficheiro de configuração de compilação inline.
• TAG_NAME é o nome da etiqueta se quiser definir o acionador para criar com base numa etiqueta.
• BRANCH_NAME é o nome da ramificação se quiser definir o acionador para compilar numa ramificação.

Criar um acionador de compilação que responda a eventos do Cloud Storage

Pode criar um acionador do Pub/Sub que responda a eventos do Cloud Storage, como quando um novo ficheiro binário é enviado para um contentor de armazenamento existente. Esta secção aborda como pode criar um acionador do Pub/Sub que responde com uma compilação quando implementa um novo ficheiro binário num contentor carregado. Se não tiver experiência com o Cloud Storage, consulte os inícios rápidos.

Consola

Para criar um acionador que ouve eventos do Cloud Storage através da Google Cloud consola:

1. Abra a página Acionadores:

   Abra a página Acionadores

2. Selecione o projeto na parte superior da página e clique em Abrir.

3. Clique em Criar acionador.

4. Introduza as seguintes definições do acionador:

   • Nome: introduza um nome para o acionador.

   • Região: selecione a região para o seu acionador.

     • Se o ficheiro de configuração de compilação associado ao acionador especificar um pool privado, o Cloud Build usa o pool privado para executar a compilação. Neste caso, a região especificada no acionador tem de corresponder à região onde criou o seu conjunto privado.
     • Se o ficheiro de configuração de compilação associado ao acionador não especificar um conjunto privado, o Cloud Build usa o conjunto predefinido para executar a compilação na mesma região que o acionador.

   • Descrição (opcional): introduza uma descrição para o acionador.

   • Evento: selecione Mensagem do Pub/Sub como o evento para invocar o acionador.

   • Subscrição: selecione o tópico do Pub/Sub ao qual quer subscrever como evento acionador. Vê todos os tópicos existentes no seu projeto no menu pendente.

     • Tópico do Pub/Sub: selecione o tópico gcs no menu pendente ou crie o tópico manualmente seguindo as instruções em Configurar notificações do Pub/Sub para o Cloud Storage.
     Nota: depois de criar o acionador, é criada automaticamente uma subscrição para o acionador. Pode ver a sua subscrição na página Subscrições do Pub/Sub.

   • Origem: selecione a origem a criar quando o acionador do Pub/Sub for executado. Pode especificar 1st generation (1.ª geração) ou 2nd generation (2.ª geração) como origem.

     Nota: a região do seu repositório tem de corresponder à região do seu acionador.

     • Repositório: na lista de repositórios disponíveis, selecione o repositório desejado.

     • Branch ou Tag: especifique uma expressão regular com o valor da ramificação ou da etiqueta a corresponder. Para obter informações sobre a sintaxe de expressões regulares aceitável, consulte a sintaxe RE2.

     • Controlo de comentários: se selecionou Pedido de envio (apenas app GitHub) como Evento, escolha uma das seguintes opções para controlar se uma compilação é executada automaticamente pelo acionador:

       Aviso: qualquer utilizador com acesso de leitura ao repositório pode enviar um pedido de envio, que pode executar uma compilação que inclua alterações ao código-fonte no pedido de envio. Para desativar este comportamento, recomendamos que use aprovações manuais para restringir as compilações quando fizer pedidos de envio em repositórios públicos. Para mais informações sobre os privilégios de tempo de compilação dos acionadores, consulte o artigo Acionadores de compilação e conta de serviço do Cloud Build.

       • Obrigatório, exceto para proprietários e colaboradores: quando um proprietário ou um colaborador do repositório cria ou atualiza um pedido de envio, as compilações são executadas automaticamente pelo acionador. Se um colaborador externo iniciar a ação, as compilações só são executadas depois de um proprietário ou um colaborador comentar /gcbrun no pedido de envio.

       • Obrigatório: quando um pedido de obtenção é criado ou atualizado por qualquer colaborador, as compilações só são executadas depois de um proprietário ou um colaborador comentar /gcbrun no pedido de obtenção. As compilações são executadas sempre que é feita uma alteração a um pedido de obtenção.

       • Não obrigatório: quando um pedido de obtenção é criado ou atualizado por qualquer colaborador, as compilações são executadas automaticamente por acionadores.

   • Configuração: selecione o ficheiro de configuração de compilação (localizado no seu repositório remoto) ou crie um ficheiro de configuração de compilação inline para usar na sua compilação.

     • Tipo: selecione o tipo de configuração a usar para a sua compilação.
       • Ficheiro de configuração do Cloud Build (YAML ou JSON): use um ficheiro de configuração de compilação para a sua configuração.
       • Dockerfile: use um Dockerfile para a sua configuração.
       • Buildpacks: use buildpacks para a sua configuração.

     • Localização: especifique a localização da configuração.

       • Repositório: se o ficheiro de configuração estiver localizado no seu repositório remoto, indique a localização do ficheiro de configuração de compilação, do Dockerfilediretório ou do diretório de pacotes de compilação. Se o seu tipo de configuração de compilação for Dockerfile ou um buildpack, tem de fornecer um nome para a imagem resultante e, opcionalmente, um limite de tempo para a compilação. Quando tiver indicado o nome da imagem Dockerfile ou do buildpack, é apresentada uma pré-visualização do comando docker build ou pack que a sua compilação vai executar.
       • Variáveis de ambiente do buildpack (opcional): se selecionou buildpacks como o tipo de configuração, clique em Adicionar variável de ambiente do pacote para especificar as variáveis de ambiente e os valores do buildpack. Para saber mais acerca das variáveis de ambiente do buildpack, consulte o artigo Variáveis de ambiente.

       • Inline: se selecionou Ficheiro de configuração do Cloud Build (YAML ou JSON) como opção de configuração, pode especificar a configuração de compilação inline. Clique em Abrir editor para escrever o ficheiro de configuração de compilação na Google Cloud consola com a sintaxe YAML ou JSON. Clique em Concluído para guardar a configuração de compilação.

         Nota: o suporte da configuração de compilação inline não está disponível para o Dockerfile ou os buildpacks.

   • Substituições (opcional): se selecionou o ficheiro de configuração de compilação como a opção de configuração de compilação, pode optar por definir variáveis de substituição específicas do acionador através deste campo.

     Neste exemplo, queremos monitorizar a implementação de um novo ficheiro binário quando é carregado para um contentor. Para obter estes dados, podemos criar variáveis de substituição através de associações de payload.

     Especifique as seguintes variáveis e valores abaixo:

     Nome da variável	Valor da variável
     _EVENT_TYPE	$(body.message.attributes.eventType)
     _BUCKET_ID	$(body.message.attributes.bucketId)
     _OBJECT_ID	$(body.message.attributes.objectId)

     body.message refere-se à PubSubMessage publicada pelos publicadores e consumida pelos subscritores. Para ver mais exemplos da carga útil de notificação do Pub/Sub, consulte os exemplos de notificação.

     Nota: embora a definição de variáveis de substituição seja opcional, é necessária se quiser configurar a filtragem personalizada em mensagens do Pub/Sub (consulte Filtros abaixo para mais informações).

   • Filtros (opcional): pode criar filtros num acionador que determinam se o acionador vai executar uma compilação em resposta à carga útil recebida, especificando filtros em variáveis de substituição. A expressão de filtro tem de ser avaliada como true para que seja possível executar uma compilação.

     Recomendamos a utilização da filtragem ao configurar acionadores do Pub/Sub em tópicos com várias mensagens. Os filtros podem ser usados para controlar com precisão as compilações que são executadas em resposta a mensagens Pub/Sub recebidas. Para saber mais sobre os riscos associados à configuração de um acionador sem filtros, consulte a secção Riscos associados a um acionador não filtrado.

     Uma vez que queremos que o acionador execute uma compilação se o novo ficheiro binário tiver sido implementado num contentor específico, podemos usar o operador "==" para verificar se existem correspondências exatas. Também pode usar a palavra-chave "matches" se quiser fazer a correspondência por expressão regular.

     Especifique o seguinte como filtros:

     • _EVENT_TYPE == OBJECT_FINALIZE
     • _OBJECT_ID correspondências ^<object-id>$
     • _BUCKET_ID correspondências ^<bucket-id>$

5. Clique em Criar para criar o acionador de compilação
.

gcloud

Riscos associados a um acionador não filtrado

Se não tiver configurado filtros no seu acionador do Pub/Sub, o acionador pode acabar por invocar um número infinito de compilações se o acionador modificar um artefacto ou um objeto que publique involuntariamente uma nova mensagem no tópico que está a ouvir. Por exemplo, o seu acionador pode invocar um número infinito de compilações se:

• Aponta para um tópico de gcr.
• Cria qualquer imagem ou etiqueta em gcr.
• Aponta para um tópico gcs para um objeto específico no seu contentor e modifica esse objeto.

Se encontrar um ciclo infinito, pode eliminar o acionador ou atualizá-lo para apontar para um tópico separado, de modo a evitar incorrer em custos adicionais para cada compilação que invocar.

O que se segue?

• Saiba como iniciar compilações manualmente através de comandos gcloud ou da API Cloud Build.
• Saiba como criar e gerir acionadores.
• Saiba como ver os resultados da compilação.
• Saiba como resolver problemas de erros de compilação.