Como criar seu próprio notificador

O Cloud Build pode notificar você sobre atualizações no status do build enviando notificações para canais selecionados. Além dos notificadores mantidos pelo Cloud Build, como Slack ou SMTP, você também pode usar a biblioteca fornecida no repositório cloud-build-notifiers para criar seu próprio notificador.

Nesta página, explicamos como criar seu próprio notificador.

Antes de começar

• Ative as APIs Cloud Build, Cloud Run, Pub/Sub e Secret Manager, se alguma delas ainda não estiver ativada.

  Funções necessárias para ativar APIs

  Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão com o papel de Proprietário (roles/owner). Caso contrário, é possível receber essa permissão com o papel de Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

  Ativar as APIs

• Instale a linguagem de programação Go.

  Observação: os notificadores do Cloud Build são escritos em Go. Para criar seu próprio notificador usando a biblioteca fornecida pelo repositório cloud-build-notifiers, você precisará instalar o Go na sua máquina.

• Instale a CLI do Google Cloud.

Configuração

1. Abra uma janela de terminal na sua máquina.

2. Clone e navegue até o repositório cloud-build-notifiers:

     git clone https://github.com/GoogleCloudPlatform/cloud-build-notifiers.git && cd cloud-build-notifiers
   

3. Adicione um diretório para seu próprio notificador e navegue até ele, em que DIRECTORY_NAME é o nome do diretório:

     mkdir DIRECTORY_NAME && cd DIRECTORY_NAME
   

4. Inicialize os módulos do Go no novo diretório, em que DIRECTORY_NAME é o nome do novo diretório:

     go mod init github.com/GoogleCloudPlatform/cloud-build-notifiers/DIRECTORY_NAME
   

   Agora você verá um arquivo go.mod no diretório.

5. Adicione a seguinte linha ao arquivo go.mod para garantir que você esteja usando a versão mais recente dos notificadores:

    replace github.com/GoogleCloudPlatform/cloud-build-notifiers/lib/notifiers => ../
   

Suas dependências agora estão configuradas e você está pronto para criar seu próprio notificador.

Como criar seu próprio notificador

O cloud-build-notifiers contém um diretório lib/notifiers. No diretório lib/notifiers, você verá um arquivo chamado notifier.go. Esse arquivo contém o framework que pode ser usado para criar seu próprio notificador.

Será necessário definir dois métodos para criar um notificador no arquivo principal.

1. No novo diretório, crie um arquivo chamado main.go.

2. Em main.go, importe o framework da biblioteca do notificador e outras dependências:

   package main
   
   import (
   	"context"
   	"fmt"
   
   	cbpb "cloud.google.com/go/cloudbuild/apiv1/v2/cloudbuildpb"
   	"github.com/GoogleCloudPlatform/cloud-build-notifiers/lib/notifiers"
   	log "github.com/golang/glog"
   	"google.golang.org/protobuf/encoding/prototext"
   )
   

3. Defina um método principal para o notificador. Neste exemplo, logger é o nome do notificador:

   func main() {
   	if err := notifiers.Main(new(logger)); err != nil {
   		log.Fatalf("fatal error: %v", err)
   	}
   }
   

   O main usa o Main definido no arquivo notifier.go, que é usado para configurar binários de notificação.

4. Defina uma estrutura para o notificador, em que você definirá as variáveis da interface. Neste exemplo, logger é o nome do notificador:

   type logger struct {
   	filter notifiers.EventFilter
   }
   

5. Adicione a funcionalidade de notificação. A interface do notificador é definida por dois métodos:

   • SetUp: o método SetUp aceita uma configuração, busca secrets e extrai filtros especificados da configuração, armazenando-os como um predicado da Common Expression Language que pode ser usado para enviar notificações. Para saber mais sobre a CEL, consulte o repositório cel-spec.

   • SendNotification: o método SendNotification é usado para enviar notificações ao canal ou serviço selecionado.

     A definição do notificador está disponível em notifier.go e na documentação do Go.

     No exemplo a seguir, a interface do notificador é definida usando o método SetUp e SendNotification para imprimir registros de build, com logger como o nome do seu notificador:

     func (h *logger) SetUp(_ context.Context, cfg *notifiers.Config, _ notifiers.SecretGetter, _ notifiers.BindingResolver) error {
     	prd, err := notifiers.MakeCELPredicate(cfg.Spec.Notification.Filter)
     	if err != nil {
     		return fmt.Errorf("failed to create CELPredicate: %w", err)
     	}
     	h.filter = prd
     	return nil
     }
     
     func (h *logger) SendNotification(ctx context.Context, build *cbpb.Build) error {
     	// Include custom functionality here.
     	// This example logs the build.
     	if h.filter.Apply(ctx, build) {
     		log.V(1).Infof("printing build\n%s", prototext.Format(build))
     	} else {
     		log.V(1).Infof("build (%q, %q) did NOT match CEL filter", build.ProjectId, build.Id)
     	}
     
     	return nil
     }
     

     O arquivo main.go final será semelhante ao arquivo a seguir. Neste exemplo, logger é usado como o nome do notificador.

     package main
     
     import (
     	"context"
     	"fmt"
     
     	cbpb "cloud.google.com/go/cloudbuild/apiv1/v2/cloudbuildpb"
     	"github.com/GoogleCloudPlatform/cloud-build-notifiers/lib/notifiers"
     	log "github.com/golang/glog"
     	"google.golang.org/protobuf/encoding/prototext"
     )
     
     
     func main() {
     	if err := notifiers.Main(new(logger)); err != nil {
     		log.Fatalf("fatal error: %v", err)
     	}
     }
     
     
     type logger struct {
     	filter notifiers.EventFilter
     }
     
     
     func (h *logger) SetUp(_ context.Context, cfg *notifiers.Config, _ notifiers.SecretGetter, _ notifiers.BindingResolver) error {
     	prd, err := notifiers.MakeCELPredicate(cfg.Spec.Notification.Filter)
     	if err != nil {
     		return fmt.Errorf("failed to create CELPredicate: %w", err)
     	}
     	h.filter = prd
     	return nil
     }
     
     func (h *logger) SendNotification(ctx context.Context, build *cbpb.Build) error {
     	// Include custom functionality here.
     	// This example logs the build.
     	if h.filter.Apply(ctx, build) {
     		log.V(1).Infof("printing build\n%s", prototext.Format(build))
     	} else {
     		log.V(1).Infof("build (%q, %q) did NOT match CEL filter", build.ProjectId, build.Id)
     	}
     
     	return nil
     }
     

   Em seguida, configure o notificador.

Configurar notificações

1. Grave um arquivo de configuração do notificador para configurar seu notificador e filtrar eventos de build:

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

   apiVersion: cloud-build-notifiers/v1
   kind: YourNotifier
   metadata:
     name: logging-sample
   spec:
     notification:
       filter: build.status == Build.Status.SUCCESS

   Em que:

   • logging-sample é o nome do notificador.

   Para ver outros campos que podem ser filtrados, consulte o recurso Build. Para outros exemplos de filtragem, consulte Como usar a CEL para filtrar eventos de build.

2. 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 comando a seguir para criar um bucket, em que BUCKET_NAME é o nome que você quer dar ao bucket, sujeito aos requisitos de nomenclatura.

      gcloud storage buckets create gs://BUCKET_NAME/
      

   2. Faça o upload do arquivo de configuração do notificador para o bucket:

      gcloud storage 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.

3. Crie e implante o notificador:

   1. Crie um Dockerfile para o logging-sample:

      
      FROM us-docker.pkg.dev/artifact-foundry-prod/docker-3p-trusted/golang@sha256:11fd8f7f63db3b6fb198797042ba4c40a4a34dc83325d3328ca3bc4bb7726786 AS build-env
      COPY . /go-src/
      WORKDIR /go-src/
      RUN go build -o /go-app .
      
      # From the Cloud Run docs:
      # https://cloud.google.com/run/docs/tutorials/pubsub#looking_at_the_code
      # Use the official Debian slim image for a lean production container.
      # https://hub.docker.com/_/debian
      # https://docs.docker.com/develop/develop-images/multistage-build/#use-multi-stage-builds
      FROM debian:buster-slim
      # Modify sources.list to point to the Debian archive
      RUN sed -i 's|deb.debian.org|archive.debian.org|g' /etc/apt/sources.list && \
          sed -i 's|security.debian.org|archive.debian.org/debian-security|g' /etc/apt/sources.list && \
          sed -i '/buster-updates/d' /etc/apt/sources.list && \
          echo "deb http://archive.debian.org/debian buster-updates main contrib non-free" >> /etc/apt/sources.list && \
          set -x && \
          apt-get update --allow-releaseinfo-change && \
          DEBIAN_FRONTEND=noninteractive apt-get install -y ca-certificates && \
          rm -rf /var/lib/apt/lists/*
      
      
      FROM gcr.io/distroless/base
      COPY --from=build-env /go-app /
      ENTRYPOINT ["/go-app", "--v=1", "--alsologtostderr"]
      

   2. Crie e implante o notificador usando o arquivo cloudbuild.yaml a seguir.

      steps:
      - # Build the binary and put it into the builder image.
        name: gcr.io/cloud-builders/docker
        args: ['build', '--tag=gcr.io/$PROJECT_ID/logging-sample', '.']
      
      - # Push the container image to Container Registry
        name: gcr.io/cloud-builders/docker
        args: ['push', 'gcr.io/$PROJECT_ID/logging-sample']
      
      - # Deploy to Cloud Run
        name: google/cloud-sdk
        args: 
          - gcloud
          - run
          - deploy
          - logging-sample-notifier
          - --platform=managed
          - --region=us-central1
          - --image=gcr.io/$PROJECT_ID/logging-sample
          - --no-allow-unauthenticated
          - --update-env-vars=CONFIG_PATH=${_CONFIG_PATH}
      
      # Push the image with tags.
      images:
      - gcr.io/$PROJECT_ID/logging-sample

      Em que:

      • _CONFIG_PATH é o caminho para a configuração do notificador, como gs://BUCKET_NAME/CONFIG_FILE_NAME.yaml.

   Para executar o cloudbuild.yaml, transmita o caminho do notificador como uma variável de substituição.

    gcloud builds submit .  --substitutions=_CONFIG_PATH=gs://BUCKET_NAME/CONFIG_FILE_NAME
   

   Observação: o Cloud Build hospeda imagens de notificador atuais no Artifact Registry. Como você está criando seu próprio notificador em vez de usar um host do Cloud Build, é necessário criar um notificador para criar uma imagem do notificador. Para ver um exemplo de arquivo cloudbuild.yaml para outro tipo de notificador, como o slack, consulte buildtest.cloudbuild.yaml. Para ver um exemplo do Dockerfile usado no arquivo buildtest.cloudbuild.yaml, consulte Dockerfile.

4. 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:[e-mail] \
      --role=roles/iam.serviceAccountTokenCreator
   

   Em que:

   • PROJECT_ID é o ID do projeto do Google Cloud .
   • PROJECT_NUMBER é o número do projeto do Google Cloud .

5. 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"
   

   É possível usar cloud-run-pubsub-invoker ou um nome exclusivo no seu projeto Google Cloud .

6. 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 Google Cloud .

7. Crie o tópico cloud-builds para receber mensagens de atualização de build do seu notifier:

   gcloud pubsub topics create cloud-builds
   

   Também é possível definir um nome de tópico personalizado no arquivo de configuração do build para que as mensagens sejam enviadas ao tópico personalizado. Nesse caso, você criaria um tópico com o mesmo nome personalizado:

   gcloud pubsub topics create topic-name
   

   Para mais informações, consulte Tópicos do Pub/Sub para notificações de build.

8. 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=SUB_IDENTITY_SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com

Em que: + SUBSCRIBER_ID é o nome que você quer dar à assinatura. + SERVICE_URL é o URL gerado pelo Cloud Run para seu novo serviço. + PROJECT_ID é o ID do projeto do Google Cloud .

Note: By default, [subscriptions expire after 31 days of inactivity](/pubsub/docs/subscription-overview#lifecycle).
You can adjust or disable the expiration period by including the
[`--expiration-period` flag](/sdk/gcloud/reference/pubsub/subscriptions/create#--expiration-period)
when creating the subscription.

Agora as notificações do seu projeto do Cloud Build estão configuradas. Da próxima vez que você invocar uma build, você receberá uma notificação no seu canal caso a build corresponda ao filtro que você configurou.

Notificações de teste

Para testar as notificações do exemplo usado neste guia, você pode invocar um build executando o comando gcloud builds submit.

No exemplo a seguir, especificamos success.yaml como o caminho de configuração. A execução desse comando deve resultar em um build bem-sucedido mínimo. Você também verá uma saída dos seus registros de criação.

 gcloud builds submit --no-source --config=success.yaml

Onde success.yaml é:

 steps:
 - name: busybox
   args: ["true"]

No exemplo a seguir, especificamos failure.yaml como o caminho de configuração. A execução desse comando deve resultar em uma criação com falha. Em vez de ver uma saída dos registros de compilação, você verá uma saída informando que não houve correspondência para os filtros CEL especificados na sua origem.

gcloud builds submit --no-source --config=failure.yaml

Onde failure.yaml é:

 steps:
 - name: busybox
   args: ["false"]

Se você criou um notifier configurado para realizar outra tarefa além de registrar a saída nos registros de serviço do Cloud Run, também é possível executar o comando gcloud builds submit para testar as notificações. Para examinar erros associados à versão, verifique os registros do Cloud Run do seu serviço. Para saber mais, consulte Como visualizar registros no Cloud Run.

A seguir

• Saiba mais sobre os notificadores do Cloud Build.
• Saiba como se inscrever para criar notificações.