Builds mit einem vom Nutzer verwalteten Dienstkonto ausführen

In diesem Dokument wird beschrieben, wie Sie Ihre Builds so konfigurieren, dass sie ein nutzerverwaltetes Dienstkonto verwenden.

Wenn Sie kein nutzerverwaltetes Dienstkonto für Ihre Builds angeben, verwendet Cloud Build automatisch das Cloud Build-Standarddienstkonto. Dieses Standarddienstkonto hat möglicherweise unnötig umfassende Berechtigungen, z. B. Zugriff auf Ihre Cloud Source Repositories und alle Cloud Storage-Bucket in Ihrem Projekt.

Wir empfehlen, das Prinzip der geringsten Berechtigung zu befolgen, indem Sie Dienstkonten Berechtigungen und Rollen zuweisen, die auf die von ihnen ausgeführte Aufgabe beschränkt sind. Sie können beispielsweise ein Dienstkonto verwenden, um Images zu erstellen und in Artifact Registry zu übertragen, wie im Google Cloud -Blog beschrieben.

Hinweis

  • Aktivieren Sie die Cloud Build API und die IAM API, falls sie noch nicht aktiviert sind.

    Rollen, die zum Aktivieren von APIs erforderlich sind

    Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Inhaberrolle (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen

    APIs aktivieren

  • Wenn Sie dieses Konto zum Erstellen und Verwalten von Anmeldedaten verwenden möchten, z. B. zum Erstellen kurzlebiger Anmeldedaten, aktivieren Sie die IAM Service Account Credentials API.

    Rollen, die zum Aktivieren von APIs erforderlich sind

    Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Inhaberrolle (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen

    API aktivieren

  • Erstellen Sie ein Dienstkonto, falls Sie noch keines haben.

Dienstkonto einrichten

Weisen Sie Ihrem nutzerverwalteten Dienstkonto IAM-Rollen zu, damit es die erforderlichen Berechtigungen zum Ausführen Ihrer Builds hat. Sie können Cloud Build auch so konfigurieren, dass dieses Dienstkonto automatisch für neue Trigger ausgewählt wird.

  1. Rufen Sie in der Google Cloud Console die Seite Berechtigungen für Cloud Build auf:

    Rufen Sie Berechtigungen auf.

  2. Rufen Sie das Menü Dienstkonto auf und wählen Sie Ihr Dienstkonto aus. Wenn Sie ein Dienstkonto in einem anderen Projekt auswählen möchten, klicken Sie auf Projekt wechseln.

  3. Wenn Sie das ausgewählte Dienstkonto als Dienstkonto für neue Trigger verwenden möchten, aktivieren Sie Als Vorauswahl für neue Trigger festlegen.

  4. Aktivieren Sie in der Liste der Google Cloud -Dienste die IAM-Rollen, die Sie Ihrem Dienstkonto zuweisen möchten.

  5. Wenn die Rolle, die Sie für Ihre Build-Pipeline benötigen, hier nicht aufgeführt ist, können Sie auf der Seite „IAM-Konfigurationen“ zusätzliche Rollen zuweisen.

  6. Wenn Sie ein Dienstkonto in einem anderen Projekt ausgewählt haben, führen Sie die Schritte unter Projektübergreifende Einrichtung aus.

Zu konfigurierendes Dienstkonto identifizieren

Prüfen Sie vor dem Zuweisen von Rollen, welches Dienstkonto für Ihre Builds konfiguriert ist:

  • Vorhandene Build-Trigger: Prüfen Sie das für einen Trigger konfigurierte Dienstkonto:

    gcloud builds triggers describe TRIGGER_NAME \
        --region=REGION \
        --format="value(serviceAccount)"
    

    Ersetzen Sie Folgendes:

    • TRIGGER_NAME: der Name Ihres Build-Triggers.
    • REGION: Die Region Ihres Build-Triggers.

    Interpretieren Sie die Ausgabe so:

    • Wenn die Befehlsausgabe einen Dienstkonto-Ressourcennamen im Format projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL ausgibt, weisen Sie diesem Konto die erforderlichen Rollen zu. Diese Ausgabe kann entweder ein nutzerverwaltetes Dienstkonto oder das Compute Engine-Standarddienstkonto identifizieren.
    • Wenn das Feld serviceAccount leer ist, verwendet der Trigger das Legacy-Dienstkonto von Cloud Build. Das Weglassen von serviceAccount beim Erstellen eines Triggers wird nur in Projekten unterstützt, die das Standarddienstkonto der Legacy-Version verwenden. In Projekten, die das Compute Engine-Standarddienstkonto verwenden oder das Standarddienstkonto durch eine Organisationsrichtlinie einschränken, schlägt die Triggererstellung mit dem Fehler INVALID_ARGUMENT fehl, der angibt, dass Sie ein Dienstkonto (BYOSA is required when creating triggers) angeben müssen. Wenn Organisationsrichtlinien das Standarddienstkonto zur Build-Zeit einschränken, schlägt der Build mit build.service_account must be specified due to the evaluation of the following org policies fehl.
  • Build-Konfigurationsdateien: Wenn Sie Builds manuell mit gcloud builds submit ausführen, prüfen Sie das Feld serviceAccount in Ihrer cloudbuild.yaml-Datei. Wenn kein Wert angegeben ist, verwendet Cloud Build das Standard-Build-Dienstkonto oder schlägt mit build.service_account must be specified due to the evaluation of the following org policies fehl, wenn Organisationsrichtlinien das Standarddienstkonto einschränken.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihrem nutzerverwalteten Dienstkonto die folgenden IAM-Rollen für das Projekt zuzuweisen, in dem Ihre Builds ausgeführt werden, damit Ihr nutzerverwaltetes Dienstkonto die erforderlichen Berechtigungen zum Ausführen von Builds mit einem nutzerverwalteten Dienstkonto hat:

  • Build-Logs in Cloud Logging schreiben und streamen: Logs Writer (roles/logging.logWriter)
  • Quellarchive oder Abhängigkeiten aus Cloud Storage-Buckets herunterladen: Storage-Objekt-Betrachter (roles/storage.objectViewer)

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Ihr Administrator kann Ihrem nutzerverwalteten Dienstkonto möglicherweise auch die erforderlichen Berechtigungen über benutzerdefinierte Rollen oder andere vordefinierte Rollen erteilen.

Identitätsübernahme des Dienstkontos

Damit Cloud Build und Ihre Trigger Builds mit einem nutzerverwalteten Dienstkonto ausführen können, müssen dem nutzerverwalteten Dienstkonto die folgenden Berechtigungen gewährt werden:

  • Weisen Sie dem Nutzer oder der Automatisierungsidentität, die den Build-Trigger erstellt, aktualisiert oder manuell ausführt (oder Builds mit gcloud builds submit einreicht), die Rolle „Dienstkontonutzer“ (roles/iam.serviceAccountUser) zu, die die Berechtigung iam.serviceAccounts.actAs enthält.
  • Für den Cloud Build-Dienst-Agent (service-PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com) ist die Berechtigung iam.serviceAccounts.getAccessToken erforderlich. Im selben Projekt ist diese Berechtigung standardmäßig in der Rolle „Cloud Build-Dienst-Agent“ (roles/cloudbuild.serviceAgent) enthalten. Wenn diese Rolle entfernt wurde oder sich das nutzerverwaltete Dienstkonto in einem anderen Projekt befindet, weisen Sie die Rolle „Ersteller von Dienstkonto-Tokens“ (roles/iam.serviceAccountTokenCreator) zu.

Weitere Informationen zu den IAM-Rollen, die häufig für einen Build erforderlich sind, finden Sie hier:

Build-Logs einrichten

Wenn Sie ein eigenes Dienstkonto für Builds angeben, müssen Sie Ihre Build-Logs in einem der folgenden Bucket-Typen speichern:

Wenn Sie einen Log-Bucket erstellen, achten Sie darauf, dass er keine Aufbewahrungsrichtlinie hat, da die Richtlinie möglicherweise verhindert, dass Cloud Build Build-Logs in den Bucket schreibt.

Sie können Ihre Logs nicht in einem Log-Bucket speichern, der zu Google Cloudgehört.

Weitere Informationen zum Speichern von Build-Logs finden Sie unter Speicheroptionen für Build-Logs.

Build mit einer Konfigurationsdatei ausführen

So führen Sie einen Build manuell mit einer Konfigurationsdatei aus:

  1. Erstellen Sie im Stammverzeichnis des Projekts eine Cloud Build-Konfigurationsdatei mit dem Namen cloudbuild.yaml oder cloudbuild.json.

  2. Fügen Sie das Feld serviceAccount und die bevorzugte Logging-Einrichtung hinzu.

    • Wenn Sie die Build-Logs in Cloud Logging speichern, fügen Sie das Feld logging hinzu und setzen Sie den Wert des Felds auf CLOUD_LOGGING_ONLY.

    • Wenn Sie die Build-Logs in einem vom Nutzer erstellten Cloud Storage-Bucket speichern:

      • Fügen Sie das Feld logging hinzu und legen Sie als Wert GCS_ONLY fest.
      • Fügen Sie das Feld logsBucket hinzu und legen Sie als Wert den Standort Ihres Cloud Storage-Buckets fest.

    Im folgenden Beispiel wird Cloud Build so konfiguriert, dass Builds mit einem nutzerverwalteten Dienstkonto ausgeführt werden. Außerdem werden Build-Logs so konfiguriert, dass sie in einem vom Nutzer erstellten Cloud Storage-Bucket gespeichert werden:

    YAML

    steps:
    - name: 'bash'
      args: ['echo', 'Hello world!']
    logsBucket: 'LOGS_BUCKET_LOCATION'
    serviceAccount: 'projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT'
    options:
      logging: GCS_ONLY
    

    JSON

    {
      "steps": [
      {
        "name": "bash",
        "args": [
          "echo",
          "Hello world!"
        ]
      }
      ],
      "logsBucket": "LOGS_BUCKET_LOCATION",
      "serviceAccount": "projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT",
      "options": {
        "logging": "GCS_ONLY"
      }
    }
    
    

    Ersetzen Sie die Variablen in Ihrer Build-Konfigurationsdatei durch Folgendes:

    • LOGS_BUCKET_LOCATION ist der Cloud Storage-Bucket, in dem Build-Logs gespeichert werden. Beispiel: gs://mylogsbucket.
    • PROJECT_ID ist die ID des Google Cloud -Projekts, in dem Sie den Build ausführen.
    • SERVICE_ACCOUNT ist die E-Mail-Adresse oder eindeutige ID des Dienstkontos, das Sie für Builds angeben möchten. Die E-Mail-Adresse eines Dienstkontos sieht beispielsweise so aus: service-account-name@project-id.iam.gserviceaccount.com.
  3. Starten Sie mit der Build-Konfigurationsdatei den Build:

    gcloud builds submit --config CONFIG_FILE_PATH SOURCE_DIRECTORY
    

    Ersetzen Sie die Variablen in den Befehlen durch die folgenden Werte:

    • CONFIG_FILE_PATH ist der Pfad zur Build-Konfigurationsdatei.
    • SOURCE_DIRECTORY ist der Pfad oder die URL zum Quellcode.

    Wenn Sie CONFIG_FILE_PATH und SOURCE_DIRECTORY im Befehl gcloud builds submit nicht angeben, geht Cloud Build davon aus, dass sich die Build-Konfigurationsdatei und der Quellcode im aktuellen Arbeitsverzeichnis befinden.

Builds mit Triggern ausführen

Wenn Sie einen Build mit Cloud Build-Triggern über Ihr eigenes Dienstkonto ausführen möchten, richten Sie die gewünschte Logging-Option ein und wählen Sie beim Erstellen des Triggers das gewünschte Dienstkonto aus.

Wenn Sie für alle neuen Trigger dasselbe Dienstkonto verwenden möchten, können Sie Cloud Build so konfigurieren, dass das Dienstkonto automatisch ausgewählt wird.

  1. In der Build-Konfigurationsdatei:

    • Wenn Sie die Build-Logs in Cloud Logging speichern, fügen Sie das Feld logging hinzu und setzen Sie den Wert des Felds auf CLOUD_LOGGING_ONLY.

    • Wenn Sie die Build-Logs in einem vom Nutzer erstellten Cloud Storage-Bucket speichern:

      • Fügen Sie das Feld logging hinzu und legen Sie als Wert GCS_ONLY fest.
      • Fügen Sie das Feld logsBucket hinzu und legen Sie als Wert den Standort Ihres Cloud Storage-Buckets fest.

    Im folgenden Beispiel werden Build-Logs so konfiguriert, dass sie in einem vom Nutzer erstellten Cloud Storage-Bucket gespeichert werden:

    YAML

    steps:
    - name: 'bash'
      args: ['echo', 'Hello world!']
    logsBucket: 'LOGS_BUCKET_LOCATION'
    options:
      logging: GCS_ONLY
    

    JSON

    {
      "steps": [
      {
        "name": "bash",
        "args": [
          "echo",
          "Hello world!"
        ]
      }
      ],
      "logsBucket": "LOGS_BUCKET_LOCATION",
      "options": {
        "logging": "GCS_ONLY"
      }
    }
    

    Ersetzen Sie LOGS_BUCKET_LOCATION durch den Cloud Storage-Bucket, in dem Build-Logs gespeichert werden sollen. Beispiel: gs://mylogsbucket

  2. Geben Sie ein Dienstkonto an, das mit Ihrem Build-Trigger verwendet werden soll:

    Console

    1. Build-Trigger erstellen oder bearbeiten

    2. Geben Sie im Feld Dienstkonto Ihr Dienstkonto an. Wenn Sie ein Dienstkonto in einem anderen Projekt auswählen möchten, klicken Sie auf Projekt wechseln.

      In Projekten, die das Legacy-Cloud Build-Dienstkonto verwenden, wird dieses Feld standardmäßig auf das Legacy-Dienstkonto gesetzt. In Projekten, die das Compute Engine-Standarddienstkonto verwenden oder das Standarddienstkonto durch eine Organisationsrichtlinie einschränken, müssen Sie ein Dienstkonto auswählen. Andernfalls schlägt die Triggererstellung mit dem Fehler INVALID_ARGUMENT fehl, der angibt, dass Sie ein Dienstkonto angeben müssen.

    3. Klicken Sie auf Erstellen, um den Build-Trigger zu speichern.

    gcloud

    Geben Sie beim Erstellen eines Build-Triggers Ihr Dienstkonto mit dem Flag --service-account an. In Projekten, die das Legacy-Standarddienstkonto nicht verwenden, ist das Flag --service-account erforderlich. Andernfalls schlägt die Triggererstellung mit dem Fehler INVALID_ARGUMENT fehl, der angibt, dass Sie ein Dienstkonto angeben müssen. Im folgenden Beispiel wird mit dem Befehl gcloud ein Build-Trigger erstellt, der Code aus einem Git-Repository abruft:

    gcloud builds triggers create github \
       --name=TRIGGER_NAME \
       --repo-name=REPO_NAME \
       --repo-owner=REPO_OWNER \
       --branch-pattern=BRANCH_PATTERN
       --build-config=BUILD_CONFIG_FILE
       --service-account=SERVICE_ACCOUNT
       --project=BUILD_PROJECT
    

    Ersetzen Sie die Variablen in der Build-Konfigurationsdatei durch die folgenden Werte:

    • TRIGGER_NAME ist der Name Ihres Build-Triggers.
    • REPO_NAME ist der Name Ihres Repositorys.
    • REPO_OWNER ist der Nutzername des Repository-Inhabers.
    • BRANCH_PATTERN ist der Zweigname in Ihrem Repository, für den der Build aufgerufen werden soll.
    • TAG_PATTERN ist der Tag-Name in Ihrem Repository, in dem der Build ausgelöst werden soll.
    • BUILD_CONFIG_FILE ist der Pfad zu Ihrer Build-Konfigurationsdatei.
    • SERVICE_ACCOUNT ist Ihr Dienstkonto im Format /projects/PROJECT_ID/serviceAccounts/ACCOUNT_ID_OR_EMAIL.
    • BUILD_PROJECT ist das Projekt, in dem Sie Builds starten.

Projektübergreifende Einrichtung

Sie können ein nutzerverwaltetes Dienstkonto verwenden, um Builds in einem anderen Projekt als dem Projekt auszuführen, in dem Sie das Dienstkonto erstellt haben, sofern die Einschränkung der Organisationsrichtlinie iam.disableCrossProjectServiceAccountUsage nicht erzwungen wird. Diese Einschränkung wird standardmäßig erzwungen. Weitere Informationen

  • Mit dem folgenden Befehl wird die Erzwingung dieser Einschränkung deaktiviert und der erforderliche Zugriff gewährt. Ihre Organisation muss sich der Sicherheitskompromisse bewusst sein, bevor Sie die Einschränkung in Ihrer Organisationsrichtlinie festlegen:

    gcloud resource-manager org-policies disable-enforce \
       iam.disableCrossProjectServiceAccountUsage \
       --project=SERVICE_ACCOUNT_PROJECT_ID
    

    In diesem Befehl ist SERVICE_ACCOUNT_PROJECT_ID das Projekt, das Ihr nutzerverwaltetes Dienstkonto enthält.

  • Weisen Sie im Projekt mit Ihrem nutzerverwalteten Dienstkonto dem Cloud Build-Dienst-Agent des Projekts, in dem Sie Builds ausführen, die Rolle roles/iam.serviceAccountTokenCreator zu:

    gcloud projects add-iam-policy-binding SERVICE_ACCOUNT_PROJECT_ID \
        --member="serviceAccount:BUILD_SERVICE_AGENT" \
        --role="roles/iam.serviceAccountTokenCreator"
    

    Ersetzen Sie die Variablen im Befehl durch Folgendes:

    • SERVICE_ACCOUNT_PROJECT_ID: Die Projekt-ID des Projekts, das Ihr nutzerverwaltetes Dienstkonto enthält.
    • BUILD_SERVICE_AGENT: Die E-Mail-ID des Dienst-Agents im Format service-BUILD_PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com, wobei BUILD_PROJECT_NUMBER die Projektnummer des Projekts ist, in dem Sie Builds ausführen. Die Projektnummer finden Sie auf der Seite mit den Projekteinstellungen.

Beschränkungen:

  • Ihr Google Cloud -Projekt muss sich in einer Google Cloud -Organisation befinden.

  • Sie müssen Builds in der Befehlszeile mit gcloud builds submit oder gcloud builds triggers create starten.

  • Wenn Sie beim Zuweisen der IAM-Rolle den Fehler service account not found erhalten, müssen Sie den Dienst-Agent möglicherweise manuell erstellen.

Nächste Schritte