Rollen für Dienst-Agents erstellen und zuweisen

In Google Cloudwerden Dienst-Agents auf Projektebene, Ordnerebene und Organisationsebene automatisch erstellt, wenn SieGoogle Cloud -Dienste aktivieren und verwenden. Manchmal werden diesen Dienst-Agents auch automatisch Rollen zugewiesen, mit denen sie in Ihrem Namen Ressourcen erstellen und darauf zugreifen können.

Bei Bedarf können Sie auch Google Cloud bitten, Dienst-Agents auf Projektebene, Ordner- und Organisationsebene für einen Dienst zu erstellen, bevor Sie den Dienst verwenden. Wenn Sie Google Cloud bitten, Dienst-Agents zu erstellen, können Sie Dienst-Agents Rollen zuweisen, bevor Sie einen Dienst verwenden. Wenn noch kein Dienst-Agent erstellt wurde, können Sie dem Dienst-Agent keine Rollen zuweisen.

Diese Option ist nützlich, wenn Sie eine der folgenden Strategien zum Verwalten Ihrer Zulassungsrichtlinien verwenden:

  • Ein deklaratives Framework wie Terraform. Wenn Ihre Terraform-Konfiguration nicht die Rollen der Dienst-Agents enthält, werden diese Rollen beim Anwenden der Konfiguration widerrufen. Wenn Sie Dienst-Agents erstellen und ihnen in Ihrer Terraform-Konfiguration Rollen zuweisen, sorgen Sie dafür, dass diese Rollen nicht widerrufen werden.
  • Ein Richtliniensystem als Code, das Kopien Ihrer aktuellen Zulassungsrichtlinien in einem Code-Repository speichert. Wenn Sie Google Cloud Dienst-Agents automatisch Rollen zuweisen lassen, werden diese Rollen in der tatsächlichen Zulassungsrichtlinie angezeigt, jedoch nicht in der gespeicherten Kopie der Zulassungsrichtlinie. Um diese Inkonsistenz zu beheben, können Sie diese Rollen falsch widerrufen. Wenn Sie Dienst-Agents erstellen und ihnen Rollen proaktiv zuweisen, können Sie Abweichungen zwischen Ihrem Code-Repository und Ihren tatsächlichen Zulassungsrichtlinien verhindern.

Nachdem Sie die Erstellung des Dienst-Agents ausgelöst haben, müssen Sie den Dienst-Agents die Rollen zuweisen, die ihnen normalerweise automatisch zugewiesen werden. Wenn Sie das nicht tun, funktionieren einige Dienste möglicherweise nicht richtig. Dies liegt daran, dass Dienst-Agents, die auf Anfrage eines Nutzers erstellt werden, nicht automatisch Rollen zugewiesen werden.

Hinweis

  • Aktivieren Sie die Resource Manager API und die Workload Identity API.

    Rollen, die zum Aktivieren von APIs erforderlich sind

    Zum Aktivieren von APIs benötigen Sie die IAM-Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin), die die Berechtigung serviceusage.services.enable enthält. Weitere Informationen zum Zuweisen von Rollen

    APIs aktivieren

  • Informationen zu Dienst-Agents

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für die Projekte, Ordner und Organisationen zuzuweisen, für die Sie Dienst-Agents erstellen und Zugriff gewähren, um die Berechtigungen zu erhalten, die Sie zum Erstellen von Dienst-Agents und zum Gewähren des Zugriffs auf diese benötigen:

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

Diese vordefinierten Rollen enthalten die Berechtigungen, die zum Erstellen von Dienst-Agents und zum Gewähren des Zugriffs auf Dienst-Agents erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen, um die notwendigen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind erforderlich, um Dienst-Agents zu erstellen und Zugriff auf sie zu gewähren:

  • Verfügbare Dienste und ihre Endpunkte auflisten: serviceusage.services.list
  • Kundenservicemitarbeiter aktivieren: workloadidentity.serviceAgents.create
  • Vorgänge mit langer Ausführungszeit ansehen: workloadidentity.operations.get
  • Gewähren Sie Dienst-Agents Zugriff auf ein Projekt:
    • resourcemanager.projects.getIamPolicy
    • resourcemanager.projects.setIamPolicy
  • Gewähren Sie Dienst-Agents Zugriff auf einen Ordner:
    • resourcemanager.folders.getIamPolicy
    • resourcemanager.folders.setIamPolicy
  • Gewähren Sie Dienst-Agents Zugriff auf eine Organisation:
    • resourcemanager.organizations.getIamPolicy
    • resourcemanager.organizations.setIamPolicy

Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

Zu erstellende Dienst-Agents identifizieren

So ermitteln Sie die Dienst-Agents, die Sie erstellen müssen, und die Ressourcen, für die Sie sie erstellen müssen:

  1. Erstellen Sie eine Liste der von Ihnen verwendeten Dienste und ihrer API-Endpunkte. Verwenden Sie eine der folgenden Methoden, um alle verfügbaren Dienste und ihre Endpunkte aufzurufen:

    Console

    Rufen Sie in der Google Cloud Console die Seite API-Bibliothek auf.

    Zur API-Bibliothek

    Der API-Endpunkt ist der Dienstname, der im Abschnitt Zusätzliche Details aufgeführt ist.

    gcloud

    Mit dem Befehl gcloud services list werden alle verfügbaren Dienste für ein Projekt aufgelistet.

    Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

    • EXPRESSION: Optional. Ein Ausdruck zum Filtern der Ergebnisse. Der folgende Ausdruck filtert beispielsweise nach allen Diensten, deren Namen googleapis.com, aber nicht sandbox enthalten: 

      name ~ googleapis.com AND name !~ sandbox

      Eine Liste der Filterausdrücke finden Sie unter gcloud topic filters.

    • LIMIT: Optional. Die maximale Anzahl von aufzulistenden Ergebnissen. Der Standardwert ist unlimited.

    Führen Sie folgenden Befehl aus:

    Linux, macOS oder Cloud Shell

    gcloud services list --available --filter='EXPRESSION' --limit=LIMIT

    Windows (PowerShell)

    gcloud services list --available --filter='EXPRESSION' --limit=LIMIT

    Windows (cmd.exe)

    gcloud services list --available --filter='EXPRESSION' --limit=LIMIT

    Die Antwort enthält die Namen und Titel aller verfügbaren Dienste. Der API-Endpunkt ist der Wert im Feld NAME.

    REST

    Die Methode services.list der Service Usage API listet alle verfügbaren Dienste für ein Projekt auf.

    Ersetzen Sie diese Werte in den folgenden Anfragedaten:

    • RESOURCE_TYPE: Der Ressourcentyp, für den Sie die verfügbaren Dienste auflisten möchten. Verwenden Sie projects, folders, oder organizations.
    • RESOURCE_ID: Die ID des Google Cloud-Projekts, -Ordners oder der -Organisation, für die Sie die verfügbaren Dienste auflisten möchten. Projekt-IDs sind alphanumerische Strings, wie my-project. Ordner- und Organisations-IDs sind numerisch, z. B. 123456789012.
    • PAGE_SIZE: Optional. Die Anzahl der Dienste, die in der Antwort enthalten sein sollen. Der Standardwert ist 50 und der Höchstwert 200. Wenn die Anzahl der Dienste die Seitengröße überschreitet, enthält die Antwort ein Seitenumbruchtoken, mit dem Sie die nächste Ergebnisseite abrufen können.
    • NEXT_PAGE_TOKEN: Optional. Das Seitenumbruchtoken, das in einer früheren Antwort von dieser Methode zurückgegeben wurde. Wenn dieser Wert angegeben wird, beginnt die Liste der Dienste dort, wo die vorherige Anfrage endet.

    HTTP-Methode und URL:

    GET https://serviceusage.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/services?pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN

    Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

    Die Antwort enthält die Namen und Titel aller verfügbaren Dienste für die Ressource. Wenn die Anzahl der verfügbaren Dienste die Seitengröße überschreitet, enthält die Antwort auch ein Paginierungstoken.

    Der API-Endpunkt ist der Wert im Feld name.

  2. Erstellen Sie für jeden API-Endpunkt, den Sie verwenden möchten, eine Liste der Ressourcen, für die Sie die Dienst-Agents des Endpunkts erstellen müssen:

    1. Suchen Sie auf der Seite Referenz zum Dienst-Agent nach jedem API-Endpunkt, um alle Dienst-Agents für diesen Endpunkt zu finden.

      Einige Endpunkte haben möglicherweise keine zugehörigen Dienst-Agents. In diesem Fall können Sie die Erstellung von Dienst-Agents für diese Endpunkte überspringen.

    2. Verwenden Sie für jeden Dienst-Agent des Endpunkts die E-Mail-Adresse des Dienst-Agents, um zu ermitteln, wo Sie den Dienst-Agent erstellen müssen.

      Der Platzhalter in der E-Mail-Adresse eines Dienst-Agents gibt an, wo Sie den Dienst-Agent erstellen müssen:

      Platzhalter Dienst-Agent erstellen
      PROJECT_NUMBER Jedes Projekt, in dem Sie den Dienst verwenden
      FOLDER_NUMBER Jeder Ordner, in dem Sie den Dienst verwenden
      ORGANIZATION_NUMBER Jede Organisation, in der Sie den Dienst verwenden

    3. Erfassen Sie für jeden Endpunkt jede eindeutige Ressource, für die Sie Dienst-Agents für diesen Endpunkt erstellen müssen.

Erstellen eines Trigger-Dienst-Agents

Nachdem Sie wissen, welche Dienst-Agents Sie erstellen müssen, können SieGoogle Cloud bitten, sie zu erstellen.

Wenn Sie Google Cloud bitten, Dienst-Agents zu erstellen,stellen Sie ihm einen Dienst und eine Ressource zur Verfügung. Anschließend erstellt Google Cloud alle Dienst-Agents für diesen Dienst und diese Ressource.

Wenn Sie in diesem Schritt die gcloud CLI oder die REST API verwenden, können Sie auch eine Liste der Rollen erstellen, die jedem Dienst-Agent gewährt werden müssen. Mit diesen Informationen weisen Sie den Dienst-Agents Rollen zu. Wenn Sie Terraform verwenden, müssen Sie die erforderlichen Rollen nicht manuell im Blick behalten, da Sie programmatisch darauf verweisen können.

gcloud

Verwenden Sie den Befehl gcloud workload-identity service-agents generate, um Dienst-Agents für jeden Endpunkt und jede Ressource zu erstellen, die Sie unter Zu erstellende Dienst-Agents identifizieren ermittelt haben.

Sehen Sie sich die Antwort jedes Mal an, wenn Sie den Befehl ausführen. Notieren Sie für jede Rolle in der Antwort die E-Mail-Adresse des Dienst-Agents, dem die Rolle zugewiesen werden soll. Sie benötigen diese Informationen, um den Dienst-Agents Rollen zuzuweisen.

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

  • ENDPOINT: Der Endpunkt der API, für die Sie Dienst-Agents erstellen möchten, z. B. aiplatform.googleapis.com.
  • RESOURCE_TYPE: Der Ressourcentyp, für den Sie Dienst-Agents erstellen möchten. Verwenden Sie project, folder oder organization.

  • RESOURCE_ID: Die numerische ID des Google Cloud-Projekts, -Ordners oder der -Organisation, für die Sie Dienst-Agents erstellen möchten. Beispiel: 123456789012

    Sie können für jeweils eine Ressource Dienst-Agents erstellen. Wenn Sie Dienst-Agents für mehrere Ressourcen erstellen müssen, führen Sie den Befehl für jede Ressource einmal aus.

Führen Sie folgenden Befehl aus:

Linux, macOS oder Cloud Shell

gcloud workload-identity service-agents generate --service="ENDPOINT" \
    --location="global" --RESOURCE_TYPE="RESOURCE_ID"

Windows (PowerShell)

gcloud workload-identity service-agents generate --service="ENDPOINT" `
    --location="global" --RESOURCE_TYPE="RESOURCE_ID"

Windows (cmd.exe)

gcloud workload-identity service-agents generate --service="ENDPOINT" ^
    --location="global" --RESOURCE_TYPE="RESOURCE_ID"

Die Antwort enthält eine Liste aller erstellten Service-Agents. Für jeden Dienst-Agent werden in der Antwort die Ressource, für die er erstellt wurde, die E-Mail-Adresse des Dienst-Agents, der Dienst, mit dem der Dienst-Agent verknüpft ist, und der Status des Dienst-Agents aufgeführt. Wenn dem Dienst-Agent in der Regel eine bestimmte Rolle zugewiesen wird, wird diese Rolle auch in der Antwort aufgeführt.

Die aufgeführte Rolle wird dem Dienst-Agenten nicht automatisch zugewiesen. Notieren Sie für jede Rolle in der Antwort die E-Mail-Adresse des Dienst-Agents, dem die Rolle zugewiesen werden soll. Sie benötigen diese Informationen, um den Dienst-Agents Rollen zuzuweisen.

Das Folgende ist ein gekürztes Beispiel für die Antwort beim Erstellen von Dienst-Agents für aiplatform.googleapis.com. 

Provisioned service agents for aiplatform.googleapis.com under projects/123456789012:

container: projects/123456789012
principal: serviceAccount:service-123456789012@gcp-sa-aiplatform.iam.gserviceaccount.com
role: roles/aiplatform.serviceAgent
serviceProducer: aiplatform.googleapis.com
state: ACTIVE
----
container: projects/123456789012
principal: serviceAccount:service-123456789012@gcp-ri-aiplatform.iam.gserviceaccount.com
serviceProducer: aiplatform.googleapis.com
state: ACTIVE
----
...
----
container: projects/123456789012
principal: serviceAccount:service-123456789012@gcp-sa-vertex-vtc.iam.gserviceaccount.com
role: roles/aiplatform.trainingClusterServiceAgent
serviceProducer: aiplatform.googleapis.com
state: ACTIVE
----

Terraform

Informationen zum Anwenden oder Entfernen einer Terraform-Konfiguration finden Sie unter Grundlegende Terraform-Befehle. Weitere Informationen finden Sie in der Referenzdokumentation des Anbieters zu Terraform.

Verwenden Sie die google_workload_identity_service_agent-Ressource, um die Erstellung von Dienst-Agents für jeden Endpunkt und jede Ressource auszulösen, die Sie unter Zu erstellende Dienst-Agents identifizieren identifiziert haben.

Wenn Sie beispielsweise alle Dienst-Agents auf Projektebene für BigQuery für das Standardprojekt erstellen möchten, können Sie Ihrer Terraform-Konfiguration den folgenden Code hinzufügen:

data "google_project" "default" {
}

# Create all project-level bigquery.googleapis.com service agents
resource "google_workload_identity_service_agent" "primary" {
  parent = "projects/${data.google_project.default.number}/locations/global/serviceProducers/bigquery.googleapis.com"
}

REST

Gehen Sie für jeden Endpunkt, für den Sie Dienst-Agents erstellen müssen, so vor:

  1. Erstellen Sie Dienst-Agents für jede Ressource, die Sie unter Zu erstellende Dienst-Agents identifizieren identifiziert haben:

    Ersetzen Sie diese Werte in den folgenden Anfragedaten:

    • RESOURCE_TYPE: Der Ressourcentyp, für den Sie Dienst-Agents erstellen möchten. Verwenden Sie projects, folders, oder organizations.

    • RESOURCE_NUMERIC_ID: Die numerische ID des Google Cloud Projekts, des Ordners oder der Organisation, für die Sie Dienst-Agents erstellen möchten. Beispiel: 123456789012

      Sie können für jeweils eine Ressource Dienst-Agents erstellen. Wenn Sie Dienst-Agents für mehrere Ressourcen erstellen müssen, senden Sie für jede Ressource eine Anfrage.

    • ENDPOINT: Der Endpunkt der API, für die Sie einen Dienst-Agent erstellen möchten, z. B. aiplatform.googleapis.com.

    HTTP-Methode und URL:

    POST https://workloadidentity.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_NUMERIC_ID/locations/global/serviceProducers/ENDPOINT:generateServiceAgents

    Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

    Die Antwort enthält ein Operation, das den Status Ihrer Anfrage angibt. Beispiel: 

    {
  "name": "projects/123456789012/locations/global/operations/operation-1775250941060-64e94d1baa76d-1aa958f3-07b2ea9c",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.workloadidentity.v1.OperationMetadata",
    "createTime": "2026-04-03T21:15:41.367155118Z",
    "target": "projects/123456789012/locations/global/serviceProducers/bigquery.googleapis.com",
    "verb": "passthroughLro",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

  2. Rufen Sie die Antwort des abgeschlossenen Vorgangs ab. Notieren Sie für jede Rolle in der Antwort die E-Mail-Adresse des Dienst-Agents, dem die Rolle zugewiesen werden soll. Sie benötigen diese Informationen, um den Dienst-Agents Rollen zuzuweisen.

    Ersetzen Sie diese Werte in den folgenden Anfragedaten:

    • OPERATION_NAME: Der Name eines generateServiceAgents-Vorgangs. Kopieren Sie diesen Wert aus dem Feld name einer serviceProducers.generateServiceAgents-Antwort. Beispiel: projects/123456789012/locations/global/operations/operation-1775250941060-64e94d1baa76d-1aa958f3-07b2ea9c.
    • PROJECT_ID: Ihre Google Cloud Projekt-ID. Projekt-IDs sind alphanumerische Strings, wie my-project.

    HTTP-Methode und URL:

    GET https://workloadidentity.googleapis.com/v1/OPERATION_NAME

    Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

    Laufende Vorgänge geben eine Antwort wie die folgende zurück:

    {
  "name": "projects/123456789012/locations/global/operations/operation-1775258415970-64e968f44b91a-28fcf2f5-38367cfe",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.workloadidentity.v1.OperationMetadata",
    "createTime": "2026-04-03T23:20:15.982631253Z",
    "target": "projects/123456789012/locations/global/serviceProducers/aiplatform.googleapis.com",
    "verb": "passthroughLro",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

    Abgeschlossene Vorgänge geben eine Antwort mit einer Liste der erstellten Kundenservicemitarbeiter zurück. Für jeden Dienst-Agenten werden in der Antwort die Ressource, für die er erstellt wurde, die E-Mail-Adresse des Dienst-Agents, der Dienst, mit dem der Dienst-Agent verknüpft ist, und der Status des Dienst-Agents aufgeführt. Wenn dem Dienst-Agent normalerweise eine bestimmte Rolle zugewiesen wird, wird diese Rolle auch in der Antwort aufgeführt.

    Die aufgeführte Rolle wird dem Dienst-Agenten nicht automatisch zugewiesen. Notieren Sie für jede Rolle in der Antwort die E-Mail-Adresse des Dienst-Agents, dem die Rolle zugewiesen werden soll. Sie benötigen diese Informationen, um den Dienst-Agents Rollen zuzuweisen.

    Das Folgende ist ein gekürztes Beispiel für die Antwort beim Erstellen von Dienst-Agents für aiplatform.googleapis.com. 

    {
  "name": "projects/123456789012/locations/global/operations/operation-1775258415970-64e968f44b91a-28fcf2f5-38367cfe",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.workloadidentity.v1.OperationMetadata",
    "createTime": "2026-04-03T23:20:15.982631253Z",
    "endTime": "2026-04-03T23:20:17.315225515Z",
    "target": "projects/123456789012/locations/global/serviceProducers/aiplatform.googleapis.com",
    "verb": "passthroughLro",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.workloadidentity.v1.GenerateServiceAgentsResponse",
    "serviceAgents": [
      {
        "container": "projects/123456789012",
        "serviceProducer": "aiplatform.googleapis.com",
        "principal": "serviceAccount:service-123456789012@gcp-sa-aiplatform.iam.gserviceaccount.com",
        "role": "roles/aiplatform.serviceAgent",
        "state": "ACTIVE"
      },
      {
        "container": "projects/123456789012",
        "serviceProducer": "aiplatform.googleapis.com",
        "principal": "serviceAccount:service-123456789012@gcp-ri-aiplatform.iam.gserviceaccount.com",
        "state": "ACTIVE"
      },
      ...
      {
        "container": "projects/123456789012",
        "serviceProducer": "aiplatform.googleapis.com",
        "principal": "serviceAccount:service-123456789012@gcp-sa-vertex-vtc.iam.gserviceaccount.com",
        "role": "roles/aiplatform.trainingClusterServiceAgent",
        "state": "ACTIVE"
      }
    ]
  }
}

Dienst-Agents Rollen zuweisen

Nachdem Google Cloud die erforderlichen Dienst-Agents für Ihre Projekte, Ordner und Organisationen erstellt hat, verwenden Sie die E-Mail-Adressen der Dienst-Agents, um ihnen Rollen zuzuweisen.

Wenn Sie Google Cloud aufgefordert haben, Dienst-Agents zu erstellen, müssen Sie diesen Dienst-Agents die Rollen zuweisen, die sie normalerweise automatisch erhalten. Wenn Sie das nicht tun, funktionieren einige Dienste möglicherweise nicht richtig. Dies liegt daran, dass Dienst-Agents, die auf Anfrage eines Nutzers erstellt werden, nicht automatisch Rollen zugewiesen werden.

Console

Verwenden Sie die Liste der Rollen und Dienst-Agents, die Sie unter Erstellen eines Trigger-Dienst-Agents erstellt haben, um zu ermitteln, welchen Dienst-Agents Rollen zugewiesen werden müssen. Gehen Sie für jeden Dienst-Agent, der eine Rolle benötigt, so vor:

  1. Rufen Sie in der Google Cloud Console die Seite IAM auf.

    IAM aufrufen

  2. Wählen Sie ein Projekt, einen Ordner oder eine Organisation aus, für die Sie den Dienst-Agent erstellt haben.

  3. Klicken Sie auf Zugriff erlauben und geben Sie dann die E-Mail-Adresse des Dienst-Agents ein.

  4. Klicken Sie auf Rolle auswählen und geben Sie dann den Namen einer Rolle oder Berechtigung ein, um nach einer Rolle zu filtern, die Sie zuweisen möchten. Wählen Sie eine Rolle aus, die nur die Berechtigungen enthält, die Ihr Hauptkonto benötigt, um dem Prinzip der geringsten Berechtigung zu folgen.

  5. Klicken Sie auf Speichern. Dem Dienst-Agent wird die Rolle für die Ressource zugewiesen.

gcloud

Anhand der Liste der Rollen und Dienst-Agents, die Sie unter Erstellen eines Trigger-Dienst-Agents erstellt haben, können Sie ermitteln, welchen Dienst-Agents Rollen zugewiesen werden müssen. Verwenden Sie für jeden Dienst-Agent, der eine Rolle benötigt, den Befehl add-iam-policy-binding, um dem Dienst-Agent die Rolle zuzuweisen.

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

  • RESOURCE_TYPE: Der Ressourcentyp, für den Sie den Zugriff verwalten möchten. Verwenden Sie projects, resource-manager folders oder organizations.

  • RESOURCE_ID: Ihr Google Cloud Projekt, Ihr Ordner oder Ihre Organisations-ID. Projekt-IDs sind alphanumerisch, z. B. my-project. Ordner- und Organisations-IDs sind numerisch, z. B. 123456789012.

  • PRINCIPAL: Die E-Mail-Adresse des Dienst-Agents, dem Sie Zugriff gewähren möchten, mit dem Präfix serviceAccount:. Beispiel: serviceAccount:service-0123456789012@gcp-sa-aiplatform-cc.iam.gserviceaccount.com

  • ROLE_NAME: Der Name der Rolle, die Sie dem Dienst-Agent zuweisen möchten.

Führen Sie folgenden Befehl aus:

Linux, macOS oder Cloud Shell

gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
    --member=PRINCIPAL --role=ROLE_NAME \
    --condition=CONDITION

Windows (PowerShell)

gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID `
    --member=PRINCIPAL --role=ROLE_NAME `
    --condition=CONDITION

Windows (cmd.exe)

gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID ^
    --member=PRINCIPAL --role=ROLE_NAME ^
    --condition=CONDITION

Die Antwort enthält die aktualisierte IAM-Zulassungsrichtlinie.

Terraform

Informationen zum Anwenden oder Entfernen einer Terraform-Konfiguration finden Sie unter Grundlegende Terraform-Befehle. Weitere Informationen finden Sie in der Referenzdokumentation des Anbieters zu Terraform.

So weisen Sie Dienst-Agents Rollen zu:

  1. Weisen Sie für jede google_workload_identity_service_agent-Ressource alle Rollen zu, die mit den Dienst-Agents verknüpft sind.

    Wenn Sie beispielsweise allen Dienst-Agents für die Ressource google_workload_identity_service_agent.primary Rollen zuweisen möchten, können Sie Ihrer Terraform-Konfiguration den folgenden Code hinzufügen: 

    # Grant roles to BigQuery service agents for project
resource "google_project_iam_member" "service_agents" {
  for_each = {
    for i, agent in google_workload_identity_service_agent.primary.service_agents :
    i => agent if try(agent.role, "") != ""
  }
  project = data.google_project.default.project_id
  role    = each.value.role
  member  = each.value.principal
}

  2. Führen Sie einen gezielten terraform apply-Befehl für die google_workload_identity_service_agent-Ressource aus, die Sie im Abschnitt Erstellung des Dienst-Agents auslösen auf dieser Seite hinzugefügt haben.

    Wenn Sie beispielsweise eine Ressource mit dem Namen google_workload_identity_service_agent.primary hinzugefügt haben, führen Sie den folgenden Befehl aus: 

    terraform apply target="google_workload_identity_service_agent.primary"

    Durch Ausführen dieses Befehls wird sichergestellt, dass die google_project_iam_member-Ressource auf Dienst-Agent-Ressourcen verweisen kann, ohne Known After Apply-Fehler zu erhalten.

  3. Führen Sie den Befehl terraform plan für Ihre Terraform-Konfiguration aus. Dieser Befehl zeigt den Ausführungsplan für das Zuweisen von Rollen an Dienst-Agents. Wenn der Ausführungsplan in Ordnung ist, führen Sie terraform apply aus, um ihn anzuwenden.

REST

Verwenden Sie die Liste der Rollen und Dienst-Agents, die Sie in Erstellung von Dienst-Agents auslösen erstellt haben, um zu ermitteln, welchen Dienst-Agents Rollen zugewiesen werden müssen. Verwenden Sie zum Zuweisen von Rollen für die Dienst-Agents das Read-Modify-Write-Muster, um die „allow“-Richtlinie der Ressource zu aktualisieren:

  1. Lesen Sie die aktuelle Zulassungsrichtlinie, indem Sie getIamPolicy aufrufen.

    Ersetzen Sie diese Werte in den folgenden Anfragedaten:

    • API_VERSION: Die zu verwendende API-Version. Verwenden Sie v1 für Projekte und Organisationen. Verwenden Sie v2 für Ordner.
    • RESOURCE_TYPE: Der Ressourcentyp, dessen Richtlinie Sie verwalten möchten. Verwenden Sie den Wert projects, folders oder organizations.
    • RESOURCE_ID: Die ID Ihres Google Cloud-Projekts, Ihrer Organisation oder Ihres Ordners. Projekt-IDs sind alphanumerische Strings, wie my-project. Ordner- und Organisations-IDs sind numerisch, z. B. 123456789012.
    • POLICY_VERSION: Die Richtlinienversion, die zurückgegeben werden soll. Anfragen sollten die neueste Richtlinienversion angeben. Diese ist Richtlinienversion 3. Weitere Informationen finden Sie unter Richtlinienversion beim Abrufen einer Richtlinie festlegen.

    HTTP-Methode und URL:

    POST https://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:getIamPolicy

    JSON-Text anfordern:

    {
  "options": {
    "requestedPolicyVersion": POLICY_VERSION
  }
}

    Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

    Die Antwort enthält die Zulassungsrichtlinie des Projekts. Beispiel: 

    {
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/owner",
      "members": [
        "user:my-user@example.com"
      ]
    }
  ]
}

  2. Erstellen Sie für jeden Dienst-Agent, dem Sie eine Rolle zuweisen möchten, eine Rollenbindung, die dem Dienst-Agent die erforderliche Rolle zuweist. Mit der folgenden Rollenbindung wird dem Dienst-Agent für benutzerdefinierten AI Platform-Code beispielsweise die Rolle „Dienst-Agent für benutzerdefinierten Vertex AI-Code“ (roles/aiplatform.customCodeServiceAgent) zugewiesen:

      {
    "role": "roles/aiplatform.customCodeServiceAgent",
    "members": [
      "serviceAccount:service-PROJECT_NUMBER@gcp-sa-aiplatform-cc.iam.gserviceaccount.com",
    ]
  }

    Wenn die „allow“-Richtlinie bereits eine Rollenbindung für die erforderliche Rolle enthält, fügen Sie den Dienst-Agent der Liste members für diese Rollenbindung hinzu.

  3. Schreiben Sie die aktualisierte Zulassungsrichtlinie durch Aufrufen von setIamPolicy.

    Ersetzen Sie diese Werte in den folgenden Anfragedaten:

    • API_VERSION: Die zu verwendende API-Version. Verwenden Sie v1 für Projekte und Organisationen. Verwenden Sie v2 für Ordner.
    • RESOURCE_TYPE: Der Ressourcentyp, dessen Richtlinie Sie verwalten möchten. Verwenden Sie den Wert projects, folders oder organizations.
    • RESOURCE_ID: Die ID Ihres Google Cloud-Projekts, Ihrer Organisation oder Ihres Ordners. Projekt-IDs sind alphanumerische Strings, wie my-project. Ordner- und Organisations-IDs sind numerisch, z. B. 123456789012.

    • POLICY: Eine JSON-Darstellung der Richtlinie, die Sie festlegen möchten. Weitere Informationen zum Format einer Richtlinie finden Sie in der Richtlinienreferenz.

    HTTP-Methode und URL:

    POST https://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:setIamPolicy

    JSON-Text anfordern:

    {
  "policy": POLICY
}

    Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

    Die Antwort enthält die aktualisierte Zulassungsrichtlinie:

Nächste Schritte