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 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 RollenErstellen 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.
-
Rufen Sie in der Google Cloud Console die Seite Berechtigungen fürsettings Cloud Build auf:
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.
Wenn Sie das ausgewählte Dienstkonto als Dienstkonto für neue Trigger verwenden möchten, aktivieren Sie Als Vorauswahl für neue Trigger festlegen.
Aktivieren Sie in der Liste der Google Cloud -Dienste die IAM-Rollen, die Sie Ihrem Dienstkonto zuweisen möchten.
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.
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_EMAILausgibt, weisen Sie diesem Konto die erforderlichen Rollen zu. Diese Ausgabe kann entweder ein nutzerverwaltetes Dienstkonto oder das Compute Engine-Standarddienstkonto identifizieren. - Wenn das Feld
serviceAccountleer ist, verwendet der Trigger das Legacy-Dienstkonto von Cloud Build. Das Weglassen vonserviceAccountbeim 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 FehlerINVALID_ARGUMENTfehl, 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 mitbuild.service_account must be specified due to the evaluation of the following org policiesfehl.
Build-Konfigurationsdateien: Wenn Sie Builds manuell mit
gcloud builds submitausführen, prüfen Sie das FeldserviceAccountin Ihrercloudbuild.yaml-Datei. Wenn kein Wert angegeben ist, verwendet Cloud Build das Standard-Build-Dienstkonto oder schlägt mitbuild.service_account must be specified due to the evaluation of the following org policiesfehl, 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 submiteinreicht), die Rolle „Dienstkontonutzer“ (roles/iam.serviceAccountUser) zu, die die Berechtigungiam.serviceAccounts.actAsenthält. - Für den Cloud Build-Dienst-Agent (
service-PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com) ist die Berechtigungiam.serviceAccounts.getAccessTokenerforderlich. 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:
- Cloud Build-Standarddienstkonto.
- Zugriff auf Cloud Build-Ressourcen konfigurieren
- IAM-Rollen und -Berechtigungen für Cloud Build
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:
Cloud Storage-Buckets im Projekt des Nutzers. Dies können von Nutzern erstellte Buckets oder vonGoogle Clouderstellte Buckets im Besitz von Nutzern sein.
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:
Erstellen Sie im Stammverzeichnis des Projekts eine Cloud Build-Konfigurationsdatei mit dem Namen
cloudbuild.yamlodercloudbuild.json.Fügen Sie das Feld
serviceAccountund die bevorzugte Logging-Einrichtung hinzu.Wenn Sie die Build-Logs in Cloud Logging speichern, fügen Sie das Feld
logginghinzu und setzen Sie den Wert des Felds aufCLOUD_LOGGING_ONLY.Wenn Sie die Build-Logs in einem vom Nutzer erstellten Cloud Storage-Bucket speichern:
- Fügen Sie das Feld
logginghinzu und legen Sie als WertGCS_ONLYfest. - Fügen Sie das Feld
logsBuckethinzu und legen Sie als Wert den Standort Ihres Cloud Storage-Buckets fest.
- Fügen Sie das Feld
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_ONLYJSON
{ "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_LOCATIONist der Cloud Storage-Bucket, in dem Build-Logs gespeichert werden. Beispiel:gs://mylogsbucket.PROJECT_IDist die ID des Google Cloud -Projekts, in dem Sie den Build ausführen.SERVICE_ACCOUNTist 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.
Starten Sie mit der Build-Konfigurationsdatei den Build:
gcloud builds submit --config CONFIG_FILE_PATH SOURCE_DIRECTORYErsetzen Sie die Variablen in den Befehlen durch die folgenden Werte:
CONFIG_FILE_PATHist der Pfad zur Build-Konfigurationsdatei.SOURCE_DIRECTORYist der Pfad oder die URL zum Quellcode.
Wenn Sie CONFIG_FILE_PATH und SOURCE_DIRECTORY im Befehl
gcloud builds submitnicht 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.
In der Build-Konfigurationsdatei:
Wenn Sie die Build-Logs in Cloud Logging speichern, fügen Sie das Feld
logginghinzu und setzen Sie den Wert des Felds aufCLOUD_LOGGING_ONLY.Wenn Sie die Build-Logs in einem vom Nutzer erstellten Cloud Storage-Bucket speichern:
- Fügen Sie das Feld
logginghinzu und legen Sie als WertGCS_ONLYfest. - Fügen Sie das Feld
logsBuckethinzu und legen Sie als Wert den Standort Ihres Cloud Storage-Buckets fest.
- Fügen Sie das Feld
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_ONLYJSON
{ "steps": [ { "name": "bash", "args": [ "echo", "Hello world!" ] } ], "logsBucket": "LOGS_BUCKET_LOCATION", "options": { "logging": "GCS_ONLY" } }Ersetzen Sie
LOGS_BUCKET_LOCATIONdurch den Cloud Storage-Bucket, in dem Build-Logs gespeichert werden sollen. Beispiel:gs://mylogsbucketGeben Sie ein Dienstkonto an, das mit Ihrem Build-Trigger verwendet werden soll:
Console
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_ARGUMENTfehl, der angibt, dass Sie ein Dienstkonto angeben müssen.Klicken Sie auf Erstellen, um den Build-Trigger zu speichern.
gcloud
Geben Sie beim Erstellen eines Build-Triggers Ihr Dienstkonto mit dem Flag
--service-accountan. In Projekten, die das Legacy-Standarddienstkonto nicht verwenden, ist das Flag--service-accounterforderlich. Andernfalls schlägt die Triggererstellung mit dem FehlerINVALID_ARGUMENTfehl, der angibt, dass Sie ein Dienstkonto angeben müssen. Im folgenden Beispiel wird mit dem Befehlgcloudein 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_PROJECTErsetzen Sie die Variablen in der Build-Konfigurationsdatei durch die folgenden Werte:
TRIGGER_NAMEist der Name Ihres Build-Triggers.REPO_NAMEist der Name Ihres Repositorys.REPO_OWNERist der Nutzername des Repository-Inhabers.BRANCH_PATTERNist der Zweigname in Ihrem Repository, für den der Build aufgerufen werden soll.TAG_PATTERNist der Tag-Name in Ihrem Repository, in dem der Build ausgelöst werden soll.BUILD_CONFIG_FILEist der Pfad zu Ihrer Build-Konfigurationsdatei.SERVICE_ACCOUNTist Ihr Dienstkonto im Format/projects/PROJECT_ID/serviceAccounts/ACCOUNT_ID_OR_EMAIL.BUILD_PROJECTist 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_IDIn 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.serviceAccountTokenCreatorzu: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 Formatservice-BUILD_PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com, wobeiBUILD_PROJECT_NUMBERdie 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 submitodergcloud builds triggers createstarten.Wenn Sie beim Zuweisen der IAM-Rolle den Fehler
service account not founderhalten, müssen Sie den Dienst-Agent möglicherweise manuell erstellen.
Nächste Schritte
- Weitere Informationen zu IAM-Rollen und -Berechtigungen für Cloud Build
- Informationen zu den Auswirkungen der Dienstkontoänderungen auf die Ausführung Ihrer Builds