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 onde enviar 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 armazenamento dos 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 registros de build específicos.

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

Com o Cloud Storage e o Logging, é possível armazenar registros em um bucket padrão criado pelo Google ou em um bucket personalizado criado pelo usuário. Com os buckets padrão, é possível ver os registros armazenados, mas não mudar nada neles. 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 registros de build a um desses buckets, configure o LoggingMode do arquivo de configuração de 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 padrão do Logging.

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

O bucket padrão do Logging tem uma política de retenção de 30 dias para registros armazenados. Para definir uma política de retenção personalizada para 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 da região e de propriedade do usuário

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 seu 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 em que você executa o build. Essa configuração oferece mais controle sobre o local dos dados de registro de build, o que pode ajudar você a cumprir os requisitos de residência de dados.

Conceder permissões do IAM:

Se o bucket do Cloud Storage e o Cloud Build estiverem no mesmo projeto Google Cloud e você estiver usando a conta de serviço legada do Cloud Build, essa conta 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 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 de Administrador do Storage (roles/storage.admin) na conta de serviço usada para seu 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 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 existente enquanto REGIONAL_USER_OWNED_BUCKET estiver ativo. Como esse bucket é de propriedade do usuário, 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 os registros de build.

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

Armazenar registros de build em buckets criados pelo usuário

Com os buckets criados pelo usuário, você tem mais controle sobre o gerenciamento e a configuração dos seus buckets de registros.

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

Com os buckets do Logging criados pelo usuário, é possível 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 de Gravador de configuração de registros (roles/logging.configWriter) no 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.

Configure o bucket do Logging:

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

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 seu coletor:

      logName = "projects/PROJECT_ID/logs/cloudbuild"
      

      Substitua PROJECT-ID pelo ID do seu projeto Google Cloud .

   2. (Opcional) Para impedir que seus registros sejam enviados ao bucket padrão do Logging, 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:

Conceder permissões do IAM:

Se o bucket do Cloud Storage e o Cloud Build estiverem no mesmo projeto 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. 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 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 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 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 configurações de registros

Se você definir um bucket do Cloud Storage criado pelo usuário em logsBucket, o Cloud Build 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 e já tiver configurado as opções logging ou logsBucket, recomendamos que 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 os 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 de build, o Cloud Build define logging: LEGACY e armazena os registros de build no bucket padrão do Cloud Storage. Definir 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:

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:

• Veja 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 ver os registros de build
  • Acessador de exibição de registros (roles/logging.viewAccessor): os principais que querem ver os registros de build
• Acesse os registros de build no bucket padrão do Cloud Storage: Leitor (roles/viewer): o projeto em que o build está configurado
• Ver registros de build no Logging: Visualizador de registros (roles/logging.viewer): os principais que querem ver 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.

Ver registros de build em Google Cloud:

gcloud builds log build-id

Ver registros de build no GitHub e no GitHub Enterprise:

Se você criar um gatilho 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, poderá conferir os registros de build no GitHub e no GitHub Enterprise.

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

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

2. Acesse sua lista de commits.

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

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

   Você vai ver uma lista de verificações associadas ao seu commit.

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

   A página Resumo associada ao commit vai aparecer. Se você criou um gatilho usando a flag --include-logs-with-status, os registros do build vão aparecer na seção Detalhes da página.

Excluir registros e buckets de build

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 seu build:

• Exclua os registros da 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 da build
• Exclua 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 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 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.