Instala el operador de APIM 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 APIM de Apigee para Kubernetes. Para obtener más información sobre los beneficios de usar el operador de APIM, consulta Descripción general del operador de APIM de Apigee para Kubernetes.

Antes de comenzar

Antes de comenzar a instalar el operador de APIM, asegúrate de tener los roles y permisos necesarios para completar los pasos y de haber completado las tareas de requisitos previos que se describen en Operador de APIM: Antes de comenzar.

Roles requeridos

Para obtener los permisos que necesitas para instalar APIM Operator, pídele a tu administrador que te otorgue los siguientes roles de IAM en la organización:

• Crea y administra el clúster de GKE: Administrador de contenedores (roles/container.admin)
• Crear y administrar cuentas de servicio: Administrador de cuentas de servicio (roles/iam.serviceAccountAdmin)
• Crear y administrar extensiones del servicio: Administrador de extensiones del servicio (roles/networkservices.serviceExtensionsAdmin)
• Crear y administrar grupos de extremos de red (NEG): Administrador de instancias de Compute (roles/compute.instanceAdmin)
• Crear y administrar servicios de backend: Administrador de balanceador de cargas de Compute (roles/compute.loadBalancerAdmin)
• Crear y administrar recursos de Apigee: Administrador de Apigee (roles/apigee.admin)

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Instala y configura el operador de APIM

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

1. Configura las variables de entorno.
2. Habilita las API necesarias.
3. Recupera y configura las credenciales.
4. Instala el operador de APIM.
5. Crea una identidad para cargas de trabajo.
6. Crea un entorno de Apigee.
7. Verifica la configuración de GKE Gateway.

Configure las variables de entorno

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

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

Aquí:

• PROJECT_ID es el ID del proyecto con 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 se establece con el mismo valor que PROJECT_ID.

Para confirmar que las variables de entorno estén configuradas correctamente, ejecuta el siguiente comando:

echo $PROJECT_ID $CLUSTER_NAME $REGION $APIGEE_ORG

Habilita las API obligatorias

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 de Network Services
container.googleapis.com	API de Google Kubernetes Engine

Usa el siguiente comando para confirmar que las APIs requeridas estén habilitadas:

gcloud services list --project=$PROJECT_ID

Si no ves las APIs requeridas 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

Recupera y configura credenciales

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

1. Obtén 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 requisitos previos.

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

   gcloud iam service-accounts create apigee-apim-gsa

3. Otorga los roles y permisos necesarios a la cuenta de servicio que creaste con los siguientes comandos:
   • Rol de administrador de Apigee: Se requiere para crear y administrar 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 requiere para crear y administrar 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 requiere para administrar el acceso a Apigee con 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 cargas: Se requiere para administrar el acceso entre los grupos de extremos de red (NEG) y los 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"

Crea una identidad para cargas 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, la KSA contiene la anotación necesaria para asociarse con una identidad de cargas de trabajo que usa el operador de APIM para acceder a los recursos necesarios de Apigee y de 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 la KSA con la cuenta de servicio Google que creaste en Cómo recuperar y configurar credenciales y asigna el rol workloadIdentityUser.

Es posible que los cambios de la identidad de la carga de trabajo tarden unos minutos, tal vez 7 o más, en propagarse por el sistema.

Para confirmar que se creó 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

El resultado debería ser similar al siguiente:

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

Instala las definiciones de recursos personalizados (CRD) y el operador de APIM

Instala las definiciones de recursos personalizados (CRD) 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 (CRD) 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 haya completado correctamente:

   helm list -n apim

   El resultado debería ser similar al 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 la KSA se creó con la anotación requerida:

   kubectl describe serviceaccounts apim-ksa -n apim

   El resultado debería ser similar al 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

   El resultado debería ser similar al siguiente:

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

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

Crea un entorno de Apigee

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

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

1. Establece el TOKEN requerido para el comando curl:

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

2. Crea el entorno con uno de los siguientes comandos:
   • Para las organizaciones de suscripción de 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"
               }
             ]
           }
       }'

     Aquí, ENV_NAME es el nombre del entorno que se creará.

   • Para las organizaciones de suscripción 2024 y de pago por uso, haz lo siguiente:

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

     Aquí:

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

   Para verificar que el entorno se creó correctamente, haz lo siguiente:

   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"}'

   Aquí:

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

   Para verificar el estado de la operación de adjuntar el entorno, haz lo siguiente:

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

   Aquí, OPERATION_ID es el ID de la operación de adjuntar el entorno.

Solucionar problemas

Si tienes problemas para instalar APIM Operator, consulta Soluciona problemas de APIM Operator para encontrar soluciones a errores comunes.

¿Qué sigue?

• Usa políticas de Apigee con el operador de APIM.
• Agrega políticas de Apigee a GKE Gateway.