Instalar el operador de gestión de APIs de Apigee para Kubernetes

Esta página se aplica a Apigee, pero no a Apigee Hybrid.

Consulta la documentación de Apigee Edge.

En esta página se describen los pasos necesarios para instalar y configurar el operador de gestión de APIs de Apigee para Kubernetes. Para obtener más información sobre las ventajas de usar el operador APIM, consulta el resumen del operador APIM de Apigee para Kubernetes.

Antes de empezar

Antes de empezar a instalar el operador de APIM, asegúrate de que tienes los roles y permisos necesarios para completar los pasos y de que has completado las tareas previas descritas en Operador de APIM: antes de empezar.

Roles obligatorios

Para obtener los permisos que necesitas para instalar el operador de APIM, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos en la organización:

• Crea y gestiona el clúster de GKE: Administrador de contenedores (roles/container.admin)
• Crear y gestionar cuentas de servicio: Administrador de cuentas de servicio (roles/iam.serviceAccountAdmin)
• Crear y gestionar extensiones de servicio: Administrador de extensiones de servicio (roles/networkservices.serviceExtensionsAdmin)
• Crear y gestionar grupos de puntos finales de red (NEGs): Administrador de instancias de Compute (roles/compute.instanceAdmin)
• Crear y gestionar servicios backend: Administrador de balanceadores de carga de Compute (roles/compute.loadBalancerAdmin)
• Crear y gestionar recursos de Apigee: Administrador de Apigee (roles/apigee.admin)

Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

Instalar y configurar el operador de APIM

En las siguientes secciones se describen los pasos necesarios para instalar y configurar el operador de APIM:

1. Define variables de entorno.
2. Habilita las APIs necesarias.
3. Recuperar y configurar credenciales.
4. Instala el operador de APIM.
5. Crea una identidad de carga de trabajo.
6. Crea un entorno de Apigee.
7. Verifica la configuración de GKE Gateway.

Establece variables de entorno:

En el Google Cloud proyecto que contiene tu instancia de Apigee, usa el siguiente comando para definir las variables de entorno:

export PROJECT_ID=PROJECT_ID
export CLUSTER_NAME=CLUSTER_NAME
export REGION=REGION
export APIGEE_ORG=APIGEE_ORG

Donde:

• PROJECT_ID es el ID del proyecto que contiene tu instancia de Apigee.
• CLUSTER_NAME es el nombre de tu clúster de GKE.
• REGION es la región de tu clúster de GKE.
• APIGEE_ORG tiene el mismo valor que PROJECT_ID.

Para confirmar que las variables de entorno se han definido correctamente, ejecuta el siguiente comando:

echo $PROJECT_ID $CLUSTER_NAME $REGION $APIGEE_ORG

Habilitar las APIs necesarias

El operador de APIM requiere acceso a las siguientes APIs:

Nombre	Título
apigee.googleapis.com	API de Apigee
compute.googleapis.com	API de Compute Engine
networkservices.googleapis.com	API Network Services
container.googleapis.com	API de Google Kubernetes Engine

Usa el siguiente comando para confirmar que las APIs necesarias están habilitadas:

gcloud services list --project=$PROJECT_ID

Si no ves las APIs necesarias en el resultado del comando, habilítalas:

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

Recuperar y configurar credenciales

Recupera las credenciales de tu clúster y crea una cuenta de servicio para conectarte a los servicios de Google Cloud :

1. Obtén las credenciales del clúster con el siguiente comando:

   gcloud container clusters get-credentials $CLUSTER_NAME --location=$REGION --project=$PROJECT_ID

   Estas credenciales se usan para comunicarse con el clúster de GKE creado en los pasos de los requisitos previos.

2. Configura las credenciales de la cuenta de servicio para conectarte a los Google Cloud servicios:

   gcloud iam service-accounts create apigee-apim-gsa

3. Concede los roles y permisos necesarios a la cuenta de servicio que has creado con los siguientes comandos:
   • Rol de administrador de Apigee: se necesita para crear y gestionar recursos de Apigee.

     gcloud projects add-iam-policy-binding $PROJECT_ID \
         --member "serviceAccount:apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com" \
         --role "roles/apigee.admin"

   • Rol de administrador de extensiones de servicio: se necesita para crear y gestionar extensiones de servicio.

     gcloud projects add-iam-policy-binding $PROJECT_ID \
         --member "serviceAccount:apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com" \
         --role "roles/networkservices.serviceExtensionsAdmin"

   • Rol de administrador de redes: se necesita para gestionar el acceso a Apigee mediante extensiones de servicio.

     gcloud projects add-iam-policy-binding $PROJECT_ID \
         --member "serviceAccount:apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com" \
         --role "roles/compute.networkAdmin"

   • Rol de administrador del balanceador de carga: se necesita para gestionar el acceso entre grupos de puntos finales de red (NEGs) y servicios de backend.

     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"

Crear una identidad de carga de trabajo

La instalación de helm del operador de APIM en el siguiente paso crea una cuenta de servicio de Kubernetes (KSA) obligatoria llamada apim-ksa en el espacio de nombres apim. Cuando se crea, el KSA contiene la anotación necesaria para asociarse a una identidad de carga de trabajo que usa el operador de APIM para acceder a los recursos necesarios de Apigee y Service Networking.

Para crear la identidad de carga de trabajo, usa el siguiente comando:

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]"

Este comando vincula el KSA con la Google cuenta de servicio que has creado en Recuperar y configurar credenciales y asigna el rol workloadIdentityUser.

Los cambios en la identidad de carga de trabajo pueden tardar unos minutos en propagarse por el sistema (hasta 7 minutos o más).

Para confirmar que se ha creado la identidad de carga de trabajo, usa los siguientes comandos:

gcloud config set project $PROJECT_ID

kubectl run --rm -it --image google/cloud-sdk:slim \
  --namespace apim workload-identity-test \
  --overrides='{ "spec": { "serviceAccountName": "apim-ksa" } }'  \
  -- gcloud auth list

La salida debería ser similar a la siguiente:

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

Instalar definiciones de recursos personalizadas (CRDs) y el operador de APIM

Instala las definiciones de recursos personalizados (CRDs) de Kubernetes y el operador de APIM:

1. Crea un espacio de nombres para el operador de APIM:

   kubectl create ns apim

2. Instala las definiciones de recursos personalizados (CRDs) del operador de APIM:

   helm install apigee-apim-crds -n apim \
     oci://us-docker.pkg.dev/apigee-release/apigee-k8s-tooling-helm-charts/apigee-apim-operator-crds \
     --version 1.0.0 \
     --atomic

3. Instala el operador de APIM:

   helm install apigee-apim-operator -n apim \
     oci://us-docker.pkg.dev/apigee-release/apigee-k8s-tooling-helm-charts/apigee-apim-operator-helm \
     --version 1.0.0 \
     --set projectId=$PROJECT_ID \
     --set serviceAccount=apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com \
     --set apigeeOrg=$PROJECT_ID \
     --set generateEnv=TRUE \
     --atomic

4. Confirma que la instalación se ha completado correctamente:

   helm list -n apim

   La salida debería ser similar a la siguiente:

   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-1.0.0	1.0.0
   apigee-apim-operator	apim     	1       	2025-02-01 00:15:00.362829981 +0000 UTC	deployed	apigee-apim-operator-helm-1.0.0	1.0.0   

5. Confirma que el KSA se ha creado con la anotación necesaria:

   kubectl describe serviceaccounts apim-ksa -n apim

   La salida debería ser similar a la siguiente:

   Name:                apim-ksa
   Namespace:           apim
   ...
   Annotations:         iam.gke.io/gcp-service-account: [e-mail]

6. Confirma que el operador de APIM está en funcionamiento en los pods del clúster:

   kubectl get pods -n apim

   La salida debería ser similar a la siguiente:

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

   Si el valor de STATUS no es Running o READY no muestra 1/1, consulta Solucionar problemas del operador de APIM para solucionar problemas de instalación.

Crear un entorno de Apigee

Si has instalado el operador de APIM con generateEnv=TRUE en el paso anterior, el operador crea un nuevo entorno de Apigee cuando se crea y se aplica la política de extensión de APIM. El nombre del nuevo entorno tendrá el prefijo apim-enabled-dep-env.

Si has instalado el operador de APIM con generateEnv=FALSE, debes crear un entorno de Apigee:

1. Define el TOKEN necesario para el comando curl:

   export TOKEN=$(gcloud auth print-access-token)

2. Crea el entorno con uno de los siguientes comandos:
   • Para las organizaciones con una suscripción del 2021:

     curl -X POST "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"
               }
             ]
           }
       }'

     Donde ENV_NAME es el nombre del entorno que se va a crear.

   • En el caso de las organizaciones con suscripción del 2024 y las de pago por uso:

     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" : "COMPREHENSIVE",
       "properties": {
         "property": [
           {
             "name": "apigee-service-extension-enabled",
             "value": "true"
           }
         ]
       }
     }'

     Donde:

     • ENV_NAME es el nombre del entorno que se va a crear.
     • ENV_TYPE es el tipo de entorno que se va a crear. Por ejemplo, INTERMEDIATE o COMPREHENSIVE.
     Nota: El entorno creado en este paso o por el operador de APIM es un entorno intermedio o completo para admitir el uso de proxies extensibles. Esta función no se puede usar con entornos base.

   Para comprobar que el entorno se ha creado correctamente, sigue estos pasos:

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

3. Adjunta el entorno a tu instancia de Apigee:

   curl -i -X POST -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"}'

   Donde:

   • INSTANCE_NAME es el nombre de tu instancia de Apigee.
   • ENV_NAME es el nombre del entorno que has creado en el paso anterior.

   Para comprobar el estado de la operación de adjuntar el entorno, sigue estos pasos:

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

   Donde OPERATION_ID es el ID de la operación de adjunto del entorno.

Solucionar problemas

Si tienes problemas al instalar el operador APIM, consulta el artículo Solucionar problemas del operador APIM para encontrar soluciones a errores habituales.

Siguientes pasos

• Usa políticas de Apigee con el operador de APIM.
• Añadir políticas de Apigee a GKE Gateway