Workload Identity-Föderation mit Kubernetes konfigurieren

In diesem Leitfaden wird beschrieben, wie Sie mit Workload Identity-Föderation Arbeitslasten, die in Azure Kubernetes Service (AKS) oder in einem selbst gehosteten Kubernetes-Cluster ausgeführt werden, bei Google Cloud authentifizieren können.

Mit Kubernetes können Sie einen Cluster so konfigurieren, dass Arbeitslasten Kubernetes-Dienstkonto-Tokens aus einem projizierten Volume abrufen können. Wenn Sie die Workload Identity-Föderation einrichten, können Arbeitslasten diese Kubernetes-Dienstkonto-Tokens zur Authentifizierung bei Google Cloud verwenden.

Wenn Sie GKE verwenden, verwenden Sie anstelle von Workload Identity-Föderation Workload Identity.

Hinweise

Prüfen Sie vor der Konfiguration der Workload Identity-Föderation, ob Ihr Kubernetes-Cluster die folgenden Kriterien erfüllt:

AKS

Achten Sie darauf, dass Ihr Cluster die folgende Anforderung erfüllt:

  • Das Feature OIDC-Aussteller muss aktiviert sein.

    Sie müssen dieses Feature aktivieren, damit die Workload Identity-Föderation auf die OpenID Connect-Metadaten und das JSON Web Key Set (JWKS) für den Cluster zugreifen kann.

EKS

Sie müssen keine Änderungen an Ihrer EKS-Konfiguration vornehmen.

Kubernetes

Achten Sie darauf, dass Ihr Cluster die folgenden Anforderungen erfüllt:

  • Sie führen Kubernetes 1.20 oder höher aus.

    In früheren Versionen von Kubernetes wurde ein anderes Dienstkonto-Token-Format verwendet, das nicht mit den Anleitungen in diesem Dokument kompatibel ist.

  • Sie haben kube-apiserver so konfiguriert, dass es Projektionen für ServiceAccount-Token-Volumes unterstützt.

Der Cluster muss nicht über das Internet zugänglich sein.

Workload Identity-Föderation konfigurieren

Sie müssen diese Schritte nur einmal für jeden Kubernetes-Cluster ausführen. Sie können dann denselben Workload Identity-Pool und -Anbieter für mehrere Arbeitslasten und mehrere Google Cloud-Projekte verwenden.

So konfigurieren Sie die Workload Identity-Föderation:

  1. Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.

    Zur Projektauswahl

  2. Wir empfehlen, ein dediziertes Projekt zur Verwaltung von Workload Identity-Pools und -Anbietern.
  3. Die Abrechnung für das Google Cloud-Projekt muss aktiviert sein.

  4. IAM, Resource Manager, Service Account Credentials, and Security Token Service APIs aktivieren.

    Aktivieren Sie die APIs

Attributzuordnung und -bedingung definieren

Tokens für Kubernetes-Dienstkonten enthalten mehrere Anforderungen, darunter:

  • sub: enthält den Namespace und den Namen des Dienstkontos, z. B. system:serviceaccount:NAMESPACE:KSA_NAME, wobei NAMESPACE der Namespace des Dienstkontos und KSA_NAME der Name des Dienstkontos ist.
  • "kubernetes.io".namespace: enthält den Namespace des Dienstkontos.
  • "kubernetes.io".serviceaccount.name: enthält den Namen des Dienstkontos.
  • "kubernetes.io".pod.name: enthält den Namen des Pods.

Wenn Sie sub als Betreffkennung (google.subject) in Google Cloud nutzen möchten, verwenden Sie die folgende Zuordnung:

google.subject=assertion.sub

Optional können Sie zusätzliche Attribute zuordnen. Sie können dann auf diese Attribute verweisen, wenn Sie Zugriff auf Ressourcen gewähren. Beispiel:

google.subject=assertion.sub,
attribute.namespace=assertion['kubernetes.io']['namespace'],
attribute.service_account_name=assertion['kubernetes.io']['serviceaccount']['name'],
attribute.pod=assertion['kubernetes.io']['pod']['name']

Definieren Sie optional eine Attributbedingung. Attributbedingungen sind CEL-Ausdrücke, die Assertion-Attribute und Zielattribute prüfen können. Wenn die Attributbedingung bei bestimmten Anmeldedaten als true ausgewertet wird, werden die Anmeldedaten akzeptiert. Andernfalls werden die Anmeldedaten abgelehnt.

Sie können eine Attributbedingung verwenden, um einzuschränken, welche Kubernetes-Dienstkonten die Workload Identity-Föderation verwenden können, um kurzlebige Google Cloud-Tokens abzurufen. Die folgende Bedingung beschränkt beispielsweise den Zugriff auf Kubernetes-Dienstkonten aus den Namespaces backend und monitoring:

assertion['kubernetes.io']['namespace'] in ['backend', 'monitoring']

Workload Identity-Pool und -Anbieter erstellen

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für das Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Konfigurieren der Workload Identity-Föderation benötigen:

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Alternativ enthält die einfache Rolle „IAM-Inhaber“ (roles/owner) auch Berechtigungen zum Konfigurieren der Identitätsföderation. In einer Produktionsumgebung sollten Sie keine einfachen Rollen zuweisen, Sie können sie aber in einer Entwicklungs- oder Testumgebung gewähren.

So erstellen Sie einen Workload Identity-Pool und -Anbieter:

AKS

  1. Bestimmen Sie die Aussteller-URL Ihres AKS-Clusters:

    az aks show -n NAME -g RESOURCE_GROUP --query "oidcIssuerProfile.issuerUrl" -otsv
    

    Ersetzen Sie Folgendes:

    • NAME ist der Name des Clusters.
    • RESOURCE_GROUP: die Ressourcengruppe des Clusters

    Der Befehl gibt die Aussteller-URL aus. Sie benötigen die Aussteller-URL in einem der folgenden Schritte.

    Wenn der Befehl keine Aussteller-URL zurückgibt, prüfen Sie, ob Sie das Feature OIDC-Aussteller aktiviert haben.

  2. Erstellen Sie einen neuen Workload Identity-Pool:

    gcloud iam workload-identity-pools create POOL_ID \
        --location="global" \
        --description="DESCRIPTION" \
        --display-name="DISPLAY_NAME"
    

    Ersetzen Sie Folgendes:

    • POOL_ID: die eindeutige ID des Pools.
    • DISPLAY_NAME: der Name des Pools.
    • DESCRIPTION: eine Beschreibung des von Ihnen gewählten Pools. Diese Beschreibung wird angezeigt, wenn Sie Zugriff auf Poolidentitäten gewähren.
  3. Fügen Sie den AKS-Cluster als Workload Identity-Poolanbieter hinzu:

    gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
        --location="global" \
        --workload-identity-pool="POOL_ID" \
        --issuer-uri="ISSUER" \
        --attribute-mapping="MAPPINGS" \
        --attribute-condition="CONDITIONS"
    

    Ersetzen Sie Folgendes:

    • PROVIDER_ID: eine eindeutige Anbieter-ID für Workload Identity-Pool Ihrer Wahl.
    • POOL_ID: die ID des Workload Identity-Pools, die Sie zuvor erstellt haben.
    • ISSUER: der Aussteller-URI, den Sie zuvor ermittelt haben.
    • MAPPINGS: eine durch Kommas getrennte Liste der Attributzuordnungen, die Sie zuvor in dieser Anleitung erstellt haben.
    • CONDITIONS: eine optionale Attributbedingung, die Sie zuvor in dieser Anleitung erstellt haben. Entfernen Sie den Parameter, wenn keine Attributbedingung vorliegt.

EKS

  1. Bestimmen Sie die Aussteller-URL Ihres EKS-Clusters:

    aws eks describe-cluster --name NAME --query "cluster.identity.oidc.issuer" --output text
    

    Ersetzen Sie NAME durch den Namen des Clusters.

    Der Befehl gibt die Aussteller-URL aus. Sie benötigen die Aussteller-URL in einem der folgenden Schritte.

  2. Erstellen Sie einen neuen Workload Identity-Pool:

    gcloud iam workload-identity-pools create POOL_ID \
        --location="global" \
        --description="DESCRIPTION" \
        --display-name="DISPLAY_NAME"
    

    Ersetzen Sie Folgendes:

    • POOL_ID: die eindeutige ID des Pools.
    • DISPLAY_NAME: der Name des Pools.
    • DESCRIPTION: eine Beschreibung des von Ihnen gewählten Pools. Diese Beschreibung wird angezeigt, wenn Sie Zugriff auf Poolidentitäten gewähren.
  3. Fügen Sie den AKS-Cluster als Workload Identity-Poolanbieter hinzu:

    gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
        --location="global" \
        --workload-identity-pool="POOL_ID" \
        --issuer-uri="ISSUER" \
        --attribute-mapping="MAPPINGS" \
        --attribute-condition="CONDITIONS"
    

    Ersetzen Sie Folgendes:

    • PROVIDER_ID: eine eindeutige Anbieter-ID für Workload Identity-Pool Ihrer Wahl.
    • POOL_ID: die ID des Workload Identity-Pools, die Sie zuvor erstellt haben.
    • ISSUER: der Aussteller-URI, den Sie zuvor ermittelt haben.
    • MAPPINGS: eine durch Kommas getrennte Liste der Attributzuordnungen, die Sie zuvor in dieser Anleitung erstellt haben.
    • CONDITIONS: eine optionale Attributbedingung, die Sie zuvor in dieser Anleitung erstellt haben. Entfernen Sie den Parameter, wenn keine Attributbedingung vorliegt.

Kubernetes

  1. Stellen Sie eine Verbindung zu Ihrem Kubernetes-Cluster her und ermitteln Sie mit kubectl die Aussteller-URL des Clusters:

    kubectl get --raw /.well-known/openid-configuration | jq -r .issuer
    

    Sie benötigen die Aussteller-URL in einem der folgenden Schritte.

  2. Laden Sie das JSON Web Key Set (JWKS) des Clusters herunter:

    kubectl get --raw /openid/v1/jwks > cluster-jwks.json
    

    In einem der folgenden Schritte laden Sie das JWKS hoch, damit die Workload Identity-Föderation die Authentizität der von Ihrem Cluster ausgestellten Kubernetes-Dienstkonto-Tokens prüfen kann.

  3. Erstellen Sie einen neuen Workload Identity-Pool:

    gcloud iam workload-identity-pools create POOL_ID \
        --location="global" \
        --description="DESCRIPTION" \
        --display-name="DISPLAY_NAME"
    

    Ersetzen Sie Folgendes:

    • POOL_ID: die eindeutige ID des Pools.
    • DISPLAY_NAME: der Name des Pools.
    • DESCRIPTION: eine Beschreibung des von Ihnen gewählten Pools. Diese Beschreibung wird angezeigt, wenn Sie Zugriff auf Poolidentitäten gewähren.
  4. Fügen Sie den Kubernetes-Cluster als Workload Identity-Pool-Anbieter hinzu und laden Sie den JWKS des Clusters hoch:

    gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
        --location="global" \
        --workload-identity-pool="POOL_ID" \
        --issuer-uri="ISSUER" \
        --attribute-mapping="MAPPINGS" \
        --attribute-condition="CONDITIONS" \
        --jwk-json-path="cluster-jwks.json"
    

    Ersetzen Sie Folgendes:

    • PROVIDER_ID: eine eindeutige Anbieter-ID für Workload Identity-Pool Ihrer Wahl.
    • POOL_ID: die ID des Workload Identity-Pools, die Sie zuvor erstellt haben.
    • ISSUER: der Aussteller-URI, den Sie zuvor ermittelt haben.
    • MAPPINGS: eine durch Kommas getrennte Liste der Attributzuordnungen, die Sie zuvor in dieser Anleitung erstellt haben.
    • CONDITIONS: eine optionale Attributbedingung, die Sie zuvor in dieser Anleitung erstellt haben. Entfernen Sie den Parameter, wenn keine Attributbedingung vorliegt.

Kubernetes-Arbeitslast authentifizieren

In diesem Abschnitt wird beschrieben, wie Sie eine Kubernetes-Arbeitslast für die Verwendung der Workload Identity-Föderation konfigurieren.

Sie müssen diese Schritte einmal für jede Kubernetes-Arbeitslast ausführen, die Zugriff auf Google Cloud benötigt.

Zwei Dienstkonten erstellen

Damit sich eine Kubernetes-Arbeitslast bei Google Cloud authentifizieren kann, benötigen Sie ein Paar Dienstkonten:

  • Ein Kubernetes-Dienstkonto, das Sie an den Kubernetes-Pod anhängen.
  • Ein IAM-Dienstkonto, dessen Identität die Kubernetes-Arbeitslast mit dem angehängten Kubernetes-Dienstkonto übernehmen kann.

So erstellen Sie die Dienstkonten:

  1. Erstellen Sie ein IAM-Dienstkonto, das die Arbeitslast darstellt.

    Das Dienstkonto muss sich nicht im selben Projekt wie der Workload Identity-Pool befinden.

    gcloud iam service-accounts create SA_NAME
    

    Ersetzen Sie Folgendes:

    • SA_NAME: der Name des Dienstkontos
  2. Erstellen Sie ein Kubernetes-Dienstkonto:

    kubectl create serviceaccount KSA_NAME --namespace NAMESPACE
    

    Ersetzen Sie Folgendes:

    • KSA_NAME: der Name des Dienstkontos
    • NAMESPACE: der Namespace, in dem das Dienstkonto erstellt werden soll.
  3. Gewähren Sie dem IAM-Dienstkonto Zugriff auf Ressourcen, auf die die Kubernetes-Arbeitslast zugreifen soll.

  4. Weisen Sie der externen Identität des Kubernetes-Dienstkontos die Rolle "Workload Identity-Nutzer" (roles/iam.workloadIdentityUser) zu:

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
        --role=roles/iam.workloadIdentityUser \
        --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT"
    

    Ersetzen Sie Folgendes:

    • SERVICE_ACCOUNT_EMAIL: die E-Mail-Adresse des Dienstkontos.
    • PROJECT_NUMBER: die Projektnummer des Projekts, das den Workload Identity-Pool enthält.
    • POOL_ID: die Pool-ID des Workload Identity-Pools.
    • SUBJECT: der erwartete Wert für das Attribut, das Sie google.subject zugeordnet haben, z. B. system:serviceaccount:NAMESPACE:KSA_NAME.

Kubernetes-Arbeitslast bereitstellen

Stellen Sie jetzt eine Kubernetes-Arbeitslast bereit und lassen Sie die Arbeitslast das Dienstkontopaar verwenden:

  1. Erstellen Sie eine Konfigurationsdatei für Anmeldedaten:

    gcloud iam workload-identity-pools create-cred-config \
        projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
        --service-account=SERVICE_ACCOUNT_EMAIL \
        --credential-source-file=/var/run/service-account/token \
        --credential-source-type=text \
        --output-file=credential-configuration.json
    

    Ersetzen Sie Folgendes:

    • PROJECT_NUMBER: Projektnummer des Projekts, das den Workload Identity-Pool enthält
    • POOL_ID: die ID des Workload Identity-Pools
    • PROVIDER_ID: die ID des Workload Identity-Poolanbieters
    • SERVICE_ACCOUNT_EMAIL: E-Mail-Adresse des Dienstkontos

    Mit der Konfigurationsdatei für Anmeldedaten können die Cloud-Clientbibliotheken, die gcloud CLI und Terraform Folgendes ermitteln:

    • Wo externe Anmeldedaten abgerufen werden
    • Welcher Workload Identity-Pool und -Anbieter verwendet werden
    • Welches Dienstkonto übernommen wird
  2. Importieren Sie die Konfigurationsdatei für Anmeldedaten als ConfigMap:

    kubectl create configmap CONFIGMAP_NAME \
      --from-file credential-configuration.json \
      --namespace NAMESPACE
    

    Ersetzen Sie Folgendes:

    • CONFIGMAP_NAME: der Name der ConfigMap.
    • NAMESPACE: der Namespace, in dem die ConfigMap erstellt werden soll.
  3. Stellen Sie eine Arbeitslast bereit und lassen Sie sie das Kubernetes-Dienstkonto und ConfigMap verwenden.

    Erstellen Sie ein Manifest und konfigurieren Sie es so:

    • Stellen Sie ein projiziertes Token-Volume bereit, damit die Arbeitslast ein Kubernetes-Dienstkonto-Token aus einer lokalen Datei abrufen kann. Konfigurieren Sie das Volume so, dass das Token des Kubernetes-Dienstkontos die Zielgruppe verwendet, die vom Workload Identity-Föderationspoolanbieter erwartet wird.
    • Stellen Sie die ConfigMap bereit, die die Konfigurationsdatei für Anmeldedaten enthält, damit die Arbeitslast auf die erforderliche Konfiguration für die Verwendung der Workload Identity-Föderation zugreifen kann.
    • Fügen Sie eine Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS hinzu, die den Pfad der Konfigurationsdatei für Anmeldedaten enthält, damit Arbeitslasten die Datei finden können.

    Das folgende Beispiel zeigt das Kubernetes-Dienstkonto und die ConfigMap, damit sich die Google Cloud CLI bei Google Cloud authentifizieren kann:

    apiVersion: v1
    kind: Pod
    metadata:
      name: example
      namespace: NAMESPACE
    spec:
      containers:
      - name: example
        image: google/cloud-sdk:alpine
        command: ["/bin/sh", "-c", "gcloud auth login --cred-file $GOOGLE_APPLICATION_CREDENTIALS && gcloud auth list && sleep 600"]
        volumeMounts:
        - name: token
          mountPath: "/var/run/service-account"
          readOnly: true
        - name: workload-identity-credential-configuration
          mountPath: "/etc/workload-identity"
          readOnly: true
        env:
        - name: GOOGLE_APPLICATION_CREDENTIALS
          value: "/etc/workload-identity/credential-configuration.json"
    
      serviceAccountName: KSA_NAME
      volumes:
      - name: token
        projected:
          sources:
          - serviceAccountToken:
              audience: https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID
              expirationSeconds: 3600
              path: token
      - name: workload-identity-credential-configuration
        configMap:
          name: CONFIGMAP_NAME
    

    Sie können genauso vorgehen, damit Tools und Arbeitslasten, die eine der folgenden Clientbibliotheken verwenden, Anmeldedaten automatisch finden:

    C++

    Die Google Cloud-Clientbibliotheken für C++ unterstützen die Mitarbeiteridentitätsföderation seit Version v2.6.0. Wenn Sie die Mitarbeiteridentitätsföderation verwenden möchten, müssen Sie die Clientbibliotheken mit Version 1.36.0 oder höher von gRPC erstellen.

    Einfach loslegen (Go)

    Clientbibliotheken für Go unterstützen die Identitätsföderation, wenn sie Version 0.0.0-2021218202405-ba52d332ba99 oder höher des Moduls golang.org/x/oauth2 verwenden.

    Führen Sie die folgenden Befehle aus, um zu überprüfen, welche Version dieses Moduls in Ihrer Clientbibliothek verwendet wird:

    cd $GOPATH/src/cloud.google.com/go
    go list -m golang.org/x/oauth2
    

    Java

    Clientbibliotheken für Java unterstützen die Identitätsföderation, wenn sie Version 0.24.0 oder höher des com.google.auth:google-auth-library-oauth2-http-Artefakts verwenden.

    Führen Sie den folgenden Maven-Befehl in Ihrem Anwendungsverzeichnis aus, um zu überprüfen, welche Version dieses Artefakts Ihre Clientbibliothek verwendet:

    mvn dependency:list -DincludeArtifactIds=google-auth-library-oauth2-http
    

    Node.js

    Clientbibliotheken für Node.js unterstützen die Workload Identity-Föderation, wenn sie Version 7.0.2 oder höher des google-auth-library-Pakets verwenden.

    Führen Sie den folgenden Befehl in Ihrem Anwendungsverzeichnis aus, um zu überprüfen, welche Version dieses Pakets verwendet wird:

    npm list google-auth-library
    

    Wenn Sie ein GoogleAuth-Objekt erstellen, können Sie eine Projekt-ID angeben oder GoogleAuth erlauben, automatisch nach der Projekt-ID zu suchen. Damit automatisch nach der Projekt-ID gesucht werden kann, muss das Dienstkonto in der Konfigurationsdatei in Ihrem Projekt die Rolle „Sucher“ (roles/browser) oder eine Rolle mit entsprechenden Berechtigungen haben. Weitere Informationen finden Sie unter README für das Paket google-auth-library.

    Python

    Clientbibliotheken für Python unterstützen die Identitätsföderation, wenn sie Version 1.7.0 oder höher des google-auth-Pakets verwenden.

    Führen Sie den folgenden Befehl in der Umgebung aus, in der das Paket installiert ist, um zu ermitteln, welche Version dieses Pakets verwendet wird:

    pip show google-auth
    

    Wenn Sie eine Projekt-ID für den Authentifizierungsclient angeben, können Sie die Umgebungsvariable GOOGLE_CLOUD_PROJECT festlegen oder Sie gestatten dem Client, automatisch nach der Projekt-ID zu suchen. Damit automatisch nach der Projekt-ID gesucht werden kann, muss das Dienstkonto in der Konfigurationsdatei in Ihrem Projekt die Rolle „Sucher“ (roles/browser) oder eine Rolle mit entsprechenden Berechtigungen haben. Weitere Informationen finden Sie im Nutzerhandbuch für das Paket google-auth.

    gcloud

    Verwenden Sie zum Authentifizieren der Workload Identity-Föderation den Befehl gcloud auth login:

    gcloud auth login --cred-file=FILEPATH.json
    

    Ersetzen Sie FILEPATH durch den Dateipfad zur Konfigurationsdatei für Anmeldedaten.

    Unterstützung für die Workload Identity-Föderation in der gcloud CLI ist in Version 363.0.0 und höher des gcloud CLI verfügbar.

    Terraform

    Der Google Cloud-Anbieter unterstützt die Workload Identity-Föderation, wenn Sie Version 3.61.0 oder höher verwenden:

    terraform {
      required_providers {
        google = {
          source  = "hashicorp/google"
          version = "~> 3.61.0"
        }
      }
    }
    

    gsutil

    Verwenden Sie eine der folgenden Methoden, um sich mit einer Workload Identity-Föderation zu authentifizieren:

    Wenn Sie gsutil zusammen mit gcloud verwenden, melden Sie sich wie gewohnt an:

    gcloud auth login --cred-file=FILEPATH.json
    

    Wenn Sie gsutil als eigenständige Befehlszeilenanwendung verwenden, bearbeiten Sie die .boto-Datei so, dass sie Folgendes enthält:

    [Credentials]
    gs_external_account_file = FILEPATH
    

    Ersetzen Sie in beiden Fällen FILEPATH durch den Dateipfad zur Konfigurationsdatei für Anmeldedaten.

    Unterstützung für Workload Identity-Föderation in gsutil ist in Version 379.0.0 und späteren Versionen der gcloud CLI verfügbar.

    bq

    Verwenden Sie für die Authentifizierung mithilfe der Workload Identity-Föderation den Befehl gcloud auth login:

    gcloud auth login --cred-file=FILEPATH.json
    

    Ersetzen Sie FILEPATH durch den Dateipfad zur Konfigurationsdatei für Anmeldedaten.

    Unterstützung für Workload Identity-Föderation in bq ist in Version 390.0.0 und späteren Versionen der gcloud CLI verfügbar.

  4. Optional können Sie prüfen, ob die Authentifizierung ordnungsgemäß funktioniert, indem Sie den folgenden Befehl ausführen:

    kubectl exec example --namespace NAMESPACE -- gcloud auth print-access-token
    

Nächste Schritte