O Cloud Build pode notificá-lo sobre atualizações de criação enviando notificações para os canais pretendidos, como o Slack ou seu servidor SMTP. Esta página explica como configurar notificações usando o Notificador do BigQuery.
O notificador do BigQuery fornece a funcionalidade para que você especifique filtros em quais versões você quer armazenar no seu banco de dados. Por exemplo, é possível agrupar as versões por ID do gatilho, tags ou valores de substituição. O notificador do BigQuery também grava dados no BigQuery em um formato padronizado que inclui campos calculados não acessíveis imediatamente no objeto Build, como tamanho da imagem ou duração da execução. Para saber como exportar entradas de registro para o BigQuery ou outro destino, consulte Como exportar registros com o console do Google Cloud.
Antes de começar
-
Enable the Cloud Build, Cloud Run, Pub/Sub, and BigQuery APIs.
- Instale o Google Cloud CLI.
Como configurar notificações do BigQuery
Na seção a seguir, explicamos como configurar notificações HTTP manualmente usando o notificador do BigQuery. Se você quiser automatizar a configuração, consulte Como automatizar a configuração de notificações.
Para configurar notificações do BigQuery:
Conceda permissão à conta de serviço do Cloud Run para criar e gravar em tabelas do BigQuery, para receber dados do Artifact Registry relacionados ao build e de acesso de leitura e gravação nos buckets do Cloud Storage:
Acesse a página "IAM" no Console do Google Cloud.
Localize a conta de serviço padrão do Compute Engine associada ao seu projeto:
Sua conta de serviço padrão do Compute Engine será semelhante a esta:
project-number-compute@developer.gserviceaccount.com
Clique no ícone de lápis na linha que contém sua conta de serviço padrão do Compute Engine. Você verá a guia Editar acesso.
Clique em Adicionar outro papel.
Adicione os seguintes papéis:
- Leitor do Artifact Registry
- Editor de dados do BigQuery
- Leitor de objetos do Storage
O papel Leitor do Artifact Registry permite buscar dados para as imagens. O Editor de dados do BigQuery dá acesso de leitura e gravação aos seus dados. O Leitor de objetos do Storage oferece acesso de leitura ao Cloud Storage objetos.
Clique em Save.
Grave um arquivo de configuração do notificador para configurar seu notificador do BigQuery e filtrar eventos de build:
No exemplo de arquivo de configuração de notificador a seguir, o campo
filter
usa Common Expression Language com a variávelbuild
para filtrar eventos de build com um ID de gatilho especificado:apiVersion: cloud-build-notifiers/v1 kind: BigQueryNotifier metadata: name: example-bigquery-notifier spec: notification: filter: build.build_trigger_id == "123e4567-e89b-12d3-a456-426614174000" params: buildStatus: $(build.status) delivery: table: projects/project-id/datasets/dataset-name/tables/table-name template: type: golang uri: gs://example-gcs-bucket/bq.json
Em que:
buildStatus
é um parâmetro definido pelo usuário. Esse parâmetro assume o valor de ${build.status}, o status do build.project-id
é o ID do seu projeto do Google Cloud.dataset-name
é o nome que você quer dar ao conjunto de dados.table-name
é o nome que você quer dar à tabela.O campo
uri
faz referência ao arquivobq.json
. Esse arquivo se refere a um modelo JSON hospedado no Cloud Storage e representa as informações a serem inseridas na tabela do BigQuery.
Para ver um exemplo de arquivo de modelo, consulte o arquivo
bq.json
no repositório cloud-build-notifiers-repository.O table-name no arquivo de configuração do notificador pode se referir a:
- uma tabela inexistente
- uma tabela vazia sem um esquema
uma tabela atual com um esquema que corresponde às especificações de esquema no notificador do BigQuery;
Recomendamos especificar o ID do gatilho de compilação como seu filtro, porque a especificação do ID do gatilho de versão permite correlacionar os dados da versão para os gatilhos. Também é possível especificar vários códigos de gatilho em uma lista:
build.build_trigger_id in ["example-id-123", "example-id-456"]
.Para receber o ID do gatilho, execute o seguinte comando: em que trigger-name é o nome do gatilho.
gcloud builds triggers describe trigger-name
O comando lista os campos associados ao seu gatilho, incluindo o ID.
Para ver o exemplo, consulte o arquivo de configuração de notificação do notificador do BigQuery.
Para ver outros campos que podem ser filtrados, consulte o recurso Build. Para ver mais exemplos de filtragem, consulte Como usar a CEL para filtrar eventos do build.
Faça o upload do arquivo de configuração do notificador em um bucket do Cloud Storage:
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.
gcloud storage buckets create gs://bucket-name/
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
Em que:
bucket-name
é o nome do bucket.config-file-name
é o nome do arquivo de configuração do notificador.
Implante o notificador no Cloud Run.
gcloud run deploy service-name \ --image=us-east1-docker.pkg.dev/gcb-release/cloud-build-notifiers/bigquery:latest \ --no-allow-unauthenticated \ --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 notificador do BigQuery,gs://bucket-name/config-file-name
.project-id
é o ID do seu projeto do Google Cloud.
O comando
gcloud run deploy
extrai a versão mais recente da imagem do build criada a partir Artifact Registry. 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 atributoimage
do seu comandogcloud run deploy
. Versões e tags de imagem anteriores podem ser encontradas no Artifact Registry.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
Em que:
project-id
é o ID do seu projeto do Google Cloud.project-number
é o número do projeto do Google Cloud.
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.Conceda à conta de serviço
cloud-run-pubsub-invoker
a permissãoInvoker
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 seu projeto do Google Cloud.
Crie o tópico
cloud-builds
para receber mensagens de atualização da build para seu notificador:gcloud pubsub topics create cloud-builds
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 seu projeto do Google Cloud.
Agora as notificações do seu projeto do Cloud Build estão configuradas.
Na próxima vez que você invocar uma versão, sua tabela será atualizada com os dados mais recentes que correspondem ao filtro configurado para o notificador do BigQuery.
Como ver dados da versão
Para ver seus dados de versão no BigQuery:
Abra a página do console do BigQuery:
Em Recursos, clique no código do projeto usado para configurar o notificador do BigQuery.
Clique no nome do conjunto de dados.
Clique no nome da tabela.
Agora você pode ver informações relacionadas à sua tabela, incluindo o esquema e uma visualização dos dados da versão, conforme listado na tabela.
Como acessar dados da versão
Você pode consultar dados na tabela usando a ferramenta de linha de comando bq ou o console do BigQuery.
CLI
Para consultar dados na tabela usando a ferramenta de linha de comando bq
, execute o seguinte comando no seu terminal em que sql-query é sua consulta:
bq query sql-query
Se você planeja usar os exemplos de consulta nesta página, especifique a sinalização --nouse_legacy_sql
no seu comando. A ferramenta de linha de comando bq
usa o SQL legado, ao contrário das consultas de exemplo. Execute o comando a seguir no seu terminal para consultar dados sem o SQL legado:
bq query sql-query --nouse_legacy_sql
Console
Para consultar dados na tabela usando o console do BigQuery:
Abra a página do console do BigQuery:
Em Recursos, clique no nome da tabela que você quer consultar.
Escreva sua consulta SQL no Editor de consultas.
Como usar consultas para acessar dados do build
Os exemplos de consultas a seguir mostram como acessar os dados da versão para seu evento de versão, seguindo a configuração do notificador do BigQuery:
Histórico geral da versão
SELECT * FROM `projectID.datasetName.tableName`
Números de compilação agrupados por status
SELECT STATUS, COUNT(*)
FROM `projectID.datasetName.tableName`
GROUP BY STATUS
Frequência de implantação diária para a semana atual
SELECT DAY, COUNT(STATUS) AS Deployments
FROM (SELECT DATETIME_TRUNC(CreateTime, WEEK) AS WEEK,
DATETIME_TRUNC(CreateTime, DAY) AS DAY,
STATUS
FROM `projectID.datasetName.tableName`
WHERE STATUS="SUCCESS")
WHERE WEEK = DATETIME_TRUNC(CURRENT_DATETIME(), WEEK)
GROUP BY DAY
Para ver mais consultas de exemplo, consulte o arquivo README do BigQuery do Cloud Build no repositório cloud-build-notifiers
no GitHub.
Para saber mais sobre como consultar dados usando o BigQuery, consulte Como consultar e visualizar dados.
Como usar a CEL para filtrar eventos de build
O Cloud Build usa a CEL com a variável build
nos campos
listados no recurso Build
para acessar os campos associados ao evento de build, como o
ID do gatilho, a lista de imagens ou os valores de substituição. Use a string filter
para filtrar eventos de build no arquivo de configuração do build usando
qualquer campo listado no recurso
Build. Para encontrar a sintaxe exata associada ao seu campo, consulte a
cloudbuild.proto
.
Como filtrar por ID do acionador
Para filtrar por ID de gatilho, especifique o valor do ID do gatilho no campo filter
usando build.build_trigger_id
, em que trigger-id
é
o ID do gatilho como uma string:
filter: build.build_trigger_id == trigger-id
Como filtrar por status
Para filtrar por status, especifique o status do build que você quer filtrar no
campo filter
usando build.status
.
O exemplo a seguir mostra como filtrar eventos de build com um status SUCCESS
usando o campo filter
:
filter: build.status == Build.Status.SUCCESS
Também é possível filtrar builds com status variados. O exemplo a seguir mostra
como filtrar eventos de build com um status SUCCESS
, FAILURE
ou
TIMEOUT
usando o campo filter
:
filter: build.status in [Build.Status.SUCCESS, Build.Status.FAILURE, Build.Status.TIMEOUT]
Para ver valores de status adicionais pelos quais você pode filtrar, consulte Status na referência do recurso do Build.
Como filtrar por tag
Para filtrar por tag, especifique o valor da tag no campo filter
usando build.tags
, em que tag-name
é
o nome da tag:
filter: tag-name in build.tags
É possível filtrar com base no número de tags especificadas no evento de build
usando size
. No exemplo a seguir, o campo filter
filtra
eventos de build que têm exatamente duas tags especificadas, uma delas como
v1
:
filter: size(build.tags) == 2 && "v1" in build.tags
Como filtrar por imagens
Para filtrar por imagens, especifique o valor da sua imagem no campo filter
usando build.images
, em que image-name
é o nome completo
da imagem conforme listado no Artifact Registry, como
us-east1-docker.pkg.dev/my-project/docker-repo/image-one
:
filter: image-name in build.images
No exemplo a seguir, o filter
filtra eventos de build com
us-east1-docker.pkg.dev/my-project/docker-repo/image-one
ou
us-east1-docker.pkg.dev/my-project/docker-repo/image-two
especificados como
nomes de imagem:
filter: "us-east1-docker.pkg.dev/my-project/docker-repo/image-one" in build.images || "us-east1-docker.pkg.dev/my-project/docker-repo/image-one" in build.images
Como filtrar por tempo
É possível filtrar eventos de build com base no tempo de criação, horário de início ou
horário de término de um build especificando uma das seguintes opções no campo
filter
: build.create_time
, build.start_time
ou build.finish_time
.
No exemplo a seguir, o campo filter
usa timestamp
para filtrar
eventos de build com um horário de solicitação para criar o build em 20 de julho de 2020, às 6h:
filter: build.create_time == timestamp("2020-07-20:T06:00:00Z")
Também é possível filtrar eventos de build por comparações de tempo. No exemplo a seguir,
o campo filter
usa timestamp
para filtrar eventos de versão com um horário de início
entre 6 de julho de 2020, às 6h, e 30 de julho de 2020, às 6h.
filter: timestamp("2020-07-20:T06:00:00Z") >= build.start_time && build.start_time <= timestamp("2020-07-30:T06:00:00Z")
Para saber mais sobre como os fusos horários são expressos em CEL, consulte a definição de linguagem para fusos horários.
Para filtrar por duração de um build, use duration
para comparar carimbos de data/hora.
No exemplo a seguir, o campo filter
usa duration
para filtrar
eventos de build com um build executado por pelo menos cinco minutos:
filter: build.finish_time - build.start_time >= duration("5m")
Como filtrar por substituição
É possível filtrar por substituição especificando a variável de substituição no campo filter
usando build.substitutions
. No exemplo a seguir,
o campo filter
lista versões que contêm a variável de substituição
substitution-variable e verifica se o substitution-variable corresponde ao substitution-value especificado:
filter: build.substitutions[substitution-variable] == substitution-value
Em que:
substitution-variable
é o nome da variável de substituição.substitution-value
é o nome do valor de substituição.
Também é possível filtrar por padrão os valores das variáveis de substituição. No exemplo a seguir, o campo filter
lista os builds que têm o nome da ramificação master
e os builds que têm o nome de repositório github.com/user/my-example-repo
. As variáveis de substituição padrão BRANCH_NAME
e REPO_NAME
são transmitidas como chaves para o build.substitutions
:
filter: build.substitutions["BRANCH_NAME"] == "master" && build.substitutions["REPO_NAME"] == "github.com/user/my-example-repo"
Se você quiser filtrar strings usando expressões regulares, use a
função integrada matches
. No exemplo abaixo, o campo filter
filtra as
criações com status FALHA ou TEMPO LIMITE e também tem uma variável de
substituição de versão TAG_NAME
com um valor correspondente à expressão regular
v{DIGIT}.{DIGIT}.{3 DIGITS})
filter: build.status in [Build.Status.FAILURE, Build.Status.TIMEOUT] && build.substitutions["TAG_NAME"].matches("^v\\d{1}\\.\\d{1}\\.\\d{3}$")
Para ver uma lista de valores de substituição padrão, consulte Como usar substituições padrão.
A seguir
- Saiba mais sobre os notificadores do Cloud Build.
- Saiba como se inscrever para criar notificações.
- Saiba como gravar um arquivo de configuração da compilação do Cloud Build.