Como configurar notificações SMTP

Para notificar você sobre atualizações no status do build, o Cloud Build envia notificações para os canais desejados, como o Slack ou o servidor SMTP. Esta página explica como configurar notificações usando o notificador SMTP.

Antes de começar

  • Ative as APIs Cloud Build, Compute Engine, Cloud Run, Pub/Sub, and Secret Manager.

    Ative as APIs

Notificadores do Cloud Build

O Cloud Build envia todas as atualizações do status do build com os metadados do build para o Pub/Sub no tópico cloud-builds. Os notificadores do Cloud Build podem ser configurados para ouvir esse tópico, filtrar as mensagens recebidas e enviar mensagens para o serviço.

Os notificadores do Cloud Build são imagens do Docker que podem ser executadas como contêineres no Cloud Run. Quando solicitados por um aplicativo de assinante, os notificadores do Cloud Build usam assinaturas de push para enviar mensagens ao serviço configurado. Na configuração, todos os notificadores usam uma especificação comum do YAML armazenada no Cloud Storage.

O Cloud Build fornece e mantém imagens de notificador implantáveis no repositório cloud-build-notifiers. A tabela a seguir lista os notificadores disponíveis:

Notificador Descrição
slack usa um webhook do Slack para postar mensagens em um canal do Slack
smtp envia e-mails por um servidor SMTP
http envia um payload JSON para outro endpoint HTTP

Como configurar notificações por e-mail

Para enviar notificações por e-mail, você precisará de um servidor SMTP em execução e acesso a uma conta nesse servidor, incluindo o nome de usuário e a senha da conta que será usada para enviar notificações. Certifique-se de que as cotas de envio do servidor SMTP sejam compatíveis com o volume de e-mail esperado.

Para configurar notificações por e-mail usando o notificador SMTP:

  1. Armazene a senha da conta de e-mail do remetente no Gerenciador de secrets:

    1. Abra a página "Gerenciador de secrets" no Console do Google Cloud:

      Abrir a página "Gerenciador de secrets"

    2. Clique em Criar secret.

    3. Insira um nome para o secret.

    4. Em Valor do secret, adicione a senha da conta de e-mail do remetente.

    5. Para salvar o secret, clique em Criar secret.

  2. Conceda à sua conta de serviço do Cloud Run acesso ao secret:

    1. Acesse a página IAM do Console do Google Cloud:

      Abrir a página do IAM

    2. Localize a conta de serviço padrão do Compute Engine associada ao projeto:

      Sua conta de serviço padrão do Compute Engine será semelhante a esta:

      project-number-compute@developer.gserviceaccount.com
      

      Anote a conta de serviço padrão do Compute Engine.

    3. Abra a página "Gerenciador de secrets" no Console do Google Cloud:

      Abrir a página "Gerenciador de secrets"

    4. Clique no nome do secret que contém o secret da senha da conta de e-mail do remetente.

    5. Na guia Permissões, clique em Adicionar membro.

    6. Adicione a conta de serviço padrão do Compute Engine associada ao projeto como membro.

    7. Selecione como papel a permissão Acessador de secrets do Gerenciador de secrets.

    8. Clique em Save.

  3. Grave um arquivo de configuração do notificador para configurar o notificador SMTP e filtrar os eventos de build:

    No exemplo de arquivo de configuração do notificador de exemplo, o campo filter usa Common Expression Language com a variável disponível, build, para filtrar os eventos de build com um status SUCCESS:

    apiVersion: cloud-build-notifiers/v1
    kind: SMTPNotifier
    metadata:
      name: example-smtp-notifier
    spec:
      notification:
        filter: build.status == Build.Status.SUCCESS
        delivery:
          server: server-host-name
          port: "port"
          sender: sender-email
          from: from-email
          recipients:
            - recipient-email
            # optional: more emails here
          password:
            secretRef: smtp-password
      secrets:
      - name: smtp-password
        value: projects/project-id/secrets/secret-name/versions/latest
    

    Onde:

    • server-host-name é o endereço do seu servidor SMTP.
    • port é a porta que processará as solicitações de SMTP. Esse valor precisa ser especificado como uma string.
    • sender-email é o endereço de e-mail da conta do remetente que é vista pelo server-host-name especificado.
    • from-email é o endereço de e-mail visto pelos destinatários.
    • recipient-email é uma lista de um ou mais endereços de e-mail para receber mensagens do remetente.
    • smtp-password é a variável de configuração usada neste exemplo para fazer referência à senha da conta de e-mail do remetente armazenada no Gerenciador de secrets. O nome da variável especificado aqui precisa corresponder ao campo name em secrets.
    • project-id é o ID do projeto do Cloud.
    • secret-name é o nome do secret que contém a senha da conta de e-mail do remetente.

    Para ver o exemplo, consulte o arquivo de configuração do notificador para o notificador SMTP.

    Para ver outros campos que podem ser filtrados, consulte o recurso Build. Para ver mais exemplos de filtros, consulte Como filtrar builds em notificações.

  4. Faça o upload do arquivo de configuração do notificador em um bucket do Cloud Storage:

    1. Se você não tiver um bucket do Cloud Storage, execute o seguinte comando para criar um bucket, em que bucket-name é o nome que você quer dar ao bucket, sujeito aos requisitos de nomenclatura.

      gsutil mb gs://bucket-name/
      
    2. Faça o upload do arquivo de configuração do notificador para o bucket:

      gsutil cp config-file-name gs://bucket-name/config-file-name
      

      Onde:

      • bucket-name é o nome do bucket.
      • config-file-name é o nome do seu arquivo de configuração. Para ver um arquivo de configuração de exemplo para o notificador SMTP, consulte smtp.yaml.example.
  5. Implante o notificador no Cloud Run.

     gcloud run deploy service-name \
       --image=us-east1-docker.pkg.dev/gcb-release/cloud-build-notifiers/smtp:latest \
       --update-env-vars=CONFIG_PATH=config-path,PROJECT_ID=project-id
    

    Onde:

    • service-name é o nome do serviço do Cloud Run em que você está implantando a imagem;
    • config-path é o caminho para o arquivo de configuração do seu notificador SMTP, gs://bucket-name/config-file-name.
    • project-id é o ID do projeto do Cloud.

    O comando gcloud run deploy extrai a versão mais recente da imagem hospedada do Registro de artefatos de propriedade do Cloud Build. O Cloud Build oferece suporte a imagens do notificador por nove meses. Após nove meses, o Cloud Build exclui a versão da imagem. Se quiser usar uma versão de imagem anterior, você precisará especificar a versão semântica completa da tag de imagem no atributo image do seu comando gcloud run deploy. Versões e tags de imagem anteriores podem ser encontradas no Artifact Registry.

  6. Conceda permissões do Pub/Sub para criar tokens de autenticação no seu projeto:

     gcloud projects add-iam-policy-binding project-id \
       --member=serviceAccount:service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com \
       --role=roles/iam.serviceAccountTokenCreator
    

    Onde:

    • project-id é o ID do projeto do Cloud.
    • project-number é o número do projeto do Cloud.
  7. Crie uma conta de serviço para representar sua identidade de assinatura do Pub/Sub:

    gcloud iam service-accounts create cloud-run-pubsub-invoker \
      --display-name "Cloud Run Pub/Sub Invoker"
    

    Você pode usar cloud-run-pubsub-invoker ou um nome exclusivo no seu projeto do Google Cloud.

  8. Conceda à conta de serviço cloud-run-pubsub-invoker a permissão Invoker do Cloud Run:

    gcloud run services add-iam-policy-binding service-name \
       --member=serviceAccount:cloud-run-pubsub-invoker@project-id.iam.gserviceaccount.com \
       --role=roles/run.invoker
    

    Em que:

    • service-name é o nome do serviço do Cloud Run em que você está implantando a imagem;
    • project-id é o ID do projeto do Cloud.
  9. Crie o tópico cloud-builds para receber mensagens de atualização da build para seu notificador:

    gcloud pubsub topics create cloud-builds
    
  10. Crie um assinante de push do Pub/Sub para seu notificador:

     gcloud pubsub subscriptions create subscriber-id \
       --topic=cloud-builds \
       --push-endpoint=service-url \
       --push-auth-service-account=cloud-run-pubsub-invoker@project-id.iam.gserviceaccount.com
    

    Em que:

    • subscriber-id é o nome que você quer dar à sua assinatura.
    • service-url é o URL gerado pelo Cloud Run para o novo serviço.
    • project-id é o ID do projeto do Cloud.

Agora as notificações do seu projeto do Cloud Build estão configuradas. Na próxima vez que invocar um build, o recipients especificado receberá um e-mail com uma notificação caso o build corresponda ao filtro que você configurou.

Como automatizar a configuração de notificação para SMTP

O repositório cloud-build-notifiers contém um script de configuração, setup.sh, que automatiza a configuração descrita em Como configurar notificações do SMTP. Antes de executar o script, verifique se você criou um secret para a senha da conta do e-mail do remetente usando o Gerenciador de secrets, conforme descrito nas etapas acima. Para automatizar a configuração de notificações para SMTP, siga estas etapas:

  1. Clone o repositório do cloud-build-notifiers.

  2. Execute o seguinte comando na raiz do repositório, em que config-path é o caminho para o arquivo de configuração dos notificadores:

     ./setup.sh smtp `config-path` `secret-name`
    

    Onde:

    • config-path é o caminho para o arquivo de configuração dos notificadores.
    • secret-name é o nome do secret armazenado no Gerenciador de secrets.

Depois de executar o script, você verá a seguinte mensagem:

** NOTIFIER SETUP COMPLETE **

O notificador do SMTP agora está configurado. Veja o script completo no repositório do cloud-build-notifier ou execute ./setup.sh --help para ver instruções de uso associadas ao script.

A seguir