Armazenar e visualizar registros de build

Configure o arquivo de configuração do build para armazenar os registros de build em buckets de registros para que você possa agrupá-los e analisá-los usando as ferramentas do Cloud Logging e do Cloud Storage. A configuração do armazenamento de registros de build permite maior controle sobre o armazenamento e a análise dos registros. Se você deixar as configurações de armazenamento de registros de build indefinidas, o Cloud Build os armazenará em um bucket de propriedade do Google CloudGoogle com menos opções de análise de registros de build.

Esta página descreve como armazenar registros de build em diferentes tipos de buckets e como visualizar e excluir registros armazenados.

Antes de começar

Confira se você está familiarizado com as opções de arquivo de configuração do build para configurar o armazenamento de registros de build e como a propriedade do bucket afeta a acessibilidade do registro. Para mais informações, consulte Opções de armazenamento de registros de build.

Armazenar registros de build em buckets criados pelo usuário

Os buckets criados pelo usuário oferecem maior controle sobre o gerenciamento e a configuração dos buckets.

Observação: você terá um custo para armazenar registros de build no seu próprio bucket. Para detalhes de preços, consulte Preços do Cloud Storage e Preços do Cloud Logging.

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

Os buckets de registros criados pelo usuário permitem ajustar o período de armazenamento dos registros de build armazenados. Para armazenar os registros de build em um bucket criado pelo usuário no Logging, faça o seguinte:

Conceder permissões do IAM:

Para receber as permissões necessárias para armazenar registros de build em um bucket do Cloud Logging criado pelo usuário, peça ao administrador para conceder a você o papel do IAM Gravador de configuração de registros (roles/logging.configWriter) na conta ou conta de serviço do seu projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível receber as permissões necessárias por meio de papéis personalizados ou outros papéis predefinidos.

Configurar o bucket do Logging:

1. Crie um bucket e defina um valor para o campo período de armazenamento.

2. Crie um coletor para rotear os registros de build para o novo bucket:

   1. Insira o seguinte para o filtro de inclusão de build do coletor:

      logName = "projects/PROJECT_ID/logs/cloudbuild"
      

      Substitua PROJECT_ID pelo Google Cloud ID do projeto.

   2. (Opcional) Para impedir que os registros de build sejam enviados para o bucket padrão do Logging, siga o exemplo em Parar de armazenar entradas de registro em buckets de registros.

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

Para armazenar os registros de build em um bucket do Cloud Storage criado pelo usuário, faça o seguinte:

Conceder permissões do IAM:

Se o bucket do Cloud Storage e o Cloud Build estiverem no mesmo Google Cloud projeto e você estiver usando a conta de serviço legada do Cloud Build, sua conta de serviço legada do Cloud Build terá as permissões necessárias do IAM por padrão. Não é necessário conceder outras permissões. Caso contrário, faça o seguinte:

Para receber as permissões necessárias para armazenar registros de build em um bucket do Cloud Storage criado pelo usuário, peça ao administrador para conceder a você o Administrador do Storage (roles/storage.admin) papel do IAM na conta de serviço usada para o build. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível receber as permissões necessárias por meio de papéis personalizados ou outros papéis predefinidos.

Configurar o bucket do Cloud Storage:

1. No seu Google Cloud projeto, crie um bucket do Cloud Storage sem 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 acionadores.

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

Armazenar registros de build em buckets do Cloud Storage específicos da região

É possível configurar o build para que o Cloud Build envie registros de build para um bucket do Cloud Storage de propriedade do usuário na mesma região do build. O alinhamento das regiões do bucket de armazenamento de build e de registro de build pode ajudar você a atender aos requisitos de residência de dados.

Conceder permissões do IAM:

Se o bucket do Cloud Storage e o Cloud Build estiverem no mesmo Google Cloud projeto e você estiver usando a conta de serviço legada do Cloud Build, então essa conta de serviço terá as permissões necessárias do IAM por padrão. Não é necessário conceder outras permissões. Caso contrário, faça o seguinte:

Para receber as permissões necessárias para armazenar registros de build em um bucket específico da região e de propriedade do usuário, peça ao administrador para conceder a você o papel do IAM Administrador do Storage (roles/storage.admin) na conta de serviço usada para o build. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível receber as permissões necessárias por meio de papéis personalizados ou outros papéis predefinidos.

Configurar o bucket do Cloud Storage específico da região:

1. No arquivo de configuração do 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"
       }
   }
   

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

   Quando você executa o build, o Cloud Build cria o novo bucket na região em que você está executando o build e armazena os registros de build nesse bucket. Outros builds no mesmo projeto e região vão usar o bucket atual, desde que REGIONAL_USER_OWNED_BUCKET esteja ativo. Esse bucket é de propriedade do usuário, então você pode configurá-lo como se fosse um bucket criado pelo usuário.

   Se você definir a opção REGIONAL_USER_OWNED_BUCKET e criar builds em várias regiões, o Cloud Build vai criar um bucket do Cloud Storage para cada região exclusiva.

Também é possível usar um bucket criado pelo usuário se você precisar alinhar a região do build e o bucket de registros. Nesse caso, selecione um bucket criado pelo usuário que tenha a mesma região ou crie um. Se você quiser criar um, siga as etapas para armazenar registros de build em buckets criados pelo usuário e verifique se o bucket criado pelo usuário tem a mesma região do build.

Veja os registros das versões

Para ver os registros de build, faça o seguinte:

Conceder permissões do IAM:

Para receber as permissões necessárias para visualizar registros de build no Cloud Storage ou no Logging, peça ao administrador para conceder a você os seguintes papéis do IAM na conta de serviço usada para o build:

• Visualizar registros de build em um bucket do Cloud Storage criado ou de propriedade do usuário:
  • Leitor de objetos do Storage (roles/storage.objectViewer) – os principais que querem visualizar registros de build
  • Acessador de visualização de registros (roles/logging.viewAccessor) – os principais que querem visualizar registros de build
• Visualizar registros de build no bucket padrão do Cloud Storage: Leitor (roles/viewer) – o projeto em que o build está configurado
• Visualizar registros de build no Logging: Visualizador de registros (roles/logging.viewer) – os principais que querem visualizar registros de build

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível receber as permissões necessárias por meio de papéis personalizados ou outros papéis predefinidos.

Observação: é possível conceder os papéis Proprietário (roles/owner) ou Editor (roles/editor) no nível do projeto para permitir que os principais visualizem registros de build de buckets criados pelo Cloud Build e de propriedade do usuário. No entanto, recomendamos usar o papel Leitor nesse caso para que a atribuição de papéis esteja em conformidade com o princípio de privilégio mínimo. Se você não quiser conceder o papel Leitor básico, use buckets criados pelo usuário em vez disso. Recomendamos essa prática, especialmente se os builds forem invocados por acionadores e você só quiser conceder acesso para invocar builds e visualizar o progresso do build.

Visualizar registros de build em Google Cloud

Console

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

   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 build.

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

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

6. Se os registros de build estiverem armazenados na geração de registros, no painel Registro do build, clique no ícone para visualizar os registros na Análise de registros.

gcloud

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

gcloud builds log build-id

Visualizar registros de build no GitHub e no GitHub Enterprise

Se você criar um acionador do GitHub ou do GitHub Enterprise com a CLI gcloud ou a API Cloud Build e especificar --include-logs-with-status como uma opção, então será possível visualizar os registros de build no GitHub e no GitHub Enterprise.

Para visualizar registros de build no GitHub e no GitHub Enterprise, faça o seguinte:

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

2. Navegue até a lista de confirmações.

3. Localize a linha da confirmação para a qual você quer visualizar os registros de build.

4. Clique no ícone de resultado na linha da confirmação.

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

5. Clique em Detalhes na linha para a qual você quer visualizar os registros de build.

   A página Resumo associada à confirmação será exibida. Se você tiver criado um acionador usando a flag --include-logs-with-status, os registros de build serão exibidos na seção Detalhes da página.

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

Excluir registros de build e buckets

Para receber as permissões necessárias para excluir registros de build e buckets no Cloud Storage, peça ao administrador para conceder a você os seguintes papéis do IAM na conta de serviço usada para o build:

• Excluir registros de build em um bucket do Cloud Storage criado ou de propriedade do usuário: Administrador do Storage (roles/storage.admin) – o usuário ou a conta de serviço que exclui registros de build
• Excluir um bucket do Cloud Storage criado ou de propriedade do usuário: Administrador do Storage (roles/storage.admin) – o usuário ou a conta de serviço que exclui buckets
• Excluir um bucket do Logging criado pelo usuário: Gravador de configuração de registros (roles/logging.configWriter) – seu projeto

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível receber as permissões necessárias por meio de papéis personalizados ou outros papéis predefinidos.

Para excluir registros de build em um bucket do Cloud Storage criado ou de propriedade do usuário, siga as instruções em Como excluir objetos na documentação do Cloud Storage.

Para excluir um bucket do Cloud Storage criado ou de propriedade do usuário, siga as instruções em Como excluir buckets na documentação do Cloud Storage.

Para excluir um bucket do Logging criado pelo usuário, siga as instruções em Excluir um bucket na documentação do Logging.

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.