This page applies to Apigee, but not to Apigee hybrid.
View Apigee Edge documentation.
This page describes the steps required to install and configure the Apigee APIM Operator for Kubernetes (Preview). To learn more about the benefits of using the APIM Operator, see Apigee APIM Operator for Kubernetes overview.
Before you begin
Before you begin installing the APIM Operator, make sure that you have the required roles and permissions required to complete the steps and that you have completed the prerequisite tasks described in APIM Operator: Before you begin.
Required roles
To get the permissions that you need to install the APIM Operator, ask your administrator to grant you the following IAM roles on the organization:
-
Create and manage the GKE cluster:
Container Admin (
roles/container.admin
) -
Create and manage service accounts:
Service Account Admin (
roles/iam.serviceAccountAdmin
) -
Create and manage service extensions:
Service Extensions Admin (
roles/networkservices.serviceExtensionsAdmin
) -
Create and manage network endpoint groups (NEGs):
Compute Instance Admin (
roles/compute.instanceAdmin
) -
Create and manage backend services:
Compute Load Balancer Admin (
roles/compute.loadBalancerAdmin
) -
Create and manage Apigee resources:
Apigee Admin (
roles/apigee.admin
)
For more information about granting roles, see Manage access to projects, folders, and organizations.
You might also be able to get the required permissions through custom roles or other predefined roles.
Install and configure the APIM Operator
The following sections describe the steps required to install and configure the APIM Operator:
- Set environment variables.
- Enable the required APIs.
- Retrieve and configure credentials.
- Install the APIM Operator.
- Create a workload identity.
- Optional: Create an Apigee environment.
- Verify GKE Gateway set up.
Set environment variables
In the Google Cloud project that contains your Apigee instance, use the following command to set environment variables:
export PROJECT_ID=PROJECT_ID
export CLUSTER_NAME=CLUSTER_NAME
export REGION=REGION
export APIGEE_ORG=APIGEE_ORG
Where:
PROJECT_ID
is the ID of the project with your Apigee instance.CLUSTER_NAME
is the name of your GKE cluster.REGION
is the region of your GKE cluster.APIGEE_ORG
is set to the same value asPROJECT_ID
.
To confirm that the environment variables are set correctly, run the following command:
echo $PROJECT_ID $CLUSTER_NAME $REGION $APIGEE_ORG
Enable required APIs
APIM Operator requires access to the following APIs:
Name | Title |
---|---|
apigee.googleapis.com |
Apigee API |
compute.googleapis.com |
Compute Engine API |
networkservices.googleapis.com |
Network Services API |
container.googleapis.com |
Google Kubernetes Engine API |
Use the following command to confirm that the required APIs are enabled:
gcloud services list --project=${PROJECT_ID}
If you don't see the required APIs listed in the command output, enable them:
gcloud services enable apigee.googleapis.com --project=${PROJECT_ID}
gcloud services enable compute.googleapis.com --project=${PROJECT_ID}
gcloud services enable networkservices.googleapis.com --project=${PROJECT_ID}
gcloud services enable container.googleapis.com --project=${PROJECT_ID}
Retrieve and configure credentials
Retrieve your cluster credentials and create a service account to connect to Google Cloud services:
Get cluster credentials using the following command:
gcloud container clusters get-credentials ${CLUSTER_NAME} --location=${REGION} --project=${PROJECT_ID}
These credentials are used to communicate with the GKE cluster created in the prerequisite steps.
- Set up Service Account Credentials to connect to Google Cloud services:
gcloud iam service-accounts create apigee-apim-gsa
- Grant the required roles and permissions to the service account you created using the following commands:
- Apigee Admin role: Required to create and manage Apigee resources.
gcloud projects add-iam-policy-binding ${PROJECT_ID} \ --member "serviceAccount:apigee-apim-gsa@${PROJECT_ID}.iam.gserviceaccount.com" \ --role "roles/apigee.admin"
- Service extension admin role: Required to create and manage service extensions.
gcloud projects add-iam-policy-binding ${PROJECT_ID} \ --member "serviceAccount:apigee-apim-gsa@${PROJECT_ID}.iam.gserviceaccount.com" \ --role "roles/networkservices.serviceExtensionsAdmin"
- Networking admin role: Required to manage access to Apigee using service extensions.
gcloud projects add-iam-policy-binding ${PROJECT_ID} \ --member "serviceAccount:apigee-apim-gsa@${PROJECT_ID}.iam.gserviceaccount.com" \ --role "roles/compute.networkAdmin"
- Load balancer admin role: Required to manage access between network endpoint groups (NEGs)
and backend services.
gcloud projects add-iam-policy-binding ${PROJECT_ID} \ --member "serviceAccount:apigee-apim-gsa@${PROJECT_ID}.iam.gserviceaccount.com" \ --role "roles/compute.loadBalancerAdmin"
gcloud projects add-iam-policy-binding ${PROJECT_ID} \ --member "serviceAccount:apigee-apim-gsa@${PROJECT_ID}.iam.gserviceaccount.com" \ --role "roles/iam.workloadIdentityUser"
- Apigee Admin role: Required to create and manage Apigee resources.
Install Custom Resource Definitions (CRDs) and APIM Operator
Install the Kubernetes custom resources definitions (CRDs) and APIM Operator:
- Create a namespace for the APIM Operator:
kubectl create ns apim
- Install the APIM Operator custom resource definitions (CRDs):
helm install apigee-apim-crds oci://us-docker.pkg.dev/apigee-release/apigee-k8s-tooling-helm-charts/apigee-apim-operator-crds --version 0.6.0 -n apim --atomic
- Install the APIM Operator:
helm install apigee-apim-operator oci://us-docker.pkg.dev/apigee-release/apigee-k8s-tooling-helm-charts/apigee-apim-operator-helm --version 0.6.0 --set project_id=${PROJECT_ID} --set serviceAccount=apigee-apim-gsa@${PROJECT_ID}.iam.gserviceaccount.com --set apigeeOrg=${PROJECT_ID} --set generateEnv=TRUE --set apigeeMgmtUrl="https://apigee.googleapis.com" -n apim --atomic
Use the following command to confirm that the installation completed successfully:
helm list -n apim
The output should look similar to the following:
NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION apigee-apim-crds apim 1 2025-02-01 00:17:03.399810627 +0000 UTC deployed apigee-apim-operator-crds-0.6.0 0.6.0 apigee-apim-operator apim 1 2025-02-01 00:15:00.362829981 +0000 UTC deployed apigee-apim-operator-helm-0.6.0 0.6.0
The helm
installation creates a required Kubernetes service account (KSA) named
apim-ksa
in the apim
namespace. The KSA contains the annotation required
to associate with the workload identity created in the next step.
To confirm that the KSA was created with the required annotation, run the following command:
kubectl describe serviceaccounts apim-ksa -n apim
The output should appear similar to the following:
Name: apim-ksa Namespace: apim ... Annotations: iam.gke.io/gcp-service-account: apigee-apim-gsa@my-project-id.iam.gserviceaccount.com
Create a workload identity
To create the workload identity used by the APIM Operator to access required Apigee
and Service Networking resources, bind the KSA with the Google service account you created
in Retrieve and configure credentials and assign the workloadIdentityUser
role:
gcloud iam service-accounts add-iam-policy-binding apigee-apim-gsa@${PROJECT_ID}.iam.gserviceaccount.com --role roles/iam.workloadIdentityUser --member "serviceAccount:${PROJECT_ID}.svc.id.goog[apim/apim-ksa]"
Optional: Create an Apigee environment
This step is optional. If you don't want to create an Apigee environment, the APIM Operator will create the environment.
The new environment's name will have the prefix: apim-enabled-dep-env
.
Create an Apigee environment:
- Set the
TOKEN
required for thecurl
command:export TOKEN=$(gcloud auth print-access-token)
- Create the environment using one of the following commands:
- For Subscription 2021 organizations:
curl -X POST "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/environments" -H \ "Authorization: Bearer $TOKEN" -H "content-type:application/json" \ -d '{ "name": "ENV_NAME", "properties": { "apigee-service-extension-enabled":"true" } }'
Where
ENV_NAME
is the name of the environment to create. - For Subscription 2024 and Pay-as-you-go orgs:
curl -i -X POST -H "Authorization: Bearer $TOKEN" "https://apigee.googleapis.com/v1/organizations/$APIGEE_ORG/environments" -H "Content-Type:application/json" -d '{ "name": ENV_NAME, "displayName": ENV_NAME, "state": "ACTIVE", "deploymentType": "PROXY", "apiProxyType": "PROGRAMMABLE", "type" : ENV_TYPE, "properties": { "property": [ { "name": "apigee-service-extension-enabled", "value": "true" } ] } }'
Where:
ENV_NAME
is the name of the environment to create.ENV_TYPE
is the type of the environment to create. For example,INTERMEDIATE
orCOMPREHENSIVE
.
- For Subscription 2021 organizations:
Troubleshoot
If you encounter issues when installing APIM Operator, see Troubleshoot the APIM Operator for solutions to common errors.