Fehlerbehebung beim Apigee APIM-Operator für Kubernetes

Diese Seite gilt für Apigee, aber nicht für Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Auf dieser Seite wird beschrieben, wie Sie Fehler beim Apigee APIM Operator für Kubernetes beheben. Es gibt eine Reihe von Tools, mit denen Sie Probleme beheben können. Auf dieser Seite wird beschrieben, wie Sie den Status der benutzerdefinierten Ressourcen prüfen, den Log-Explorer verwenden und Probleme mit dem Apigee-Laufzeittraffic beheben.

Status benutzerdefinierter Ressourcen prüfen

Jede benutzerdefinierte Ressource, die im Apigee APIM Operator für Kubernetes verwendet wird, enthält ein Statusobjekt mit zwei Feldern:

  • STATE: Beschreibt den Status der Ressource. Mögliche Werte sind running und created.
  • ERRORMESSAGE: Wenn der Ressourcen-Vorgang fehlschlägt, wird das Feld für die Fehlermeldung mit einer erläuternden Meldung gefüllt.

Wenn eine benutzerdefinierte Ressourcendatei yaml auf den Cluster angewendet wird, nimmt Kubernetes die entsprechenden Änderungen an der zugrunde liegenden Infrastruktur vor. Wenn Sie das Statusobjekt der benutzerdefinierten Ressource prüfen, erhalten Sie Informationen zum Status der Ressource und können alle resultierenden Fehler erkennen, wenn die zugrunde liegenden Infrastrukturvorgänge fehlschlagen.

Sie können den Status der benutzerdefinierten Ressource mit dem folgenden Befehl prüfen:

kubectl -n NAMESPACE get CUSTOM_RESOURCE_KIND CUSTOM_RESOURCE_NAME

Wobei:

  • NAMESPACE: Der Namespace, in dem die benutzerdefinierte Ressource bereitgestellt wird.
  • CUSTOM_RESOURCE_KIND: Die Art der benutzerdefinierten Ressource.
  • CUSTOM_RESOURCE_NAME: Der Name der benutzerdefinierten Ressource.

Mit dem folgenden Befehl wird beispielsweise der Status der benutzerdefinierten Ressource APIMExtensionPolicy mit dem Namen apim-extension-policy im Namespace apim geprüft:

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

Die Ausgabe sieht etwa so aus:

NAME                      STATE                  ERRORMESSAGE
apim-extension-policy     Create_Update_Failed   Permission denied

Logs ansehen

In diesem Abschnitt wird beschrieben, wie Sie Logs verwenden, um Fehler bei der GKE-Gateway-Ressource (Google Kubernetes Engine) und der APIM-Operator-Ressource zu beheben.

GKE Gateway-Logs

Wenn Sie die APIMExtensionPolicy anwenden, wird das von Ihnen in Ihrem Cluster erstellte GKE-Gateway mit einer Traffic-Erweiterung konfiguriert. Die Erweiterung verwendet die externe Verarbeitung von Kubernetes (ext-proc), um die Apigee-Laufzeit aufzurufen und Richtlinien zu verarbeiten. Die Logs für den ext-proc-Traffic können bei der Fehlerbehebung hilfreich sein.

Logs für ext-proc-Callouts ansehen

So rufen Sie Logs für den ext-proc-Callout-Traffic auf:

  1. Rufen Sie die ID des Backend-Dienstes ab, der für die Apigee-Laufzeit erstellt wurde:
    kubectl get gateways.gateway.networking.k8s.io GATEWAY_NAME
      -o=jsonpath="{.metadata.annotations.networking\.gke\.io/backend-services}"

    Dabei ist GATEWAY_NAME der Name des GKE-Gateways.

    Der Back-End-Dienst enthält apigee-service-extension-backend-service in der ID.

  2. Folgen Sie der Anleitung unter Logging für einen Backend-Dienst aktivieren, um das Logging zu aktivieren.
  3. So rufen Sie Logs in der Google Cloud Console auf:

    Log-Explorer

  4. Unter Log-Nachrichten für einen Back-End-Dienst finden Sie Informationen zu den verfügbaren Callout-Logeinträgen, einschließlich der JSON-Nutzlaststruktur für den service_extension_info-Load-Balancer-Logeintrag. Mit dem Feld Suchen im Log-Explorer können Sie nach den relevanten Informationen filtern.

    Das folgende Beispiel zeigt einen Logeintrag, der für einen fehlgeschlagenen ext-proc-Aufruf angezeigt wird:

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

    Beachten Sie, dass im Feld grpcStatus ABORTED angezeigt wird.

APIM-Operatorlogs

Der APIM-Operator ist ein Kubernetes-Operator, der APIM-Ereignisse für benutzerdefinierte Ressourcen (z. B. Erstellen, Lesen, Aktualisieren und Löschen) verarbeitet und in die entsprechende Apigee-Konfiguration übersetzt.

So rufen Sie Logs für den APIM-Operator auf:

  1. So rufen Sie Logs in der Google Cloud Console auf:

    Log-Explorer

  2. Geben Sie im Bereich „Abfrage“ eine Abfrage wie die folgende ein:
    resource.type="k8s_container"
    resource.labels.namespace_name="apim"
    labels.k8s-pod/app="apigee-apim-operator" severity>=DEFAULT
    
  3. Klicken Sie auf Abfrage ausführen.
  4. Die gefilterten Logeinträge werden im Bereich Abfrageergebnisse angezeigt.
  5. Notieren Sie sich alle Probleme beim Erstellen, Aktualisieren oder Löschen der APIMExtensionPolicy Google Cloud -Netzwerkdienste oder Probleme mit API-Produkten in Apigee-Managementebenen.

    Ein Beispiel für einen Fehler:

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

403-Zugriffsfehler im APIM-Operator beheben

Wenn Sie Fehler mit dem Statuscode 403 finden, die auf Zugriffsprobleme hinweisen, prüfen Sie Folgendes:

  • In Ihrem GKE-Cluster ist die Identitätsföderation von Arbeitslasten aktiviert. Die Identitätsföderation von Arbeitslasten ist standardmäßig für Cluster aktiviert, die im Autopilot-Modus erstellt wurden. Wenn Sie einen Cluster im Standardmodus erstellt haben, aktivieren Sie die Identitätsföderation von Arbeitslasten wie unter Identitätsföderation von Arbeitslasten für GKE aktivieren beschrieben.
  • Das Kubernetes-Dienstkonto (apim-ksa) wird durch die Helm-Installation korrekt annotiert. Mit dem folgenden Befehl können Sie dies bestätigen:
    kubectl describe serviceaccount apim-ksa -n NAMESPACE

    Dabei ist NAMESPACE der Namespace, in dem der APIM-Operator bereitgestellt wird.

    Prüfen Sie, ob apigee-apim-gsa@$PROJECT.iam.gserviceaccount.com im Feld Annotations der Ausgabe angezeigt wird.

    Beispiel:

    kubectl describe serviceaccount apim-ksa -n apim

    Die Ausgabe sieht etwa so aus: 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: Einbindbare Secrets: Tokens: Ereignisse:

  • Das apigee-apim-gsa-Dienstkonto hat die richtigen IAM-Rollen und ‑Berechtigungen. Mit dem folgenden Befehl können Sie dies bestätigen:
     gcloud iam service-accounts get-iam-policy \
    apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com

    Das Dienstkonto muss die Rolle roles/iam.workloadIdentityUser haben.

    In der folgenden Ausgabe wird beispielsweise die Rolle roles/iam.workloadIdentityUser angezeigt:

    bindings:
    - members:
      - serviceAccount:$PROJECT_ID.svc.id.goog[/apim-ksa]
      role: roles/iam.workloadIdentityUser
    etag: BwYUpeaM7XQ=
    version: 1
    
  • Für die erforderlichen Rollen sind keine speziellen IAM-Bedingungen vorhanden, die den Zugriff für den Operator verhindern würden.

Probleme mit Apigee-Laufzeittraffic beheben

In diesem Abschnitt wird beschrieben, wie Sie Probleme mit dem Apigee-Laufzeittraffic beheben. In den folgenden Abschnitten wird beschrieben, wie Sie Probleme mit gültigen und ungültigen Anfragen beheben.

Gültige Anfragen schlagen fehl

Wenn Sie keine gültigen Anfragen an Ihre Apigee-Laufzeit senden können, können die folgenden Probleme vorliegen:

  • Das GKE Gateway kann die Apigee-Laufzeit nicht erreichen.
  • Ihr API-Schlüssel oder Ihre JWT-Anmeldedaten sind ungültig.
  • Das Apigee API-Produkt ist nicht für das richtige Ziel und die richtige Umgebung konfiguriert.
  • Die Apigee-Laufzeit kennt das Apigee API-Produkt nicht.

Schritte zur Fehlerbehebung

So beheben Sie Probleme mit gültigen Anfragen:

  • Aktivieren Sie Load-Balancer-Logs für das GKE Gateway und prüfen Sie die Logs, um die Ursache von Fehlern beim Erweiterungsaufruf zu ermitteln. Weitere Informationen finden Sie unter GKE Gateway-Logs.
  • Prüfen Sie, ob der Back-End-Dienst, auf den vom ext-proc-Dienst verwiesen wird, fehlerfrei ist.
  • Überprüfen Sie die API-Produktkonfiguration in Apigee:
    • Prüfen Sie, ob das API-Produkt für die richtige Umgebung aktiviert ist (z. B. test oder prod).
    • Prüfen Sie, ob der Ressourcenpfad mit Ihrer Anfrage übereinstimmt. Ein Pfad wie / oder /** stimmt mit jedem Pfad überein. Sie können auch die Platzhalter * oder ** für den Abgleich verwenden.
    • Prüfen Sie, ob Sie eine Entwickler-App für das API-Produkt konfiguriert haben. Das API-Produkt muss an eine Entwickler-App gebunden sein, um die API-Schlüssel zu validieren.
  • Überprüfen Sie Ihre Anfrage an das Gateway:
    • Prüfen Sie, ob der Consumer-Schlüssel im x-api-key-Header übergeben wird.
    • Prüfen Sie, ob der Consumerschlüssel gültig ist. Die Anmeldedaten der Entwickler-App müssen für Ihr API-Produkt genehmigt sein.

Ungültige Anfragen erfolgreich

Wenn ungültige Anfragen an Ihre Apigee-Laufzeit erfolgreich sind, können die folgenden Probleme vorliegen:

  • FailOpen ist in Ihrer APIMExtensionPolicy auf true festgelegt.
  • Für den Load-Balancer Ihres GKE-Gateways ist keine Traffic-Erweiterung festgelegt.

Schritte zur Fehlerbehebung

So beheben Sie Probleme mit ungültigen Anfragen:

  • Prüfen Sie, ob eine Dienst-Extension vorhanden ist und auf die richtigen Back-End-Dienste und Weiterleitungsregeln für Ihr GKE Gateway verweist.

    Verwenden Sie den folgenden Befehl, um die Dienst-Erweiterung aufzurufen:

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

    Wobei:

    • NAME_OF_APIM_EXTENSION_POLICY: Der Name der benutzerdefinierten Ressource APIMExtensionPolicy.
    • PROJECT: die Projekt-ID
    • LOCATION: Der Standort des GKE-Cluster, in dem Ihr Gateway bereitgestellt wird.

    Die Ausgabe sollte in etwa so aussehen:

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

    Fehlende Analysen

    Wenn Sie Apigee API Analytics für den APIM-Operator in der Google Cloud -Konsole nicht aufrufen können, beachten Sie, dass sich die Aufnahme von Apigee um einige Minuten verzögern kann.

    Zusätzliche Ressourcen

    Die folgenden Ressourcen können auch verwendet werden, um Probleme mit dem APIM-Operator und dem Apigee-Laufzeittraffic zu beheben: