Résoudre les problèmes liés à l'opérateur APIM Apigee pour Kubernetes

Cette page s'applique à Apigee, mais pas à Apigee hybrid.

Consultez la documentation d' Apigee Edge.

Cette page explique comment résoudre les problèmes liés à l'opérateur Apigee APIM pour Kubernetes. Plusieurs outils sont disponibles pour résoudre les problèmes que vous pourriez rencontrer. Cette page explique comment vérifier l'état des ressources personnalisées, utiliser l'explorateur de journaux et résoudre les problèmes liés au trafic du runtime Apigee.

Vérifier l'état des ressources personnalisées

Chaque ressource personnalisée utilisée dans l'opérateur Apigee APIM pour Kubernetes contient un objet d'état avec deux champs :

  • STATE : décrit l'état de la ressource. Les valeurs incluent running et created.
  • ERRORMESSAGE : si l'opération sur la ressource échoue, le champ du message d'erreur est renseigné avec un message explicatif.

Lorsqu'un fichier de ressource personnalisée yaml est appliqué au cluster, Kubernetes apporte les modifications correspondantes à l'infrastructure sous-jacente. L'objet d'état de la ressource personnalisée peut fournir des informations sur l'état de la ressource et faire apparaître les erreurs résultantes en cas d'échec des opérations d'infrastructure sous-jacentes.

Vous pouvez vérifier l'état de la ressource personnalisée à l'aide de la commande suivante : 

kubectl -n NAMESPACE get CUSTOM_RESOURCE_KIND CUSTOM_RESOURCE_NAME

Où :

  • NAMESPACE : espace de noms dans lequel la ressource personnalisée est déployée.
  • CUSTOM_RESOURCE_KIND : type de la ressource personnalisée.
  • CUSTOM_RESOURCE_NAME : nom de la ressource personnalisée.

Par exemple, la commande suivante vérifie l'état de la ressource personnalisée APIMExtensionPolicy nommée apim-extension-policy dans l'espace de noms apim : 

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

Le résultat ressemble à ce qui suit :

NAME                      STATE                  ERRORMESSAGE
apim-extension-policy     Create_Update_Failed   Permission denied

Afficher les journaux

Cette section explique comment utiliser les journaux pour résoudre les problèmes liés à la ressource de passerelle Google Kubernetes Engine (GKE) et à la ressource de l'opérateur APIM.

Journaux GKE Gateway

Lorsque vous appliquez la APIMExtensionPolicy, la passerelle GKE que vous avez créée dans votre cluster est configurée avec une extension de trafic. L'extension utilise le traitement externe Kubernetes (ext-proc) pour appeler l'environnement d'exécution Apigee et traiter les règles. Les journaux liés au trafic ext-proc peuvent être utiles pour résoudre les problèmes.

Afficher les journaux pour les encadrés ext-proc

Pour afficher les journaux du trafic d'accroche ext-proc :

  1. Obtenez l'ID du service de backend créé pour le runtime Apigee : 
    kubectl get gateways.gateway.networking.k8s.io GATEWAY_NAME
  -o=jsonpath="{.metadata.annotations.networking\.gke\.io/backend-services}"

    Où GATEWAY_NAME est le nom de la passerelle GKE.

    Le service de backend contiendra apigee-service-extension-backend-service dans l'ID.

  2. Suivez la procédure décrite dans Activer la journalisation sur un service de backend pour activer la journalisation.
  3. Pour afficher les journaux dans la console Google Cloud , accédez à la page Explorateur de journaux :

    Explorateur de journaux

  4. Consultez Messages de journal pour un service de backend pour voir les informations disponibles sur les entrées de journal d'appel, y compris la structure de la charge utile JSON pour l'entrée de journal de l'équilibreur de charge service_extension_info. Vous pouvez utiliser le champ Rechercher de l'explorateur de journaux pour filtrer les informations pertinentes.

    Voici un exemple d'entrée de journal que vous pouvez voir pour un appel ext-proc ayant échoué : 

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

    Notez que le champ grpcStatus affiche ABORTED.

Journaux de l'opérateur APIM

APIM Operator est un opérateur Kubernetes qui traite les événements de ressources personnalisées APIM (tels que la création, la lecture, la mise à jour et la suppression) et les traduit dans la configuration Apigee appropriée.

Pour afficher les journaux de l'opérateur APIM :

  1. Pour afficher les journaux dans la console Google Cloud , accédez à la page Explorateur de journaux :

    Explorateur de journaux

  2. Dans le volet Requête, saisissez une requête semblable à celle-ci : 
    resource.type="k8s_container"
resource.labels.namespace_name="apim"
labels.k8s-pod/app="apigee-apim-operator" severity>=DEFAULT
  3. Cliquez sur Exécuter la requête.
  4. Les entrées de journal filtrées s'affichent dans le volet Résultats de la requête.
  5. Notez tout problème lié à la création, à la mise à jour ou à la suppression des services APIMExtensionPolicy dans les réseaux Google Cloud , ou tout problème lié aux produits d'API dans les plans de gestion Apigee.

    Voici un exemple d'erreur : 

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

Résoudre les erreurs d'accès 403 dans l'opérateur APIM

Si vous rencontrez des erreurs de code d'état 403 indiquant des problèmes d'accès, vérifiez les points suivants :

  • La fédération d'identité de charge de travail est activée sur votre cluster GKE. La fédération d'identité de charge de travail est activée par défaut pour les clusters créés avec le mode Autopilot. Si vous avez créé un cluster en mode standard, activez la fédération d'identité de charge de travail comme décrit dans Activer la fédération d'identité de charge de travail pour GKE.
  • Le compte de service Kubernetes (apim-ksa) est correctement annoté par l'installation Helm. Vous pouvez le confirmer à l'aide de la commande suivante : 
    kubectl describe serviceaccount apim-ksa -n NAMESPACE

    Où NAMESPACE est l'espace de noms dans lequel l'opérateur APIM est déployé.

    Vérifiez que apigee-apim-gsa@$PROJECT.iam.gserviceaccount.com apparaît dans le champ Annotations du résultat.

    Exemple : 

    kubectl describe serviceaccount apim-ksa -n apim

    Le résultat ressemble à ce qui suit : 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:

  • Le compte de service apigee-apim-gsa dispose des rôles et autorisations IAM appropriés. Vous pouvez le vérifier à l'aide de la commande suivante : 
     gcloud iam service-accounts get-iam-policy \
apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com

    Le compte de service doit disposer du rôle roles/iam.workloadIdentityUser.

    Par exemple, le résultat suivant affiche le rôle roles/iam.workloadIdentityUser : 

    bindings:
- members:
  - serviceAccount:$PROJECT_ID.svc.id.goog[/apim-ksa]
  role: roles/iam.workloadIdentityUser
etag: BwYUpeaM7XQ=
version: 1
  • Aucune condition IAM spéciale n'est présente sur les rôles requis, ce qui empêcherait l'opérateur d'y accéder.

Résoudre les problèmes liés au trafic d'exécution Apigee

Cette section explique comment résoudre les problèmes liés au trafic d'exécution Apigee. Les sections suivantes expliquent comment résoudre les problèmes liés aux requêtes valides et non valides.

Échec des demandes valides

Si vous ne parvenez pas à envoyer de requêtes valides à votre environnement d'exécution Apigee, les problèmes suivants peuvent se produire :

  • La passerelle GKE ne peut pas accéder au runtime Apigee.
  • Votre clé API ou vos identifiants JWT ne sont pas valides.
  • Le produit d'API Apigee n'est pas configuré pour la cible et l'environnement appropriés.
  • L'environnement d'exécution Apigee n'a pas connaissance du produit d'API Apigee.

Procédure de dépannage

Pour résoudre les problèmes liés aux demandes valides :

  • Activez les journaux de l'équilibreur de charge pour GKE Gateway et examinez-les pour déterminer la cause des échecs de l'appel d'extension. Pour en savoir plus, consultez les journaux GKE Gateway.
  • Vérifiez que le service de backend référencé par le service ext-proc est opérationnel.
  • Examinez la configuration du produit d'API sur Apigee :
    • Vérifiez que le produit d'API est activé pour l'environnement approprié (par exemple, test ou prod).
    • Vérifiez que le chemin de ressource correspond à votre demande. Un chemin d'accès tel que / ou /** correspond à n'importe quel chemin. Vous pouvez également utiliser les caractères génériques * ou ** pour la mise en correspondance.
    • Vérifiez qu'une application de développeur est configurée pour le produit d'API. Le produit d'API doit être lié à une application de développement pour valider ses clés API.
  • Vérifiez votre demande à la passerelle :
    • Vérifiez que la clé consommateur est transmise dans l'en-tête x-api-key.
    • Assurez-vous que la clé consommateur est valide. Les identifiants de l'application de développement doivent être approuvés pour votre produit d'API.

Les demandes non valides sont acceptées

Si des requêtes non valides adressées à votre environnement d'exécution Apigee aboutissent, les problèmes suivants peuvent se produire :

  • FailOpen est défini sur true dans votre APIMExtensionPolicy.
  • Aucune extension de trafic n'est définie pour l'équilibreur de charge de votre passerelle GKE.

Procédure de dépannage

Pour résoudre les problèmes liés aux demandes non valides :

  • Vérifiez qu'une extension de service existe et qu'elle fait référence aux services de backend et à la règle de transfert appropriés pour votre passerelle GKE.

    Utilisez la commande suivante pour afficher l'extension de service : 

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

    Où :

    • NAME_OF_APIM_EXTENSION_POLICY : nom de la ressource personnalisée APIMExtensionPolicy.
    • PROJECT : ID du projet.
    • LOCATION : emplacement du cluster GKE dans lequel votre passerelle est déployée.

    Le résultat doit ressembler à ce qui suit : 

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

    Données analytiques manquantes

    Si vous ne parvenez pas à afficher Apigee API Analytics pour l'opérateur APIM dans la console Google Cloud , notez que l'ingestion Apigee peut être retardée de quelques minutes.

    Autres ressources

    Les ressources suivantes peuvent également être utilisées pour résoudre les problèmes liés à l'opérateur APIM et au trafic d'exécution Apigee :