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 APIM Apigee 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 d'exécution Apigee.

Vérifier l'état d'une ressource personnalisée

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

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

Lorsqu'un fichier yaml de ressource personnalisée est appliqué au cluster, Kubernetes apporte les modifications correspondantes à l'infrastructure sous-jacente. Vérifier l'objet d'état de la ressource personnalisée peut fournir des informations sur l'état de la ressource et mettre en évidence les erreurs qui en résultent si les opérations d'infrastructure sous-jacentes échouent.

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 de la passerelle GKE

Lorsque vous appliquez 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 les règles de traitement. Les journaux liés au trafic ext-proc peuvent être utiles pour résoudre les problèmes.

Afficher les journaux des accroches ext-proc

Pour afficher les journaux du trafic des accroches ext-proc:

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

    Où GATEWAY_NAME correspond au nom de la passerelle GKE.

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

  2. Pour activer la journalisation, suivez la procédure décrite dans Activer la journalisation sur un service de backend.
  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 backend pour afficher les informations d'entrée de journal de l'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.

    L'exemple suivant est une 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}/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}/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

L'opérateur APIM est un opérateur Kubernetes qui traite les événements de ressources personnalisées APIM (création, lecture, mise à jour et suppression, par exemple) 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 à la suivante: 
    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 les problèmes de création, de mise à jour ou de suppression des services APIMExtensionPolicy dans Google Cloud networks ou les problèmes liés 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 constatez des erreurs avec le 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 vérifier à 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 de la sortie.

    Exemple : 

    kubectl describe serviceaccount apim-ksa -n apim

    Le résultat ressemble à ce qui suit : Nom: apim-ksa Espace de noms: apim Libellés: ... Annotations: iam.gke.io/gcp-service-account: apigee-apim-gsa@apigee-product-demo.iam.gserviceaccount.com ... Secrets de récupération d'images: Secrets installables: Jetons: Événements:

  • Le compte de service apigee-apim-gsa dispose des rôles et des 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}.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}.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'accès de l'opérateur.

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.

Les requêtes valides échouent

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 parvient pas à atteindre l'environnement d'exécution 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 requêtes valides:

  • Activez les journaux de l'équilibreur de charge pour GKE Gateway et examinez-les pour déterminer la cause des échecs à partir de l'appel de l'extension. Pour en savoir plus, consultez les journaux de la passerelle GKE.
  • Vérifiez que le service de backend référencé à partir du service ext-proc est opérationnel.
  • Vérifiez 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 requête. 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 que vous avez configuré une application de développeur pour le produit d'API. Le produit d'API doit être lié à une application de développement pour valider ses clés API.
  • Examinez votre demande envoyée à la passerelle :
    • Vérifiez que la clé client est transmise dans l'en-tête x-api-key.
    • Assurez-vous que la clé client est valide. Les identifiants de l'application de développement doivent être approuvés pour votre produit d'API.

Les requêtes non valides aboutissent

Si des requêtes non valides sont traitées par votre environnement d'exécution Apigee, 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 requêtes 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
    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'intégration Apigee peut être retardée de quelques minutes.

    Autres ressources

    Vous pouvez également utiliser les ressources suivantes pour résoudre les problèmes liés à l'opérateur APIM et au trafic d'exécution Apigee: