Memorizzare e visualizzare i log di build

Quando esegui le build, Cloud Build raccoglie e archivia i log di build. Questa pagina spiega come archiviare, visualizzare ed eliminare i log di build.

Scegliere dove inviare i log di build

Puoi configurare Cloud Build in modo da inviare i log di build a un bucket in Cloud Storage, a un bucket in Cloud Logging o a entrambi.

• Se vuoi controllare il periodo di conservazione dei log di build archiviati, inviali a Cloud Logging. Cloud Logging fornisce anche più opzioni per cercare log di build specifici in un bucket.

• In alcuni casi, si verifica un ritardo tra il momento in cui viene generato un log di build e il momento in cui Logging lo riceve. L'invio dei log di build a un bucket in Cloud Storage può ridurre la latenza.

Cloud Storage e Logging consentono di archiviare i log in un bucket predefinito creato da Google o in un bucket personalizzato creato dall'utente. I bucket predefiniti ti consentono di visualizzare i log archiviati nel bucket, ma non di modificare nulla al suo interno. Se hai bisogno del controllo completo sul bucket che utilizzi per l'archiviazione dei log di build, invia i log a un bucket creato dall'utente.

Archivia i log di build nei bucket predefiniti

Cloud Logging e Cloud Storage hanno entrambi bucket predefiniti in cui puoi archiviare i log di build. Questi bucket sono creati e di proprietà di Google e possono ricevere log da più regioni. Per inviare i log di build a uno di questi bucket, configura LoggingMode del file di configurazione della build con uno dei seguenti valori:

• GCS_ONLY: i log vengono archiviati nel bucket Cloud Storage predefinito.

• CLOUD_LOGGING_ONLY: i log vengono archiviati nel bucket di logging predefinito.

• LEGACY: i log vengono archiviati in entrambi i bucket predefiniti.

Il bucket Logging predefinito ha un criterio di conservazione di 30 giorni per i log archiviati. Per impostare un criterio di conservazione personalizzato per i log di build archiviati in Logging, archiviali in un bucket personalizzato.

Il bucket Cloud Storage predefinito non ha criteri di conservazione.

Archivia i log di build in un bucket Cloud Storage di proprietà dell'utente e specifico per la regione

Se invii i log di build al bucket Cloud Storage predefinito, Cloud Build li archivia in una regione specificata da Google che potrebbe essere diversa dalla località in cui esegui una build. Tuttavia, puoi anche configurare la build in modo che Cloud Build invii i log di build a un bucket Cloud Storage di proprietà dell'utente nella stessa regione in cui esegui la build. Questa configurazione ti offre un maggiore controllo sulla posizione dei dati dei log di build, il che può aiutarti a rispettare i requisiti di residenza dei dati.

Concedi autorizzazioni IAM:

Se il bucket Cloud Storage e Cloud Build si trovano nello stesso progetto Google Cloud e utilizzi il service account legacy di Cloud Build, questo account di servizio dispone delle autorizzazioni IAM necessarie per impostazione predefinita. Non devi concedere autorizzazioni aggiuntive. In caso contrario, procedi nel seguente modo:

Per ottenere le autorizzazioni necessarie per archiviare i log di build in un bucket di proprietà dell'utente e specifico per la regione, chiedi all'amministratore di concederti il ruolo IAM Amministratore archiviazione (roles/storage.admin) nell'account di servizio utilizzato per la build. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Configura il bucket Cloud Storage specifico per la regione:

1. Nel file di configurazione della build, aggiungi l'opzione defaultLogsBucketBehavior e imposta il relativo valore su 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. Utilizza il file di configurazione della build per avviare una build utilizzando la riga di comando, l'API o i trigger.

   Quando esegui la build, Cloud Build crea il nuovo bucket nella regione in cui esegui la build, quindi archivia i log di build in questo bucket. Le build successive nello stesso progetto e nella stessa regione utilizzeranno il bucket esistente finché REGIONAL_USER_OWNED_BUCKET è attivo. Questo bucket è di proprietà dell'utente, quindi puoi configurarlo come se fosse un bucket creato dall'utente.

Se imposti l'opzione REGIONAL_USER_OWNED_BUCKET e poi crei build in più regioni, Cloud Build crea più bucket per i log di build.

I bucket Cloud Storage predefiniti specifici per regione non hanno criteri di conservazione. Tuttavia, puoi automatizzare l'eliminazione dei log di build dal bucket configurando una regola del ciclo di vita degli oggetti.

Archivia i log di build in bucket creati dall'utente

I bucket creati dagli utenti ti offrono un maggiore controllo sulla gestione e la configurazione dei bucket di log.

Archiviazione dei log di build in un bucket Cloud Logging creato dall'utente

I bucket di logging creati dagli utenti consentono di modificare il periodo di conservazione dei log di build archiviati. Per archiviare i log di build in un bucket creato dall'utente in Logging, segui questi passaggi:

Concedi autorizzazioni IAM:

Per ottenere le autorizzazioni necessarie per archiviare i log di build in un bucket Cloud Logging creato dall'utente, chiedi all'amministratore di concederti il ruolo IAM Logs Configuration Writer (roles/logging.configWriter) nel progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Configura il bucket Logging:

1. Crea un bucket e imposta un valore per il campo Periodo di conservazione.

2. Crea un sink per indirizzare i log di build al nuovo bucket:

   1. Inserisci quanto segue per il filtro di inclusione della build del sink:

      logName = "projects/PROJECT_ID/logs/cloudbuild"
      

      Sostituisci PROJECT-ID con l'ID del tuo progetto Google Cloud .

   2. (Facoltativo) Per impedire che i log vengano inviati al bucket di logging predefinito, segui l'esempio riportato in Interrompere l'archiviazione delle voci di log nei bucket di log.

Archivia i log di build in un bucket Cloud Storage creato dall'utente

Per archiviare i log di build in un bucket Cloud Storage creato dall'utente, procedi come segue:

Concedi autorizzazioni IAM:

Se il bucket Cloud Storage e Cloud Build si trovano nello stesso progetto Google Cloud e utilizzi il service account legacy di Cloud Build, quest'ultimo dispone delle autorizzazioni IAM necessarie per impostazione predefinita. Non devi concedere autorizzazioni aggiuntive. In caso contrario, procedi nel seguente modo:

Per ottenere le autorizzazioni necessarie per archiviare i log di build in un bucket Cloud Storage creato dall'utente, chiedi all'amministratore di concederti il ruolo IAM Amministratore archiviazione (roles/storage.admin) sull'account di servizio utilizzato per la build. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Configura il bucket Cloud Storage:

1. Nel tuo Google Cloud progetto, crea un bucket Cloud Storage senza criteri di conservazione impostati per archiviare i log di build.

2. Nel file di configurazione della build, aggiungi un campo logsBucket che rimandi al bucket Cloud Storage che hai creato per archiviare i log di build. Il seguente file di configurazione della build di esempio contiene le istruzioni per creare un'immagine container e archiviare i log di build in un bucket denominato 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. Utilizza il file di configurazione della build per avviare una build utilizzando la riga di comando, l'API o i trigger.

Al termine della build, Cloud Build archivia i log nel bucket Cloud Storage specificato nel file di configurazione della build.

Precedenza tra le impostazioni dei log

Se definisci un bucket Cloud Storage creato dall'utente in logsBucket, Cloud Build invia i log di build al bucket creato dall'utente anziché al bucket Cloud Storage predefinito.

Se stai aggiungendo l'opzione defaultLogsBucketBehavior a un file di configurazione della build esistente e hai configurato in precedenza le opzioni logging o logsBucket, ti consigliamo di eliminare queste impostazioni per evitare conflitti tra le impostazioni. Nello specifico, defaultLogsBucketBehavior non funzionerà se hai configurato:

• logging: CLOUD_LOGGING_ONLY per archiviare i log di build in Cloud Logging.
• logging: NONE per disattivare la registrazione.

Quando esegui una build senza opzioni di logging impostate nel file di configurazione della build, Cloud Build imposta logging: LEGACY e archivia i log di build nel bucket Cloud Storage predefinito. L'impostazione defaultLogsBucketBehavior su REGIONAL_USER_OWNED_BUCKET esegue l'override di logging: LEGACY.

Visualizza i log di build

Per visualizzare i log di build:

Concedi autorizzazioni IAM:

Per ottenere le autorizzazioni necessarie per visualizzare i log di build in Cloud Storage o Logging, chiedi all'amministratore di concederti i seguenti ruoli IAM per il account di servizio utilizzato per la build:

• Visualizza i log di build in un bucket Cloud Storage creato o di proprietà dell'utente:
  • Visualizzatore oggetti Storage (roles/storage.objectViewer): i principal che vogliono visualizzare i log di build
  • Logs View Accessor (roles/logging.viewAccessor): le entità che vogliono visualizzare i log di build
• Visualizza i log di build nel bucket Cloud Storage predefinito: Visualizzatore (roles/viewer): il progetto in cui è configurata la build
• Visualizza i log di build in Logging: Visualizzatore log (roles/logging.viewer): i principali che vogliono visualizzare i log di build

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Visualizza i log di build in Google Cloud:

gcloud builds log build-id

Visualizza i log di build in GitHub e GitHub Enterprise:

Se crei un trigger GitHub o GitHub Enterprise con gcloud CLI o l'API Cloud Build e hai specificato --include-logs-with-status come opzione, allora puoi visualizzare i log di build in GitHub e GitHub Enterprise.

Per visualizzare i log di build in GitHub e GitHub Enterprise:

1. Vai al repository associato al trigger.

2. Vai all'elenco dei commit.

3. Individua la riga del commit per cui vuoi visualizzare i log di build.

4. Fai clic sull'icona del risultato nella riga del commit.

   Vedrai un elenco di controlli associati al commit.

5. Fai clic su Dettagli per la riga di cui vuoi visualizzare i log di build.

   Viene visualizzata la pagina Riepilogo associata al commit. Se hai creato un trigger utilizzando il flag --include-logs-with-status, vedrai i log di build visualizzati nella sezione Dettagli della pagina.

Elimina log e bucket di build

Per ottenere le autorizzazioni necessarie per eliminare i log di build e i bucket in Cloud Storage, chiedi all'amministratore di concederti i seguenti ruoli IAM per il account di servizio utilizzato per la build:

• Elimina i log di build in un bucket Cloud Storage creato o di proprietà dell'utente: Amministratore storage (roles/storage.admin): l'utente o il account di servizio che elimina i log di build
• Elimina un bucket Cloud Storage creato o di proprietà dell'utente: Amministratore Storage (roles/storage.admin): l'utente o il account di servizio che elimina i bucket
• Elimina un bucket Logging creato dall'utente: Autore configurazione log (roles/logging.configWriter) - il tuo progetto

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Per eliminare i log di build in un bucket Cloud Storage creato o di proprietà dell'utente, segui le istruzioni riportate in Eliminazione di oggetti nella documentazione di Cloud Storage.

Per eliminare un bucket Cloud Storage creato o di proprietà dell'utente, segui le istruzioni riportate in Eliminazione di bucket nella documentazione di Cloud Storage.

Per eliminare un bucket Logging creato dall'utente, segui le istruzioni riportate in Eliminare un bucket nella documentazione di Logging.

Passaggi successivi

• Scopri di più sugli audit log creati da Cloud Build.
• Scopri come visualizzare i risultati della build.
• Scopri di più sulle autorizzazioni IAM di Cloud Build.