Build-Logs speichern und verwalten

Wenn Sie Builds ausführen, erfasst und speichert Cloud Build Ihre Build-Logs. Auf dieser Seite wird erläutert, wie Sie Build-Logs speichern, aufrufen und löschen.

Speicherort für Build-Logs auswählen

Sie können Cloud Build so konfigurieren, dass Build-Logs in Cloud Logging oder in Cloud Storage gespeichert werden. Fügen Sie dazu das Feld logging in Ihre Cloud Build-Konfigurationsdatei ein. Wenn Sie in der Build-Konfigurationsdatei kein logging-Feld angeben, speichert Cloud Build sowohl Build-Logs als auch Cloud Storage.

Mit den folgenden Schritten werden Build-Logs nur in Logging gespeichert:

1. Legen Sie in der Build-Konfigurationsdatei den Wert von logging auf CLOUD_LOGGING_ONLY fest:

   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. Verwenden Sie die Build-Konfigurationsdatei, um einen Build über die Befehlszeile, die API oder über Trigger zu starten.

Build-Log-Felder Logeintragsfeldern zuordnen

Sie können das JSON Ihrer Build-Logs so konfigurieren, dass bestimmte Build-Log-Felder LogEntry-Feldern zugeordnet werden, wenn das Build-Log an Logging gesendet wird. Wenn Ihr Build-Log beispielsweise ein message enthält, wird die Meldung im resultierenden Logeintrag entweder in textPayload oder jsonPayload.message angezeigt. Felder im Build-Log, die nicht zugeordnet werden können, werden im Logeintrag jsonPayload angezeigt.

Wenn Sie die Feldzuordnung in Ihren Build-Logs aktivieren möchten, setzen Sie das Feld enableStructuredLogging in der BuildOptions auf TRUE.

In der folgenden Tabelle sind die Build-Log-Felder aufgeführt, die einem Logeintragsfeld zugeordnet sind:

BuildLog-Feld (JSON)	LogEntry-Feld	Beschreibung	Hinweise
message	textPayload oder jsonPayload.message	Nutzer können die Protokollmeldung festlegen	Muss ein String sein. Wenn das Build-Log nur mappable Felder enthält, wird die Meldung in textPayload angezeigt. Andernfalls wird die Meldung in jsonPayload.message angezeigt. Wenn das Build-Protokoll mehrere Schritte enthält, wird die Schritt-ID am Anfang der Nachricht angezeigt.
severity	severity	Damit können Nutzer den Logschweregrad festlegen.	Muss ein Enum von LogSeverity sein.

Die folgenden Build-Log-Felder können nicht zugeordnet werden und werden aus dem Logeintrag entfernt, wenn sie in einem Build-Log enthalten sind:

• 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

Alle anderen Build-Log-Felder werden als Teil von jsonPayload des Logeintrags angezeigt.

Build-Logs im von Google erstellten Standard-Bucket speichern

Cloud Build speichert Ihre Build-Logs standardmäßig in einem von Google erstellten Cloud Storage-Bucket. Sie können die in dem von Google erstellten Cloud Storage-Bucket gespeicherten Build-Logs anzeigen, aber keine weiteren Änderungen daran vornehmen. Wenn Sie die volle Kontrolle über Ihren Log-Bucket benötigen, speichern Sie die Logs in einem vom Nutzer erstellten Cloud Storage-Bucket.

Build-Logs in einem vom Nutzer erstellten Bucket speichern

IAM-Berechtigungen:

Wenn Sie Build-Logs in Ihrem eigenen Cloud Storage-Bucket speichern möchten, müssen Sie zuerst dem Dienstkonto, das Sie für den Build verwenden, die erforderlichen IAM-Berechtigungen erteilen:

• Wenn sich der Cloud Storage-Bucket und Cloud Build im selben Google Cloud-Projekt befinden und Sie das alte Cloud Build-Dienstkonto verwenden, hat Ihr altes Cloud Build-Dienstkonto standardmäßig die erforderlichen IAM-Berechtigungen. Sie müssen keine zusätzlichen Berechtigungen erteilen.

• In allen anderen Fällen weisen Sie dem Dienstkonto, das Sie für den Build verwenden, die Rolle Storage-Administrator zu:

  1. Öffnen Sie die IAM-Seite in dem Projekt, in dem sich Ihr Cloud Storage-Bucket befindet:

     IAM-Seite öffnen

  2. Klicken Sie auf Zugriff erlauben.

  3. Geben Sie die E-Mail-Adresse des Dienstkontos ein.

  4. Wählen Sie Cloud Storage und dann Storage-Administrator aus.

  5. Klicken Sie auf Speichern.

So geben Sie einen Cloud Storage-Bucket zum Speichern von Build-Logs an:

1. Erstellen Sie in Ihrem Google Cloud-Projekt einen Cloud Storage-Bucket, für den keine Aufbewahrungsrichtlinie festgelegt ist, um Ihre Build-Logs zu speichern.

2. Fügen Sie der Build-Konfigurationsdatei das Feld logsBucket hinzu, das auf den Cloud Storage-Bucket verweist, den Sie zum Speichern von Build-Logs erstellt haben. Die folgende Build-Konfigurationsdatei enthält eine Anleitung zum Erstellen eines Container-Images und zum Speichern der Build-Logs in einem Bucket namens 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. Verwenden Sie die Build-Konfigurationsdatei, um einen Build über die Befehlszeile, die API oder über Trigger zu starten.

Wenn der Build abgeschlossen ist, speichert Cloud Build die Logs in dem Cloud Storage-Bucket, den Sie in der Build-Konfigurationsdatei angegeben haben.

Build-Logs in einem vom Nutzer verwalteten und regionalisierten Bucket speichern

Standardmäßig speichert Cloud Build Build-Logs in einer von Google angegebenen Region, die sich vom Speicherort unterscheiden kann, an dem Sie einen Build ausführen. Mit der Option defaultLogsBucketBehavior können Sie Cloud Build so konfigurieren, dass ein Standard-Logs-Bucket in Ihrem eigenen Projekt und in derselben Region wie der Build verwendet wird. Mit dieser Konfiguration haben Sie mehr Kontrolle über den Speicherort Ihrer Protokolldaten. So können Sie die Anforderungen an den Datenstandort besser erfüllen.

Für das Speichern von Protokollen in Ihrem eigenen Projekt fallen Kosten an. Preisdetails finden Sie unter Cloud Storage – Preise.

Cloud Build für die Verwendung regionalisierter, nutzereigener Protokolle konfigurieren:

1. Erteilen Sie die erforderlichen IAM-Berechtigungen.

   • Wenn Sie das alte Cloud Build-Dienstkonto verwenden, hat es standardmäßig die erforderlichen IAM-Berechtigungen. Sie müssen keine zusätzlichen Berechtigungen erteilen.

   • Weisen Sie anderen Dienstkonten die Rolle Storage-Administrator zu. Eine Anleitung zum Zuweisen einer Rolle zu einem Dienstkonto finden Sie unter Rollen für das Projekt zuweisen.

2. Fügen Sie in Ihrer Build-Konfiguration die Option defaultLogsBucketBehavior hinzu und legen Sie den Wert auf REGIONAL_USER_OWNED_BUCKET fest:

   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. Verwenden Sie die Build-Konfigurationsdatei, um einen Build über die Befehlszeile, die API oder über Trigger zu starten.

   Wenn Sie Ihren Build ausführen, erstellt Cloud Build den neuen Log-Bucket in der Region, in der Sie den Build ausführen, und speichert die Build-Logs dann in diesem Bucket. Für nachfolgende Builds im selben Projekt und in derselben Region wird standardmäßig der vorhandene Bucket verwendet.

Wenn Sie die Option defaultLogsBucketBehavior festlegen und dann Builds in mehreren Regionen erstellen, erstellt Cloud Build mehrere Buckets für Ihre Build-Protokolle.

Für regionale Build-Logs, die in Ihrem eigenen Projekt gespeichert sind, gibt es keine Aufbewahrungsrichtlinie. Diese Einstellung kann nicht geändert werden.

Vorrang zwischen den Protokolleinstellungen

Wenn Sie die Option defaultLogsBucketBehavior einer vorhandenen Build-Konfigurationsdatei hinzufügen und zuvor logging- oder logsBucket-Optionen konfiguriert haben, empfehlen wir, diese Einstellungen zu löschen, um Konflikte zwischen den Einstellungen zu vermeiden.

Insbesondere funktioniert die defaultLogsBucketBehavior nicht, wenn Sie Folgendes konfiguriert haben:

• logging: CLOUD_LOGGING_ONLY, um Ihre Build-Logs in Cloud Logging zu speichern.
• logging: NONE, um das Logging zu deaktivieren.

Wenn Sie einen Build ausführen, in dessen Build-Konfiguration keine Logging-Optionen festgelegt sind, legt Cloud Build logging: LEGACY fest und speichert Logs im standardmäßigen von Google erstellten Cloud Storage-Bucket. Wenn Sie defaultLogsBucketBehavior: REGIONAL_USER_OWNED_BUCKET hinzufügen, wird logging: LEGACY durch diese Option überschrieben.

Build-Logs anzeigen

IAM-Berechtigungen:

• Wenn sich Ihre Build-Logs in Logging befinden, gewähren Sie den Hauptkonten, die die Build-Logs einsehen möchten, die Rolle Log-Betrachter für das Projekt, in dem der Build konfiguriert ist:

  1. Zur Seite "IAM":

     Seite "IAM" öffnen

  2. Wählen Sie Ihr Projekt aus und klicken Sie auf Öffnen.

  3. Suchen Sie in der Berechtigungstabelle nach der E-Mail-ID des Hauptkontos und klicken Sie auf das Stiftsymbol.

  4. Wählen Sie die Rolle Logging > Log-Betrachter aus.

  5. Klicken Sie auf Speichern.

• Wenn sich Ihre Build-Logs im von Google erstellten Cloud Storage-Standard-Bucket befinden, weisen Sie den Hauptkonten, die Build-Logs ansehen möchten, die Rolle Projektbetrachter für das Projekt zu, in dem der Build konfiguriert ist:

  1. Zur Seite "IAM":

     Seite "IAM" öffnen

  2. Wählen Sie Ihr Projekt aus und klicken Sie auf Öffnen.

  3. Suchen Sie in der Berechtigungstabelle nach der E-Mail-ID des Hauptkontos und klicken Sie auf das Stiftsymbol.

  4. Wählen Sie Projekt und dann Betrachter aus.

  5. Klicken Sie auf Speichern.

  Hinweis: Mit den Rollen „Projektinhaber“ und „Projektbearbeiter“ können Hauptkonten auch Build-Logs aus dem standardmäßigen Cloud Storage-Bucket aufrufen. Das liegt daran, dass die Rolle „Inhaber“ die Berechtigungen der Rolle „Bearbeiter“ und die Rolle „Bearbeiter“ die Berechtigungen der Rolle „Betrachter“ enthält. Wenn Sie Build-Logs im standardmäßigen Cloud Storage-Bucket aufrufen möchten, sollten Sie die Rolle „Projektbetrachter“ erteilen, weil somit nur der notwendige Zugriff erteilt wird.
  Hinweis: Speichern Sie Build-Logs in einem benutzerdefinierten Bucket, um die Rolle des einfachen Projektbetrachters zu vermeiden. Es wird insbesondere dann empfohlen, wenn Ihre Builds über Trigger aufgerufen werden und Sie nur Zugriff gewähren möchten, um Builds aufzurufen und den Fortschritt des Builds anzusehen.

  Wenn sich Ihre Build-Logs in einem vom Nutzer erstellten oder vom Nutzer verwalteten Cloud Storage-Bucket befinden, weisen Sie Hauptkonten, die Build-Logs ansehen möchten, die Rolle Storage-Objekt-Betrachter zu:

  1. Zur Seite "IAM":

     Seite "IAM" öffnen

  2. Wählen Sie Ihr Projekt aus und klicken Sie auf Öffnen.

  3. Suchen Sie in der Berechtigungstabelle nach der E-Mail-ID des Hauptkontos und klicken Sie auf das Stiftsymbol.

  4. Wählen Sie die Rolle Cloud Storage und dann Storage-Objekt-Betrachter aus.

  5. Klicken Sie auf Speichern.

So rufen Sie Build-Logs in Cloud Build auf:

Console

1. Öffnen Sie in der Google Cloud Console die Seite „Cloud Build“.

   Zur Seite "Cloud Build"

2. Wählen Sie Ihr Projekt aus und klicken Sie auf Öffnen.

3. Wählen Sie im Drop-down-Menü Region die Region für Ihren Build aus.

4. Klicken Sie auf der Seite Build-Verlauf auf einen bestimmten Build.

5. Klicken Sie auf der Seite Build-Details unter Schritte auf Build-Zusammenfassung, um Build-Logs für den gesamten Build aufzurufen, oder klicken Sie auf einen Build-Schritt, um Build-Logs für diesen Schritt aufzurufen.

   

6. Wenn Ihre Logs in Logging gespeichert sind, klicken Sie im Bereich Build-Log auf das Symbol , um die Logs im Log-Explorer aufzurufen.

   

gcloud

Führen Sie den Befehl gcloud builds log aus, wobei build-id die ID des Builds ist, für den Sie Build-Logs abrufen möchten. Die Build-ID wird am Ende des Übermittlungsprozesses für den Build angezeigt, wenn Sie gcloud builds submit ausführen, oder in der ID-Spalte, wenn Sie gcloud builds list ausführen.

gcloud builds log build-id

So rufen Sie Build-Logs in GitHub und GitHub Enterprise auf:

Wenn Sie einen GitHub- oder GitHub Enterprise-Trigger erstellen und --include-logs-with-status als Option angeben, können Sie Ihre Build-Protokolle in GitHub und GitHub Enterprise aufrufen.

So rufen Sie Build-Logs in GitHub und GitHub Enterprise auf:

1. Rufen Sie das Repository auf, das mit Ihrem Trigger verknüpft ist.

2. Rufen Sie die Liste der Commits auf.

3. Suchen Sie die Zeile des Commits, für den Sie Build-Logs aufrufen möchten.

4. Klicken Sie in der Zeile mit Ihrem Commit auf das Ergebnissymbol.

   Es wird eine Liste der mit Ihrem Commit verknüpften Prüfungen angezeigt.

5. Klicken Sie in der Zeile, für die Sie Build-Logs aufrufen möchten, auf Details.

   Die Seite Zusammenfassung wird angezeigt, die mit Ihrem Commit verknüpft ist. Wenn Sie einen Trigger mit dem Flag --include-logs-with-status erstellt haben, werden Ihre Build-Protokolle im Bereich Details angezeigt.

Hinweis: Dem Dienstkonto, das Sie für den Trigger verwendet haben, muss die Rolle roles/logging.viewer zugewiesen sein, damit die Build-Protokolle an GitHub gesendet werden können.

Build-Logs löschen

Sie können keine Build-Logs im von Google erstellten Log-Bucket löschen.

So löschen Sie Build-Logs in einem vom Nutzer erstellten Log-Bucket:

1. Gewähren Sie dem Nutzer oder dem Dienstkonto, das Logs löscht, die Rolle Storage Object Admin.

2. Löschen Sie die Build-Logs gemäß der Anleitung zum Löschen von Cloud Storage-Objekten unter Objekte löschen.

So löschen Sie den vom Nutzer erstellten Log-Bucket:

1. Weisen Sie dem Nutzer oder dem Dienstkonto, das den Log-Bucket löscht, die Rolle Storage-Administrator zu.

2. Löschen Sie den Log-Bucket unter Verwendung der Anleitung zum Löschen von Buckets.

Nächste Schritte

• Informationen zu Audit-Logs, die von Cloud Build erstellt wurden
• Build-Ergebnisse aufrufen
• Informationen zu Cloud Build-IAM-Berechtigungen.