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.

Preview — Apigee APIM Operator for Kubernetes

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

En esta página, se describen los pasos necesarios para instalar y configurar el operador de APIM de Apigee para Kubernetes (versión preliminar). Para obtener más información sobre los beneficios de usar el operador de APIM, consulta la 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 obligatorios

Para obtener los permisos que necesitas para instalar el operador de APIM, pide a tu administrador que te otorgue los siguientes roles de IAM en la organización:

• Crear y administrar 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 mediante 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 que se haya configurado la puerta de enlace de GKE.

Configure las variables de entorno

En el Google Cloud proyecto 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 de manera correcta, ejecuta el siguiente comando:

echo $PROJECT_ID $CLUSTER_NAME $REGION $APIGEE_ORG

Habilita las API obligatorias

APIM Operator 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 servicios de red
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 la salida 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 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 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. Otorga los roles y permisos necesarios a la cuenta de servicio que creaste con los siguientes comandos:
   • Rol de administrador de Apigee: Obligatorio 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: Obligatorio 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: Obligatorio 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: Obligatorio 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 una 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, la KSA contiene la anotación necesaria para asociarse con una identidad de carga de trabajo que usa el operador de APIM para acceder a los recursos necesarios de Apigee y de Herramientas de redes de servicios.

Para crear la identidad de la 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 Google cuenta de servicio que creaste en Cómo recuperar y configurar credenciales y le asigna el rol workloadIdentityUser.

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

Para confirmar que se creó la identidad de la 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\
  -- 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 oci://us-docker.pkg.dev/apigee-release/apigee-k8s-tooling-helm-charts/apigee-apim-operator-crds --version 0.6.0 -n apim --atomic

3. Instala el operador de APIM:

   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

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

5. Confirma que la KSA se haya creado 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 la instalación.

Crea un entorno de Apigee

Si instalaste el operador de APIM con generateEnv=TRUE en el paso anterior, el operador crea un entorno de Apigee nuevo cuando se crea y aplica la política de extensión de APIM. El nombre del entorno nuevo 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 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 de Subscription 2021:

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

     En este comando, ENV_NAME es el nombre del entorno que se creará.

   • Para las organizaciones de suscripción de 2024 y 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" : ENV_TYPE,
       "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 que se crea en este paso, o que crea 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.
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.

Solucionar problemas

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

¿Qué sigue?

• Usa políticas de Apigee con el operador de APIM.
• Agrega políticas de Apigee a la puerta de enlace de GKE.