Supported versions:
Unsupported versions:
Follow these steps if you set up your overrides file for Workload Identity on GKE in Step 6: Create the overrides.
If you are not using Workload Identity on GKE, proceed to Part 3, Step 1: Expose Apigee ingress gateway.
A Google Cloud service account is a special kind of account that can be used to make authorized API calls by authenticating as the service account itself. Google Cloud service accounts can be given roles and permissions similar to an individual user. When an application authenticates as a service account, it has access to all resources that the service account has permission to access. If you want to learn more about Google Cloud service accounts, see Service accounts overview.
You created Google Cloud service accounts for your Apigee hybrid installation in Step 4: Create service accounts. Apigee uses these service accounts to authenticate the hybrid components.
Kubernetes service accounts are similar to Google Cloud service accounts. A Kubernetes service account provides an identity for processes that run in a Pod, and allows it to authenticate to the API server similarly to a user. If you want to learn more about Kubernetes service accounts, see Configure Service Accounts for Pods.
If you have gcp.workloadIdentity.enabled set to true in your
overrides file, when Helm charts for each hybrid component will create the Kubernetes service
accounts for the components when you install or upgrade them like you did in
Step 11: Install Apigee hybrid using Helm charts.
When you configure Workload Identity on GKE, you associate the Google Cloud service accounts with the Kubernetes service accounts in the Kubernetes cluster. That way, the Kubernetes service accounts can impersonate the Google Cloud service accounts and use their assigned roles and permissions to authenticate with the hybrid components.
Follow these instructions to configure Workload Identity for your project.
namespace is required. For example:
instanceID: "hybrid-instance-1" namespace: "apigee"
apigeectl. For Helm, gcp.workloadIdentity.enabled replaces
gcp.workloadIdentityEnabled.gcp.workloadIdentity.gsa. For example:
gcp:
workloadIdentity:
enabled: true
gsa: "apigee-non-prod@my-hybrid-project.iam.gserviceaccount.com"
gsa property.
For example:
logger:
gsa: "apigee-logger@my-hybrid-project.iam.gserviceaccount.com"
gcloud configuration is set to your Google Cloud project ID with
the following command:
gcloud config get project
If needed, set the current gcloud configuration:
gcloud config set project $PROJECT_ID
gcloud container clusters describe $CLUSTER_NAME \ --region $CLUSTER_LOCATION \ --project $PROJECT_ID \ --flatten 'workloadIdentityConfig'
gcloud container clusters describe $CLUSTER_NAME \ --zone $CLUSTER_LOCATION \ --project $PROJECT_ID \ --flatten 'workloadIdentityConfig'
Your output should look like the following:
--- workloadPool: PROJECT_ID.svc.id.goog
If you see null instead in your results, run the following
command to enable Workload Identity for your cluster:
gcloud container clusters update $CLUSTER_NAME \ --workload-pool=$PROJECT_ID.svc.id.goog \ --project $PROJECT_ID \ --region $CLUSTER_LOCATION
gcloud container clusters update $CLUSTER_NAME \ --workload-pool=$PROJECT_ID.svc.id.goog \ --zone $CLUSTER_LOCATION \ --project $PROJECT_ID
Enable Workload Identity for each node pool with the following commands. This operation can take up to 30 minutes for each node:
gcloud container node-pools update NODE_POOL_NAME \ --cluster=$CLUSTER_NAME \ --region $CLUSTER_LOCATION \ --project $PROJECT_ID \ --workload-metadata=GKE_METADATA
gcloud container node-pools update NODE_POOL_NAME \ --cluster=$CLUSTER_NAME \ --zone $CLUSTER_LOCATION \ --project $PROJECT_ID \ --workload-metadata=GKE_METADATA
Where NODE_POOL_NAME is the name of each node pool. In most Apigee hybrid
installations, the two default node pools are named apigee-data and
apigee-runtime.
gcloud container node-pools describe apigee-data \ --cluster $CLUSTER_NAME \ --region $CLUSTER_LOCATION \ --project $PROJECT_ID \ --flatten "config:"
gcloud container node-pools describe apigee-runtime \ --cluster $CLUSTER_NAME \ --region $CLUSTER_LOCATION \ --project $PROJECT_ID \ --flatten "config:"
gcloud container node-pools describe apigee-data \ --cluster $CLUSTER_NAME \ --zone $CLUSTER_LOCATION \ --project $PROJECT_ID \ --flatten "config:"
gcloud container node-pools describe apigee-runtime \ --cluster $CLUSTER_NAME \ --zone $CLUSTER_LOCATION \ --project $PROJECT_ID \ --flatten "config:"
Your output should look something like:
---
diskSizeGb: 100
diskType: pd-standard
...
workloadMetadataConfig:
mode: GKE_METADATA
Use the following procedure to enable Workload Identity for the following Hybrid components:
apigee-datastoreapigee-telemetryapigee-orgapigee-envWhen you run the helm upgrade with the
--dry-run flag for the apigee-datastore, apigee-env,
apigee-org, and apigee-telemetry charts, the output will include the
commands you will need to configure Workload Identity with the correct GSA and KSA names.
For example:
helm upgrade datastore apigee-datastore/ \ --namespace $NAMESPACE \ -f overrides.yaml \ --dry-run
NAME: datastore
...
For C* backup GKE Workload Identity, please make sure to add the below membership to the IAM policy binding using the respective kubernetes SA (KSA).
gcloud iam service-accounts add-iam-policy-binding \
--role roles/iam.workloadIdentityUser \
--member "serviceAccount:my-project.svc.id.goog[apigee/apigee-cassandra-backup-sa]" \
--project :my-project
apigee-datastore and run the command under NOTES: in the output.
helm upgrade datastore apigee-datastore/ \ --namespace $NAMESPACE \ -f overrides.yaml \ --dry-run
apigee-telemetry and run the command under NOTES: in the output.
helm upgrade telemetry apigee-telemetry/ \ --namespace $NAMESPACE \ -f overrides.yaml \ --dry-run
apigee-org and run the command under NOTES: in the output.
helm upgrade $ORG_NAME apigee-org/ \ --namespace $NAMESPACE \ -f overrides.yaml \ --dry-run
apigee-env and run the command under NOTES: in the output.
helm upgrade $ENV_NAME apigee-env/ \ --namespace $NAMESPACE \ --set env=ENV_NAME \ -f overrides.yaml \ --dry-run
Repeat this step for each environment in your installation.
In the next step, you will configure the Apigee ingress gateway and deploy a proxy to test your installation.
(NEXT) Step 1: Expose Apigee ingress 2Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2026-06-11 UTC.