Armazenar e gerenciar registros de build

Quando você executa compilações, o Cloud Build coleta e armazena seus registros de build. Esta página explica como armazenar, visualizar e excluir registros de build.

Escolher onde armazenar os registros de build

É possível configurar o Cloud Build para armazenar registros de compilação no Cloud Logging ou no Cloud Storage incluindo o campo logging no arquivo de configuração do Cloud Build. de dados. Se você não especificar um campo logging no arquivo de configuração de versão, o Cloud Build armazenará registros de versão no Logging e no Cloud Storage.

As etapas a seguir armazenam registros de criação somente no Logging:

1. No arquivo de configuração de build, defina o valor de logging como CLOUD_LOGGING_ONLY:

   YAML

   steps:
   - name: 'gcr.io/cloud-builders/docker'
     args: ['build', '-t', 'us-east1-docker.pkg.dev/myproject/myimage', '.']
   options:
     logging: CLOUD_LOGGING_ONLY
   

   JSON

   {
     "steps": [
     {
       "name": "gcr.io/cloud-builders/docker",
       "args": [
         "build",
         "-t",
         "us-east1-docker.pkg.dev/myproject/myimage",
         "."
       ]
     }
     ],
     "options": {
       "logging": "CLOUD_LOGGING_ONLY"
     }
   }
   

2. Use o arquivo de configuração do build para iniciar um build usando a linha de comando, a API ou os acionadores.

Mapear campos de registro de build para campos de entrada de registro

É possível configurar o JSON dos seus registros de build para que campos específicos sejam mapeados para campos LogEntry quando o registro de build for enviado para o Logging. Por exemplo, se o registro de build contiver um message, a mensagem vai aparecer em textPayload ou jsonPayload.message na entrada de registro resultante. Os campos de registro de build que não podem ser mapeados aparecem na entrada de registro jsonPayload.

Para ativar o mapeamento de campo nos registros de build, defina o campo BuildOptions enableStructuredLogging como TRUE.

A tabela a seguir mostra os campos de registro de build que são mapeados para um campo de entrada de registro:

Campo BuildLog (JSON)	Campo LogEntry	Descrição	Observações
message	textPayload ou jsonPayload.message	Permite que os usuários definam a mensagem de registro	Precisa ser uma string. Se o build log contiver apenas campos mapeáveis, a mensagem vai aparecer em textPayload. Caso contrário, a mensagem vai aparecer em jsonPayload.message. Se o build log tiver várias etapas, o identificador de etapa vai aparecer no início da mensagem.
severity	severity	Permite que os usuários definam a gravidade do registro.	Precisa ser um tipo enumerado de LogSeverity.

Os campos de registro de build a seguir não podem ser mapeados e serão excluídos da entrada de registro se aparecerem em um registro de build:

• httpRequest
• logging.googleapis.com/insertId
• logging.googleapis.com/labels
• logging.googleapis.com/operation
• logging.googleapis.com/sourceLocation
• logging.googleapis.com/spanId
• logging.googleapis.com/trace
• logging.googleapis.com/trace_sampled
• time
• timestamp
• timestampSeconds
• timestampNanos

Todos os outros campos de registro de build vão aparecer como parte do jsonPayload da entrada de registro.

Armazenar registros de build no bucket padrão criado pelo Google

Por padrão, o Cloud Build armazena os registros de build em um bucket do Cloud Storage criado pelo Google. É possível visualizar o armazenamento de registros de build no bucket do Cloud Storage criado pelo Google, mas não é possível fazer outras alterações nele. Se você precisar de controle total sobre seu bucket de registros, armazene os registros em um bucket do Cloud Storage criado pelo usuário.

Armazenar registros de build em um bucket criado pelo usuário

Permissões do IAM:

Para armazenar registros de build no seu próprio bucket do Cloud Storage, primeiro conceda as permissões do IAM necessárias à conta de serviço que você está usando para o build:

• Se o bucket do Cloud Storage e o Cloud Build estiverem no mesmo projeto do Google Cloud e você estiver usando a conta de serviço legada do Cloud Build, ela terá as permissões necessárias do IAM por padrão. Você não precisa conceder permissões adicionais.

• Em qualquer outro caso, conceda o papel de Administrador do Storage à conta de serviço que você está usando para o build:

  1. Abra a página "IAM" no projeto em que o bucket do Cloud Storage está localizado:

     Abra a página do IAM

  2. Clique em Conceder acesso.

  3. Insira o endereço de e-mail da conta de serviço.

  4. Selecione Cloud Storage > Administrador do Storage.

  5. Clique em Save.

Para especificar um bucket do Cloud Storage para armazenar registros de builds:

1. No projeto do Google Cloud, crie um bucket do Cloud Storage sem uma política de retenção definida para armazenar os registros de build.

2. No arquivo de configuração do build, adicione um campo logsBucket que aponte para o bucket do Cloud Storage criado para armazenar registros da build. O arquivo de configuração de build a seguir contém instruções para criar uma imagem de contêiner e armazenar os registros de build em um bucket chamado mylogsbucket:

   YAML

       steps:
       - name: 'gcr.io/cloud-builders/docker'
         args: [ 'build', '-t', 'us-east1-docker.pkg.dev/myproject/myimage', '.' ]
       logsBucket: 'gs://mylogsbucket'
       options:
         logging: GCS_ONLY
   

   JSON

       {
         "steps": [
          {
            "name": "gcr.io/cloud-builders/docker",
            "args": [
              "build",
              "-t",
              "us-east1-docker.pkg.dev/myproject/myimage",
              "."
            ]
          }
          ],
          "logsBucket": "gs://mylogsbucket",
          "options": {
            "logging": "GCS_ONLY"
          }
       }
   

3. Use o arquivo de configuração do build para iniciar um build usando a linha de comando, a API ou os acionadores.

Quando o build é concluído, o Cloud Build armazena os registros no bucket do Cloud Storage especificado no arquivo de configuração de build.

Armazenar registros de build em um bucket regionalizado e de propriedade do usuário

Por padrão, o Cloud Build armazena registros de build em uma região especificada pelo Google que pode ser diferente do local em que você executa um build. A opção defaultLogsBucketBehavior permite configurar o Cloud Build para usar um bucket de registros padrão no seu projeto e na mesma região do build. Essa configuração oferece mais controle sobre o local dos dados de registro, o que pode ajudar a cumprir os requisitos de residência de dados.

Você vai incorrer em custos para armazenar registros no seu próprio projeto. Para detalhes sobre preços, consulte Preços do Cloud Storage.

Configure o Cloud Build para usar logs regionalizados de propriedade do usuário:

1. Conceda as permissões necessárias do IAM.

   • Se você estiver usando a conta de serviço legada do Cloud Build, ela terá as permissões necessárias do IAM por padrão. Você não precisa conceder outras permissões.

   • Para outras contas de serviço, conceda o papel de Administrador de armazenamento à conta de serviço que você está usando para o build. Para instruções sobre como conceder um papel a uma conta de serviço, consulte Como conceder papéis no projeto.

2. Na configuração de build, adicione a opção defaultLogsBucketBehavior e defina o valor dela como REGIONAL_USER_OWNED_BUCKET:

   YAML

   steps:
   - name: 'gcr.io/cloud-builders/docker'
     args: [ 'build', '-t', 'us-central1-docker.pkg.dev/myproject/myrepo/myimage', '.' ]
   options:
     defaultLogsBucketBehavior: REGIONAL_USER_OWNED_BUCKET
   

   JSON

   {
     "steps": [
       {
         "name": "gcr.io/cloud-builders/docker",
         "args": [
           "build",
           "-t",
           "us-central1-docker.pkg.dev/myproject/myrepo/myimage",
           "."
         ]
       }
       ],
       "options": {
         "defaultLogsBucketBehavior": "REGIONAL_USER_OWNED_BUCKET"
       }
   }
   

3. Use o arquivo de configuração do build para iniciar um build usando a linha de comando, a API ou os acionadores.

   Quando você executa o build, o Cloud Build cria o novo bucket de registros na região em que você está executando o build e armazena os registros de build nesse bucket. Os builds subsequentes no mesmo projeto e região vão usar o bucket atual por padrão.

Se você definir a opção defaultLogsBucketBehavior e criar builds em várias regiões, o Cloud Build vai criar vários buckets para seus logs de build.

Os registros de build regionalizados armazenados no seu projeto não têm uma política de retenção. Essa configuração não pode ser alterada.

Precedência entre as configurações de registros

Se você estiver adicionando a opção defaultLogsBucketBehavior a um arquivo de configuração de build existente e tiver configurado anteriormente as opções logging ou logsBucket, recomendamos que você exclua essas configurações para evitar conflitos entre elas.

Mais especificamente, o defaultLogsBucketBehavior não vai funcionar se você tiver configurado:

• logging: CLOUD_LOGGING_ONLY para armazenar seus registros de build no Cloud Logging.
• logging: NONE para desativar a geração de registros.

Quando você executa um build sem opções de registro definidas na configuração de build, o Cloud Build define logging: LEGACY e armazena registros no bucket padrão do Cloud Storage criado pelo Google. Se você adicionar defaultLogsBucketBehavior: REGIONAL_USER_OWNED_BUCKET, essa opção substituirá logging: LEGACY.

Veja os registros das versões

Permissões do IAM:

• Se os registros do build estiverem no Logging, conceda o papel Visualizador de registros no projeto em que o build está configurado para principais que querem visualizar registros de compilação:

  1. Abra a página do IAM:

     Abrir a página do IAM

  2. Selecione o projeto e clique em Abrir.

  3. Na tabela de permissões, localize o ID de e-mail do participante e clique no ícone de lápis.

  4. Selecione o papel Logging > Visualizador de registros.

  5. Clique em Salvar.

• Se os registros de build estiverem no bucket padrão do Cloud Storage criado pelo Google, conceda o papel Visualizador de projetos no projeto em que o build está configurado para principais que querem acessar os registros de build:

  1. Abra a página do IAM:

     Abrir a página do IAM

  2. Selecione o projeto e clique em Abrir.

  3. Na tabela de permissões, localize o ID de e-mail do participante e clique no ícone de lápis.

  4. Selecione o papel Projeto > Leitor.

  5. Clique em Salvar.

  Observação: os papéis de proprietário e editor do projeto também permitem que os principais visualizem registros de build do bucket padrão do Cloud Storage. Isso ocorre porque o papel de proprietário inclui as permissões no papel de editor e o papel de editor inclui as permissões no papel de leitor. Para conferir os registros de build no bucket padrão do Cloud Storage, recomendamos conceder o papel de visualizador do projeto para obedecer ao princípio de segurança de privilégio mínimo.
  Observação: para evitar a concessão do papel básico de visualizador do projeto, armazene os registros de build em um bucket especificado pelo usuário. Recomendamos essa prática especialmente se suas versões forem invocadas usando gatilhos e você quiser conceder acesso apenas para invocar versões e conferir o progresso delas.

  Se os registros de build estiverem em um bucket do Cloud Storage criado ou de propriedade do usuário, conceda o papel Leitor de objetos do Storage aos principais que quiserem acessar os registros de build:

  1. Abra a página do IAM:

     Abrir a página do IAM

  2. Selecione o projeto e clique em Abrir.

  3. Na tabela de permissões, localize o ID de e-mail do participante e clique no ícone de lápis.

  4. Selecione o papel Cloud Storage > Leitor de objetos do Storage.

  5. Clique em Salvar.

Para conferir os registros de build no Cloud Build:

Console

1. Abra a página do Cloud Build no console do Google Cloud.

   Abra a página do Cloud Build

2. Selecione o projeto e clique em Abrir.

3. No menu suspenso Região, selecione a região do seu build.

4. Na página Histórico de build, clique em um build específico.

5. Na página Detalhes do build, em Etapas, clique em Resumo do build para conferir os registros de build inteiros ou clique em uma etapa do build para conferir os registros de essa etapa.

   

6. Se os registros forem armazenados no Logging, no painel Registro do build, clique no ícone para visualizar os registros no Explorador de registros.

   

gcloud

Execute o comando gcloud builds log, em que build-id é o ID do build para o qual você quer receber registros. O ID do build é exibido no final do processo de envio do build quando você executa gcloud builds submit ou na coluna "ID" quando você executa gcloud builds list.

gcloud builds log build-id

Para conferir os registros de build no GitHub e no GitHub Enterprise:

Se você criar um gatilho do GitHub ou do GitHub Enterprise e especificar --include-logs-with-status como uma opção, poderá acessar os registros de build no GitHub e no GitHub Enterprise.

Para conferir os registros de build no GitHub e no GitHub Enterprise:

1. Navegue até o repositório associado ao acionador.

2. Acesse a lista de confirmações.

3. Localize a linha do commit para o qual você quer acessar os registros de build.

4. Clique no ícone de resultado na linha do seu commit.

   Uma lista de verificações associadas à sua confirmação será exibida.

5. Clique em Detalhes na linha em que você quer conferir os registros de build.

   A página Resumo associada à sua confirmação será mostrada. Se você criou um acionador usando a flag --include-logs-with-status, os logs de build vão aparecer na seção Details da página.

Observação: a conta de serviço usada para o gatilho precisa incluir o papel roles/logging.viewer para enviar os logs de build ao GitHub.

Excluir registros de build

Não é possível excluir os registros de build no bucket de registros criado pelo Google.

Para excluir os registros da build em um bucket de registros criado pelo usuário:

1. Conceda o papel Administrador de objetos do Storage ao usuário ou à conta de serviço que exclua os registros.

2. Exclua os registros de build seguindo as instruções para excluir objetos do Cloud Storage em Como excluir objetos.

Para excluir o bucket de registros criados pelo usuário:

1. Conceda o papel Administrador do Storage ao usuário ou à conta de serviço excluindo o bucket de registros.

2. Exclua o bucket de registros usando as instruções para excluir um bucket em Como excluir buckets.

A seguir

• Saiba mais sobre registros de auditoria criados pelo Cloud Build.
• Saiba como ver os resultados da build.
• Saiba mais sobre permissões de IAM do Cloud Build.