In diesem Thema wird erläutert, wie Sie Workload Identity für Apigee Hybrid-Installationen auf AKS- und AKS-Plattformen aktivieren.
Übersicht
Mit der Workload Identity-Föderation können Anwendungen, die außerhalb von Google Cloud ausgeführt werden, die Identität eines Google Cloud Platform-Dienstkontos mithilfe von Anmeldedaten eines externen Identitätsanbieters übernehmen.
Die Workload Identity-Föderation kann zur Verbesserung der Sicherheit beitragen, indem Anwendungen die Authentifizierungsmechanismen nutzen, die die externe Umgebung bereitstellt, und Dienstkontoschlüssel können ersetzt werden.
Wenn Sie Workload Identity-Föderation mit Apigee Hybrid verwenden möchten, konfigurieren Sie zuerst den Cluster und wenden Sie das Feature dann auf Ihre Apigee Hybrid-Installation an.
Konfigurieren Sie Ihren Cluster für die Verwendung der Workload Identity-Föderation.
Mit den folgenden Befehlen können Sie Ihre IAM-Dienstkonten und Kubernetes-Dienstkonten auflisten:
IAM-Dienstkonten: Sie haben die IAM-Dienstkonten (auch als "Google-Dienstkonten" bezeichnet) wahrscheinlich bereits bei der Erstinstallation von Apigee Hybrid mit dem create-service-account-Tool erstellt. Unter Informationen zu Dienstkonten finden Sie eine Liste der IAM-Dienstkonten, die von Apigee Hybrid benötigt werden.
Mit dem folgenden Befehl können Sie eine Liste der IAM-Dienstkonten in Ihrem Projekt aufrufen:
gcloud iam service-accounts list --project PROJECT_ID
Kubernetes-Dienstkonten: Die Apigee Hybrid-Diagramme erstellen die erforderlichen Kubernetes-Dienstkonten für jede Komponente, wenn Sie den Befehl helm install oder helm update ausführen.
Sie können die Kubernetes-Dienstkonten in Ihrem Cluster mit den kubectl get sa-Befehlen aufrufen:
kubectl get sa -n APIGEE_NAMESPACEkubectl get sa -n apigee-system
Im Schritt Identitätsföderation von Arbeitslasten konfigurieren ist die Standardzielgruppe für erstellte Workload Identity-Pools und ‑Anbieter wie unten angegeben. Verwenden Sie diesen Standardwert oder legen Sie eine benutzerdefinierte Zielgruppe fest und speichern Sie diesen Wert für später.
Beenden Sie die Anleitung nach Schritt 1 unter Kubernetes-Arbeitslast bereitstellen. Für jedes Google-Dienstkonto gibt es eine Anmeldedatenkonfigurationsdatei. Speichern Sie jede Konfigurationsdatei für Anmeldedaten und den für den Parameter --credential-source-file eingegebenen Pfad, z. B. /var/run/service-account/token.
Apigee Hybrid für die Verwendung der Workload Identity-Föderation konfigurieren
Kopieren Sie die Quelldatei der Anmeldedaten und die Ausgabedatei (credential-configuration.json) in die folgenden Diagrammverzeichnisse. Dies sind die Werte, die Sie in Schritt 1 unter Kubernetes-Arbeitslast bereitstellen angegeben haben.
apigee-datastore/
apigee-env
apigee-org/
apigee-telemetry/
Nehmen Sie die folgenden globalen Änderungen an der Überschreibungsdatei Ihres Clusters vor:
gcp:
workloadIdentity:
enabled: false # must be set to false to use Workload Identity Federation
federatedWorkloadIdentity:
enabled: true
audience: "AUDIENCE"
credentialSourceFile: "CREDENTIAL_SOURCE_FILE"
Wobei:
AUDIENCE ist die zulässige Zielgruppe des Workload Identity-Anbieters, der Wert unter .audience in der JSON-Datei zur Konfiguration der Anmeldedaten, die Sie in Schritt 1 unter Kubernetes-Arbeitslast bereitstellen konfiguriert haben.
CREDENTIAL_SOURCE_FILE ist der Dateiname und der Pfad zur Anmeldedatenquelle, die von der Workload Identity-Föderation zum Abrufen der Anmeldedaten für die Dienstkonten verwendet wird. Dies ist der Wert, den Sie für credential-source-file angeben, wenn Sie die Workload Identity-Föderation mit dem Befehl create-cred-config in Schritt 1 unter Kubernetes-Arbeitslast bereitstellen konfigurieren. Beispiel:
Konfigurieren Sie die Überschreibungen für jede Komponente mithilfe der Workload Identity-Föderation. Wählen Sie die Anleitung für Zertifikatdateien, Kubernetes-Secrets oder Vault aus, die für Ihre Installation geeignet ist.
[[["Leicht verständlich","easyToUnderstand","thumb-up"],["Mein Problem wurde gelöst","solvedMyProblem","thumb-up"],["Sonstiges","otherUp","thumb-up"]],[["Schwer verständlich","hardToUnderstand","thumb-down"],["Informationen oder Beispielcode falsch","incorrectInformationOrSampleCode","thumb-down"],["Benötigte Informationen/Beispiele nicht gefunden","missingTheInformationSamplesINeed","thumb-down"],["Problem mit der Übersetzung","translationIssue","thumb-down"],["Sonstiges","otherDown","thumb-down"]],["Zuletzt aktualisiert: 2025-08-28 (UTC)."],[[["\u003cp\u003eWorkload Identity Federation enables applications outside Google Cloud to impersonate a Google Cloud service account using external identity provider credentials, enhancing security.\u003c/p\u003e\n"],["\u003cp\u003eTo enable Workload Identity Federation for Apigee hybrid on AKS and EKS, you must first configure your cluster according to Google Cloud instructions, followed by applying the feature to your Apigee hybrid installation.\u003c/p\u003e\n"],["\u003cp\u003eThe configuration process involves listing IAM service accounts and Kubernetes service accounts, setting a default or custom audience for Workload Identity pools, and saving credential configuration files.\u003c/p\u003e\n"],["\u003cp\u003eApigee hybrid components can be configured individually to utilize Workload Identity Federation, either globally or selectively for specific services like UDCA or Synchronizer, by updating the cluster's overrides file and applying the changes.\u003c/p\u003e\n"],["\u003cp\u003eCredential source files can be managed through various methods such as cert files, Kubernetes secrets, or Vault, and the changes should be applied to the relevant components using the \u003ccode\u003ehelm update\u003c/code\u003e command in the specified order.\u003c/p\u003e\n"]]],[],null,["# Enabling Workload Identity Federation on AKS and EKS\n\n| You are currently viewing version 1.12 of the Apigee hybrid documentation. **This version is end of life.** You should upgrade to a newer version. For more information, see [Supported versions](/apigee/docs/hybrid/supported-platforms#supported-versions).\n\n\nThis topic explains how to enable Workload Identity for Apigee hybrid installations on **AKS** and **EKS** platforms.\n\nOverview\n--------\n\n\nWorkload identity federation lets applications running outside Google Cloud impersonate a Google Cloud Platform service account by using credentials from an external identity provider.\n\n\nUsing workload identity federation can help you improve security by letting applications use the authentication mechanisms that the external environment provides and can help [replace service account keys](/iam/docs/best-practices-service-accounts#using_service_accounts).\n\n\nFor an overview, see [Best practices for using Workload Identity Federation](/iam/docs/best-practices-for-using-workload-identity-federation).\n| **Note:** The `apige-logger` component does not support Workload Identity Federation. See the [known issue](/apigee/docs/release/known-issues#hybrid-apigee-logger-wif).\n\nSet up Workload Identity Federation\n-----------------------------------\n\n\nTo use Workload Identity Federation with Apigee hybrid, first configure you cluster and then apply the feature to your Apigee hybrid installation.\n\n### Configure your cluster to use Workload Identity Federation.\n\n\nFollow the Google Cloud instructions to [Configure Workload Identity Federation for Kubernetes](/iam/docs/workload-identity-federation-with-kubernetes), with the following modifications:\n\n- List your IAM service accounts and Kubernetes service accounts with the following commands:\n - **IAM service accounts:** You most likely have already created the IAM service accounts (also called \"Google service accounts\") during initial installation of Apigee hybrid with the [`create-service-account`](/apigee/docs/hybrid/v1.12/create-service-account) tool. See [About service accounts](/apigee/docs/hybrid/v1.12/sa-about#recommended-sas) for a list of IAM service accounts needed by Apigee hybrid.\n\n\n You can see a list of IAM service accounts in your project with the following command: \n\n ```\n gcloud iam service-accounts list --project PROJECT_ID\n ```\n - **Kubernetes service accounts:** The Apigee hybrid charts create the necessary Kubernetes service accounts for each component when you run the `helm install` or `helm update` command.\n\n\n You can see the Kubernetes service accounts in your cluster with the `kubectl get sa` commands: \n\n kubectl get sa -n APIGEE_NAMESPACE\n kubectl get sa -n apigee-system\n\n- In the step [Configure Workload Identity Federation](/iam/docs/workload-identity-federation-with-kubernetes#configure), the default audience for created Workload Identity pools and providers is as follows. Use this default or set a custom expected audience, and save this value for later use. \n\n ```\n https://iam.googleapis.com/projects/PROJECT_NUM/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID\n ```\n- Stop after **step 1** under [Deploy a Kubernetes workload](/iam/docs/workload-identity-federation-with-kubernetes#deploy). There will be one credential configuration file for each Google service account. Save each credential configuration file and save the path entered for the `--credential-source-file` parameter, for example: `/var/run/service-account/token`. **Tip:** You can also find the values for `audience` and `credentialSourceFile` in the credential configuration json file, under the paths `.audience` and `.credential_source.file` respectively. You will need these values for the overrides file to configure Apigee hybrid.\n\n### Configure Apigee hybrid to use Workload Identity Federation\n\n| **Tip:** You can configure your hybrid installation to use Workload Identity Federation for any or all components. For example UDCA can use Workload Identity Federation while Synchronizer uses Google IAM service accounts or vice versa.\n\n1. Copy the credential source file and the output file (`credential-configuration.json`) into the following chart directories. These were the values you provided in **step 1** under [Deploy a Kubernetes workload](/iam/docs/workload-identity-federation-with-kubernetes#deploy).\n - `apigee-datastore/`\n - `apigee-env`\n - `apigee-org/`\n - `apigee-telemetry/`\n\n | **Tip:** You can use a subdirectory for these files, for example: `apigee-datastore/fwi/`\n2. Make the following global changes to your cluster's overrides file: \n\n ```\n gcp:\n workloadIdentity:\n enabled: false # must be set to false to use Workload Identity Federation\n federatedWorkloadIdentity:\n enabled: true\n audience: \"AUDIENCE\"\n credentialSourceFile: \"CREDENTIAL_SOURCE_FILE\"\n ```\n\n\n Where:\n - \u003cvar translate=\"no\"\u003eAUDIENCE\u003c/var\u003e is the allowed audience of the Workload Identity Provider, the value under `.audience` in the credential configuration json file you configured in **step 1** under [Deploy a Kubernetes workload](/iam/docs/workload-identity-federation-with-kubernetes#deploy).\n - \u003cvar translate=\"no\"\u003eCREDENTIAL_SOURCE_FILE\u003c/var\u003e is the filename and path to the credential source file used by Workload Identity Federation to obtain the credentials for the service accounts. This is the value you provide for `credential-source-file` when you configure Workload Identity Federation with the `create-cred-config` command in **step 1** under [Deploy a Kubernetes workload](/iam/docs/workload-identity-federation-with-kubernetes#deploy). For example:\n - For example: \n\n ```\n gcp:\n workloadIdentity:\n enabled: false\n federatedWorkloadIdentity:\n enabled: true\n audience: \"//iam.googleapis.com/projects/123456789012/locations/global/workloadIdentityPools/aws-pool/providers/aws-provider\"\n credentialSourceFile: \"/var/run/service-account/token\"\n ```\n3. Configure the overrides for each component using Workload Identity Federation. Select the instructions for cert files, Kubernetes secrets, or Vault as appropriate for your installation.\n\n ### Cert file\n\n Replace the value of `serviceAccountPath` with the credential source file. This must be the path relative to the chart directory. For example: \n\n ```\n udca:\n serviceAccountPath: fwi/credential-configuration.json\n ```\n\n ### K8s Secret\n\n 1. Create a new Kubernetes secret using for the credential source file. \n\n ```\n kubectl create secret -n apigee generic SECRET_NAME --from-file=\"client_secret.json=CREDENTIAL_CONFIGURATION_FILE\"\n ```\n\n For example: \n\n ```\n kubectl create secret -n apigee generic udca-fwi-secret --from-file=\"client_secret.json=./fwi/credential-configuration.json\"\n ```\n 2. Replace the value of `serviceAccountRef` with the new secret. For example: \n\n ```\n udca:\n serviceAccountRef: udca-fwi-secret\n ```\n\n ### Vault\n\n Update the service account key, `SAKEY` in Vault with the credential source file. For example, for UDCA (the procedure is similar for all components): \n\n ```\n SAKEY=$(cat ./fwi/credential-configuration.json); kubectl -n apigee exec vault-0 -- vault kv patch secret/apigee/orgsakeys udca=\"$SAKEY\"\n ```\n4. Apply the changes to each affected component with the `helm update` command:\n\n\n If you are using Vault for the first time with this cluster, update the `apigee-operator` chart: \n\n ```\n helm upgrade operator apigee-operator/ \\\n --namespace apigee-system \\\n --atomic \\\n -f overrides.yaml\n ```\n\n\n Update the rest of the affected charts in the following order: \n\n ```\n helm upgrade datastore apigee-datastore/ \\\n --namespace apigee \\\n --atomic \\\n -f overrides.yaml\n ``` \n\n ```\n helm upgrade telemetry apigee-telemetry/ \\\n --namespace apigee \\\n --atomic \\\n -f overrides.yaml\n ``` \n\n ```\n helm upgrade $ORG_NAME apigee-org/ \\\n --namespace apigee \\\n --atomic \\\n -f overrides.yaml\n ```\n\n\n Update the `apigee-env` chart for each env, replacing \u003cvar translate=\"no\"\u003eENV_NAME\u003c/var\u003e each time: \n\n ```\n helm upgrade $ENV_NAME apigee-env/ \\\n --namespace apigee \\\n --atomic \\\n --set env=$ENV_NAME \\\n -f overrides.yaml\n ```\n\n See the [Apigee hybrid Helm reference](/apigee/docs/hybrid/v1.12/helm-reference) for a list of components and their corresponding charts.\n\nFor more information about Workload Identity Federation and best practices, see [Best practices for using workload identity federation](/iam/docs/best-practices-for-using-workload-identity-federation)."]]
