Install the Apigee Operator for Kubernetes

This page applies toApigee, but not toApigee hybrid.

View Apigee Edge documentation.

This page describes the steps to install and configure the Apigee Operator for Kubernetes. To learn more about the benefits of using the Apigee Operator for Kubernetes, see Apigee Operator for Kubernetes overview.

Before you begin

Before you install the Apigee Operator for Kubernetes, ensure that you have the required roles and permissions to complete the steps and that you have completed the prerequisite tasks described inApigee Operator for Kubernetes: Before you begin.

Required roles

To get the permissions that you need to install the Apigee Operator for Kubernetes, ask your administrator to grant you the following IAM roles on the organization:

For more information about granting roles, seeManage access to projects, folders, and organizations.

You might also be able to get the required permissions throughcustom roles or otherpredefined roles.

Install and configure the Apigee Operator for Kubernetes

The following sections describe the steps to install and configure the Apigee Operator for Kubernetes:

  1. Set environment variables.
  2. Enable the required APIs.
  3. Retrieve and configure credentials.
  4. Install the Apigee Operator for Kubernetes.
  5. Create a workload identity.
  6. Create an Apigee environment.
  7. Verify GKE Gateway setup.

Set environment variables

In the Google Cloud project that contains your Apigee instance, use the following command to set environment variables:

exportPROJECT_ID=PROJECT_IDexportCLUSTER_NAME=CLUSTER_NAMEexportREGION=REGIONexportAPIGEE_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

Apigee Operator for Kubernetes requires access to the following APIs:

NameTitle
apigee.googleapis.comApigee API
compute.googleapis.comCompute Engine API
networkservices.googleapis.comNetwork Services API
container.googleapis.comGoogle Kubernetes Engine API

Use the following command to confirm that the required APIs are enabled:

gcloudserviceslist--project=$PROJECT_ID

If you don't see the required APIs listed in the command output, enable them:

gcloudservicesenableapigee.googleapis.com--project=$PROJECT_IDgcloudservicesenablecompute.googleapis.com--project=$PROJECT_IDgcloudservicesenablenetworkservices.googleapis.com--project=$PROJECT_IDgcloudservicesenablecontainer.googleapis.com--project=$PROJECT_ID

Retrieve and configure credentials

Retrieve your cluster credentials and create a service account to connect to Google Cloud services:

  1. Get cluster credentials using the following command:

    gcloudcontainerclustersget-credentials$CLUSTER_NAME--location=$REGION--project=$PROJECT_ID

    These credentials communicate with the GKE cluster created in the prerequisite steps.

  2. Set up Service Account Credentials to connect to Google Cloud services:
    gcloudiamservice-accountscreateapigee-apim-gsa
  3. 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.
      gcloudprojectsadd-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.
      gcloudprojectsadd-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.
      gcloudprojectsadd-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.
      gcloudprojectsadd-iam-policy-binding$PROJECT_ID\--member"serviceAccount:apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com"\--role"roles/compute.loadBalancerAdmin"
      gcloudprojectsadd-iam-policy-binding$PROJECT_ID\--member"serviceAccount:apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com"\--role"roles/iam.workloadIdentityUser"

Create a workload identity

Thehelm installation of the Apigee Operator for Kubernetes in the next step creates a required Kubernetes service account (KSA) namedapim-ksa in theapim namespace. When created, the KSA contains the annotation required to associate with a workload identity used by the Apigee Operator for Kubernetes to access required Apigee and Service Networking resources.

To create the workload identity, use the following command:

gcloudiamservice-accountsadd-iam-policy-bindingapigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com--roleroles/iam.workloadIdentityUser--member"serviceAccount:$PROJECT_ID.svc.id.goog[apim/apim-ksa]"

This command binds the KSA with the Google service account you created inRetrieve and configure credentials and assigns theworkloadIdentityUser role.

It may take a few minutes, potentially 7 minutes or longer, for the workload identity changes to propagate through the system.

To confirm that the workload identity is created, use the following commands:

gcloudconfigsetproject$PROJECT_ID
kubectlrun--rm-it--imagegoogle/cloud-sdk:slim\--namespaceapimworkload-identity-test\--overrides='{ "spec": { "serviceAccountName": "apim-ksa" } }'\--gcloudauthlist

The output should look similar to the following:

Credentialed Accounts  ACTIVE  ACCOUNT  *       GSA@$PROJECT_ID.iam.gserviceaccount.com

Install Custom Resource Definitions (CRDs) and Apigee Operator for Kubernetes

Install theKubernetes Custom Resource Definitions (CRDs) and Apigee Operator for Kubernetes:

  1. Create a namespace for the Apigee Operator for Kubernetes:
    kubectlcreatensapim
  2. Install the Apigee Operator for Kubernetes CRDs:
    helminstallapigee-apim-crds-napim\oci://us-docker.pkg.dev/apigee-release/apigee-k8s-tooling-helm-charts/apigee-apim-operator-crds\--version1.1.1\--atomic
  3. Install the Apigee Operator for Kubernetes:
    helminstallapigee-apim-operator-napim\oci://us-docker.pkg.dev/apigee-release/apigee-k8s-tooling-helm-charts/apigee-apim-operator-helm\--version1.1.1\--setprojectId=$PROJECT_ID\--setserviceAccount=apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com\--setapigeeOrg=$PROJECT_ID\--setgenerateEnv=ENV_GENERATION_MODE\--atomic

    4. ReplaceENV_GENERATION_MODE withTRUE if you want the operator to create a new Apigee environment when the Apigee Operator for Kubernetes is installed. SetENV_GENERATION_MODE toFALSE if you want to create the environment manually after the operator is installed. SeeCreate an Apigee environment for more information.

  4. Confirm that the installation completed successfully:
    helmlist-napim

    The output should look similar to the following:

    NAME                NAMESPACEREVISIONUPDATED                                STATUS  CHART                          APP VERSIONapigee-apim-crds    apim     1       2025-02-01 00:17:03.399810627 +0000 UTCdeployedapigee-apim-operator-crds-1.1.11.1.1apigee-apim-operatorapim     1       2025-02-01 00:15:00.362829981 +0000 UTCdeployedapigee-apim-operator-helm-1.1.11.1.1

  5. Confirm that the KSA was created with the required annotation:
    kubectldescribeserviceaccountsapim-ksa-napim

    The output should look similar to the following:

    Name:apim-ksaNamespace:apim...Annotations:iam.gke.io/gcp-service-account:apigee-apim-gsa@my-project-id.iam.gserviceaccount.com
  6. Confirm that the APIM operator is up and running in the cluster's pods:
    kubectlgetpods-napim

    The output should look similar to the following:

    NAME                                    READY   STATUS    RESTARTS     AGEapigee-apim-operator-8559d4994b-h55fl   1/1     Running   0            8m34s

    If theSTATUS is notRunning, orREADY does not display1/1, seeTroubleshoot the Apigee Operator for Kubernetes to troubleshoot the installation.

Create an Apigee environment

If you installed the Apigee Operator for Kubernetes usinggenerateEnv=TRUE in the previous step, the operator creates a new Apigee environment when theAPIM Extension policy is created and applied. The new environment's name has the prefix:apim-enabled-dep-env.

If you installed the Apigee Operator for Kubernetes withgenerateEnv=FALSE, you must create a new Apigee environment:

  1. Set theTOKEN required for thecurl command:
    exportTOKEN=$(gcloudauthprint-access-token)
  2. Create the environment using one of the following commands:
    • For Subscription 2021 organizations:
      curl-XPOST"https://apigee.googleapis.com/v1/organizations/$APIGEE_ORG/environments"-H\"Authorization: Bearer$TOKEN"-H"content-type:application/json"\-d'{      "name": "ENV_NAME",      "displayName": "ENV_NAME",      "state": "ACTIVE",      "deploymentType": "PROXY",      "apiProxyType": "PROGRAMMABLE",      "properties": {        "property": [          {            "name": "apigee-service-extension-enabled",            "value": "true"          }        ]      }  }'

      WhereENV_NAME is the name of the environment to create.

    • For Subscription 2024 and Pay-as-you-go orgs:
      curl-i-XPOST-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" : "COMPREHENSIVE",  "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.

      Note: The environment created in this step, or created by the Apigee Operator for Kubernetes, is either anIntermediate or Comprehensive environment, to support the use ofExtensible proxies. This feature cannot be used with Base environments.

    To check that the environment created successfully:

    curl-i-H"Authorization: Bearer$TOKEN"\"https://apigee.googleapis.com/v1/organizations/$APIGEE_ORG/environments"

  3. Attach the environment to your Apigee instance:
    curl-i-XPOST-H"Authorization: Bearer$TOKEN"\"https://apigee.googleapis.com/v1/organizations/$APIGEE_ORG/instances/INSTANCE_NAME/attachments"\-H"Content-Type:application/json"-d'{"environment": "ENV_NAME"}'

    Where:

    • INSTANCE_NAME is the name of your Apigee instance.
    • ENV_NAME is the name of the environment you created in the previous step.

    To check the status of the environment attachment operation:

    curl-XGET-H"Authorization: Bearer$TOKEN"\"https://apigee.googleapis.com/v1/organizations/$APIGEE_ORG/operations/OPERATION_ID"

    WhereOPERATION_ID is the ID of the environment attachment operation.

Troubleshoot

If you encounter issues when installing Apigee Operator for Kubernetes, seeTroubleshoot the Apigee Operator for Kubernetes for solutions to common errors.

What's next

Create a traffic service extension using theAPIMExtensionPolicy or theApigeeBackendService:

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-19 UTC.