Solucionar problemas del 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 describe cómo solucionar problemas del operador de gestión de APIs de Apigee para Kubernetes. Hay varias herramientas disponibles para resolver cualquier problema que puedas tener. En esta página se describe cómo comprobar el estado de los recursos personalizados, usar el Explorador de registros y solucionar problemas con el tráfico del tiempo de ejecución de Apigee.

Comprobar el estado de un recurso personalizado

Cada recurso personalizado que se usa en el operador de gestión de APIs de Apigee para Kubernetes contiene un objeto de estado con dos campos:

  • STATE describe el estado del recurso. Entre los valores se incluyen running y created.
  • ERRORMESSAGE: si la operación del recurso falla, el campo del mensaje de error se rellena con un mensaje explicativo.

Cuando se aplica un archivo de recurso personalizado yaml al clúster, Kubernetes hace los cambios correspondientes en la infraestructura subyacente. Al comprobar el objeto de estado del recurso personalizado, se puede obtener información sobre el estado del recurso y mostrar los errores resultantes si fallan las operaciones de la infraestructura subyacente.

Puedes comprobar el estado del recurso personalizado con el siguiente comando: 

kubectl -n NAMESPACE get CUSTOM_RESOURCE_KIND CUSTOM_RESOURCE_NAME

Donde:

  • NAMESPACE: el espacio de nombres en el que se implementa el recurso personalizado.
  • CUSTOM_RESOURCE_KIND: el tipo del recurso personalizado.
  • CUSTOM_RESOURCE_NAME: nombre del recurso personalizado.

Por ejemplo, el siguiente comando comprueba el estado del recurso personalizado APIMExtensionPolicy llamado apim-extension-policy en el espacio de nombres apim: 

kubectl -n apim get APIMExtensionPolicy apim-extension-policy-1

El resultado debería ser similar al siguiente:

NAME                      STATE                  ERRORMESSAGE
apim-extension-policy     Create_Update_Failed   Permission denied

Ver registros

En esta sección se describe cómo usar los registros para solucionar problemas del recurso de puerta de enlace de Google Kubernetes Engine (GKE) y del recurso de operador de APIM.

Registros de GKE Gateway

Cuando aplicas la APIMExtensionPolicy, la GKE Gateway que has creado en tu clúster se configura con una extensión de tráfico. La extensión usa el procesamiento externo de Kubernetes (ext-proc) para llamar al tiempo de ejecución de Apigee y procesar las políticas. Los registros relacionados con el tráfico de ext-proc pueden ser útiles para solucionar problemas.

Ver los registros de las peticiones ext-proc

Para ver los registros del tráfico de ext-proc, sigue estos pasos:

  1. Obtén el ID del servicio de backend creado para el tiempo de ejecución de Apigee: 
    kubectl get gateways.gateway.networking.k8s.io GATEWAY_NAME
  -o=jsonpath="{.metadata.annotations.networking\.gke\.io/backend-services}"

    Donde GATEWAY_NAME es el nombre de la pasarela de GKE.

    El servicio de backend contendrá apigee-service-extension-backend-service en el ID.

  2. Sigue los pasos que se indican en Habilitar el registro en un servicio de backend para habilitar el registro.
  3. Para ver los registros en la Google Cloud consola, ve a la página Explorador de registros:

    Explorador de registros

  4. Consulta Mensajes de registro de un servicio backend para ver la información de las entradas de registro de llamadas disponibles, incluida la estructura de la carga útil JSON de la entrada de registro del balanceador de carga service_extension_info. Puedes usar el campo Buscar de Explorador de registros para filtrar la información pertinente.

    En el siguiente ejemplo se muestra una entrada de registro que puede ver si se produce un error en una llamada ext-proc: 

    {
  "insertId": "s14dmrf10g6hi",
  "jsonPayload": {
    "serviceExtensionInfo": [
      {
        "extension": "ext11",
        "perProcessingRequestInfo": [
          {
            "eventType": "REQUEST_HEADERS",
            "latency": "0.001130s"
          }
        ],
        "backendTargetType": "BACKEND_SERVICE",
        "grpcStatus": "ABORTED",
        "backendTargetName": "gkegw1-2y13-apigee-service-extension-backend-service-443-yhsnrauznpwh",
        "chain": "chain1",
        "resource": "projects/$PROJECT_ID/locations/us-west1/lbTrafficExtensions/apim-extension"
      }
    ],
    "backendTargetProjectNumber": "projects/763484362408",
    "@type": "type.googleapis.com/google.cloud.loadbalancing.type.LoadBalancerLogEntry"
  },
  "httpRequest": {
    ...
  },
  "resource": {
    "type": "internal_http_lb_rule",
    "labels": {
      ...
    }
  },
  "timestamp": "2024-04-01T20:15:15.182137Z",
  "severity": "INFO",
  "logName": "projects/$PROJECT_ID/logs/loadbalancing.googleapis.com%2Frequests",
  "receiveTimestamp": "2024-04-01T20:15:18.209706689Z"
}

    Ten en cuenta que el campo grpcStatus muestra ABORTED.

Registros del operador de APIM

El operador de APIM es un operador de Kubernetes que procesa eventos de recursos personalizados de APIM (como crear, leer, actualizar y eliminar) y traduce esos eventos a la configuración de Apigee adecuada.

Para ver los registros del operador de APIM, sigue estos pasos:

  1. Para ver los registros en la Google Cloud consola, ve a la página Explorador de registros:

    Explorador de registros

  2. En el panel de consultas, introduce una consulta similar a la siguiente: 
    resource.type="k8s_container"
resource.labels.namespace_name="apim"
labels.k8s-pod/app="apigee-apim-operator" severity>=DEFAULT
  3. Haz clic en Realizar una consulta.
  4. Las entradas de registro filtradas se muestran en el panel Resultados de la consulta.
  5. Apunta cualquier problema que tengas al crear, actualizar o eliminar servicios APIMExtensionPolicy in Google Cloud networks o Productos de API en los planos de gestión de Apigee.

    Un ejemplo de error sería similar al siguiente: 

    ApimExtensionPolicy creation status400
response body:{
  "error": {
    "code": 400,
    "message": "The request was invalid: backend service https://www.googleapis.com/compute/v1/projects/... must use HTTP/2 as the protocol",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "lb_traffic_extension.extension_chains[0].extensions[0].service"
          }
        ]
      },
      {
        "@type": "type.googleapis.com/google.rpc.RequestInfo",
        "requestId": "d4e6f00ab5d367ec"
      }
    ]
  }
}

Solucionar errores de acceso 403 en el operador de APIM

Si detecta errores con el código de estado 403 que indican problemas de acceso, confirme lo siguiente:

  • Tu clúster de GKE tiene habilitada la federación de identidades de cargas de trabajo. La federación de identidades de cargas de trabajo está habilitada de forma predeterminada en los clústeres de GKE creados con el modo Autopilot. Si has creado un clúster con el modo estándar, habilita la federación de identidades de carga de trabajo tal como se describe en el artículo Habilitar la federación de identidades de carga de trabajo para GKE.
  • La cuenta de servicio de Kubernetes (apim-ksa) está anotada correctamente por la instalación de Helm. Puedes confirmarlo con el siguiente comando: 
    kubectl describe serviceaccount apim-ksa -n NAMESPACE

    Donde NAMESPACE es el espacio de nombres en el que se ha desplegado el operador de APIM.

    Confirma que apigee-apim-gsa@$PROJECT.iam.gserviceaccount.com aparece en el campo Anotaciones de la salida.

    Por ejemplo: 

    kubectl describe serviceaccount apim-ksa -n apim

    El resultado es similar al siguiente: Name: apim-ksa Namespace: apim Labels: ... Annotations: iam.gke.io/gcp-service-account: apigee-apim-gsa@apigee-product-demo.iam.gserviceaccount.com ... Image pull secrets: Mountable secrets: Tokens: Events:

  • La cuenta de servicio apigee-apim-gsa tiene los roles y permisos de gestión de identidades y accesos correctos. Puedes confirmarlo con el siguiente comando: 
     gcloud iam service-accounts get-iam-policy \
apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com

    La cuenta de servicio debe tener el rol roles/iam.workloadIdentityUser.

    Por ejemplo, el siguiente resultado muestra el rol roles/iam.workloadIdentityUser: 

    bindings:
- members:
  - serviceAccount:$PROJECT_ID.svc.id.goog[/apim-ksa]
  role: roles/iam.workloadIdentityUser
etag: BwYUpeaM7XQ=
version: 1
  • No hay condiciones de IAM especiales en los roles necesarios, lo que impediría el acceso del operador.

Solucionar problemas con el tráfico del entorno de ejecución de Apigee

En esta sección se describe cómo solucionar problemas con el tráfico del tiempo de ejecución de Apigee. En las siguientes secciones se describe cómo solucionar problemas con solicitudes válidas y no válidas.

Las solicitudes válidas fallan

Si no puede enviar solicitudes válidas a su tiempo de ejecución de Apigee, es posible que se produzcan los siguientes problemas:

  • La puerta de enlace de GKE no puede acceder al tiempo de ejecución de Apigee.
  • Tu clave de API o tus credenciales de JWT no son válidas.
  • El producto de API de Apigee no está configurado para el destino y el entorno correctos.
  • El tiempo de ejecución de Apigee no conoce el producto de API de Apigee.

Pasos para solucionar el problema

Para solucionar problemas con solicitudes válidas, sigue estos pasos:

  • Habilita los registros del balanceador de carga de la pasarela de GKE y revísalos para determinar la causa de los fallos de la extensión de texto destacado. Consulta los registros de GKE Gateway para obtener más información.
  • Confirma que el servicio de backend al que hace referencia el servicio ext-proc está en buen estado.
  • Revisa la configuración del producto de API en Apigee:
    • Confirma que el producto de API está habilitado en el entorno correcto (por ejemplo, test o prod).
    • Confirma que la ruta del recurso coincide con tu solicitud. Una ruta como / o /** coincidirá con cualquier ruta. También puedes usar los comodines * o ** para buscar coincidencias.
    • Confirma que tienes una aplicación de desarrollador configurada para el producto de API. El producto de API debe estar vinculado a una aplicación para desarrolladores para validar sus claves de API.
  • Revisa tu solicitud a la pasarela:
    • Confirma que la clave de consumidor se envía en el encabezado x-api-key.
    • Asegúrate de que la clave de consumidor sea válida. Las credenciales de la aplicación para desarrolladores deben aprobarse para tu producto de API.

Las solicitudes no válidas se completan

Si las solicitudes no válidas a tu tiempo de ejecución de Apigee se completan correctamente, es posible que se produzcan los siguientes problemas:

  • FailOpen tiene el valor true en tu APIMExtensionPolicy.
  • No se ha definido ninguna extensión de tráfico para el balanceador de carga de tu GKE Gateway.

Pasos para solucionar el problema

Para solucionar problemas con solicitudes no válidas, sigue estos pasos:

  • Confirma que existe una extensión de servicio y que hace referencia a los servicios de backend y a la regla de reenvío correctos de tu puerta de enlace de GKE.

    Usa el siguiente comando para ver la extensión de servicio: 

    gcloud beta service-extensions lb-traffic-extensions describe NAME_OF_APIM_EXTENSION_POLICY --location=LOCATION  --project=PROJECT

    Donde:

    • NAME_OF_APIM_EXTENSION_POLICY: el APIMExtensionPolicy nombre de recurso personalizado.
    • PROJECT: el ID del proyecto.
    • LOCATION: ubicación del clúster de GKE en el que se ha desplegado tu Gateway.

    La salida será similar a la siguiente: 

    ...
extensionChains:
- extensions:
  - authority: ext11.com
    failOpen: false  # make sure this is false
    name: ext11
    service: https://www.googleapis.com/compute/v1/projects/my-project/regions/us-west1/backendServices/gkegw1-2y13-apigee-service-extension-backend-service-443-yhsnrauznpwh # Confirm this is correct
    supportedEvents:
    - REQUEST_HEADERS
    - RESPONSE_HEADERS
    - REQUEST_BODY
    - RESPONSE_BODY
    - REQUEST_TRAILERS
    - RESPONSE_TRAILERS
    timeout: 0.100s
  matchCondition:
    celExpression: 'true' # Confirm this is set
  name: chain1
forwardingRules:
- https://www.googleapis.com/compute/v1/projects/my-project/regions/us-west1/forwardingRules/gkegw1-2y13-default-internal-http-h6c1hhp1ce6q # Confirm this is the correct forwarding rule for your application load balancer
loadBalancingScheme: INTERNAL_MANAGED
name: projects/my-project/locations/us-west1/lbTrafficExtensions/apim-extension-policy-1

    Faltan estadísticas

    Si no puedes ver Apigee API Analytics para el operador de gestión de APIs en la consola Google Cloud , ten en cuenta que la ingesta de Apigee puede retrasarse unos minutos.

    Recursos adicionales

    También puede usar los siguientes recursos para solucionar problemas con el operador de APIM y el tráfico del tiempo de ejecución de Apigee: