Builds mit einem vom Nutzer verwalteten Dienstkonto ausführen

In diesem Dokument wird beschrieben, wie Sie Ihre Builds für die Verwendung eines nutzerverwalteten Dienstkontos konfigurieren.

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 jeweilige Aufgabe beschränkt sind. Sie können beispielsweise ein Dienstkonto zum Erstellen und Übertragen von Images in Artifact Registry verwenden, 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 Rolle „Inhaber“ (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 Rolle „Inhaber“ (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 noch nicht geschehen.

Dienstkonto einrichten

Weisen Sie Ihrem nutzerverwalteten Dienstkonto IAM-Rollen zu, damit es die Berechtigungen hat, die zum Ausführen Ihrer Builds erforderlich sind. 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 Cloud Build Berechtigungen auf:

    Zu den Berechtigungen

  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.

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

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 dies dazu führen kann, dass Cloud Build keine Build-Logs in den Bucket schreibt.

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

Weitere Informationen dazu, wo Build-Logs gespeichert werden können, 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 legen Sie den Wert des Felds auf CLOUD_LOGGING_ONLY fest.

    • 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 wird konfiguriert, dass Build-Logs 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 mit Ihrem eigenen Dienstkonto ausführen möchten, richten Sie die gewünschte Protokollierungsoption ein und wählen Sie beim Erstellen des Triggers das gewünschte Dienstkonto aus.

Wenn Sie dasselbe Dienstkonto für alle neuen Trigger 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 legen Sie den Wert des Felds auf CLOUD_LOGGING_ONLY fest.

    • 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.

      Wenn Sie kein Dienstkonto angeben, verwendet Cloud Build das Standarddienstkonto.

    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. Im folgenden Beispiel erstellt der Befehl gcloud einen Build-Trigger, 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, mit dem der Build aufgerufen wird.
    • 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 Projekt auszuführen, das sich von dem Projekt unterscheidet, in dem Sie das Dienstkonto erstellt haben, nur wenn 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 Sicherheitsrisiken bewusst sein, bevor sie die Einschränkung in der Organisationsrichtlinie festlegt:

    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. Sie finden die Projektnummer 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.

Nächste Schritte