Armazenar e consultar 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 para onde enviar os registros de build

É possível configurar o Cloud Build para enviar registros de build para um bucket no Cloud Storage, um bucket no Cloud Logging ou ambos.

• Se você quiser controlar o período de retenção dos seus registros de build armazenados, envie-os para o Cloud Logging. O Cloud Logging também oferece mais opções para pesquisar um bucket em busca de logs de build específicos.

• Em alguns casos, há um atraso entre o momento em que um registro de build é gerado e o momento em que o Logging o recebe. O envio de registros de build para um bucket no Cloud Storage pode reduzir essa latência.

O Cloud Storage e o Logging permitem armazenar registros em um bucket padrão criado pelo Google ou em um bucket personalizado criado pelo usuário. Os buckets padrão permitem que você visualize os registros armazenados, mas não permitem mudar nada no bucket. Se você precisar de controle total sobre o bucket usado para armazenamento de registros de build, envie os registros para um bucket criado pelo usuário.

Armazenar registros de build em buckets padrão

O Cloud Logging e o Cloud Storage têm buckets padrão em que você pode armazenar os registros de build. Esses buckets são criados e pertencem ao Google e podem receber registros de várias regiões. Para enviar os logs de build para um desses buckets, configure o LoggingMode do arquivo de configuração do build com um dos seguintes valores:

• GCS_ONLY: os registros são armazenados no bucket padrão do Cloud Storage.

• CLOUD_LOGGING_ONLY: os registros são armazenados no bucket de registro padrão.

• LEGACY: os registros são armazenados nos dois buckets padrão.

O bucket de registro padrão tem uma política de retenção de 30 dias para registros armazenados. Para definir uma política de retenção personalizada para os registros de build armazenados no Logging, armazene os registros de build em um bucket personalizado.

O bucket padrão do Cloud Storage não tem uma política de retenção.

Armazenar registros de build em um bucket do Cloud Storage específico do usuário e da região

Se você enviar registros de build para o bucket padrão do Cloud Storage, o Cloud Build os armazenará em uma região especificada pelo Google, que pode ser diferente do local em que você executa um build. No entanto, também é possível configurar o build para que o Cloud Build envie logs de build para um bucket do Cloud Storage pertencente ao usuário na mesma região em que você executa o build. Essa configuração oferece mais controle sobre o local dos dados de build log, o que pode ajudar a cumprir os requisitos de residência de dados.

Conceda permissões do IAM:

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, essa conta de serviço terá as permissões necessárias do IAM por padrão. Você não precisa conceder permissões adicionais. Caso contrário, faça o seguinte:

Para receber as permissões necessárias para armazenar logs de build em um bucket específico da região e do usuário, peça ao administrador para conceder a você o papel do IAM de 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 conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.

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

1. No arquivo de configuração de build, adicione a opção defaultLogsBucketBehavior e defina o valor 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 os 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. Os builds adicionais 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 vários buckets para seus registros de build.

Os buckets padrão do Cloud Storage específicos da região não têm uma política de retenção. No entanto, é possível automatizar a exclusão de logs de build do bucket configurando uma regra de ciclo de vida de objetos.

Armazenar registros de build em buckets criados pelo usuário

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

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

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

Conceda permissões do IAM:

Para receber as permissões necessárias para armazenar logs de build em um bucket do Cloud Logging criado pelo usuário, peça ao administrador para conceder a você o papel do IAM de Gravador de configuração de logs (roles/logging.configWriter) no 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 conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.

Configure o bucket de registro:

1. Crie um bucket e defina um valor para o campo Período de retenção.

2. Crie um coletor para encaminhar 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 ID do projeto do Google Cloud.

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

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:

Conceda permissões do IAM:

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, a conta de serviço legada do Cloud Build terá as permissões necessárias do IAM por padrão. Você não precisa conceder permissões adicionais. Caso contrário, faça o seguinte:

Para receber as permissões necessárias para armazenar registros do build em um bucket do Cloud Storage criado pelo usuário, peça ao administrador para conceder a você o papel do IAM de 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 conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.

Configure o bucket do Cloud Storage:

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 exemplo de 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.

Precedência entre as configurações de registros

Se você definir um bucket do Cloud Storage criado pelo usuário em logsBucket, o Cloud Build vai enviar os registros de build para o bucket criado pelo usuário em vez do bucket padrão do Cloud Storage.

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. 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 no arquivo de configuração, o Cloud Build define logging: LEGACY e armazena os registros de build no bucket padrão do Cloud Storage. A definição de defaultLogsBucketBehavior como REGIONAL_USER_OWNED_BUCKET substitui logging: LEGACY.

Veja os registros das versões

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

Conceda permissões do IAM:

Para receber as permissões necessárias para visualizar os 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:

• Acesse os 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 acessar os registros de build.
  • Acessador de exibição de registros (roles/logging.viewAccessor): os principais usuários que querem acessar os registros de build.
• Acessar os registros de build no bucket padrão do Cloud Storage: Visualizador (roles/viewer): o projeto em que o build está configurado
• Confira os registros de build em "Registro": Visualizador de registros (roles/logging.viewer): os principais usuários que querem acessar os 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 conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.

Confira os registros de build em Google Cloud:

gcloud builds log build-id

Conferir os registros de build no GitHub e no GitHub Enterprise:

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

Para conferir os logs de build no GitHub e no GitHub Enterprise, faça o seguinte:

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.

Excluir buckets e registros de build

Para receber as permissões necessárias para excluir logs 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:

• Exclua os 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 os 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
• Exclua um bucket de registro 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 conseguir as permissões necessárias por meio de papéis personalizados ou de 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 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 Excluir buckets na documentação do Cloud Storage.

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

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.