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 Probleme mit dem Apigee APIM-Operator für Kubernetes beheben. Es gibt eine Reihe von Tools, mit denen Sie auftretende 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 Apigee-Laufzeitverkehr beheben.

Status der benutzerdefinierten Ressource 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. Zulässige Werte sind running und created.
  • ERRORMESSAGE: Wenn der Ressourcenvorgang fehlschlägt, wird das Feld für die Fehlermeldung mit einer Erläuterung ausgefüllt.

Wenn eine benutzerdefinierte Ressourcen-yaml-Datei 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 sich alle daraus resultierenden Fehler ansehen, falls 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 APIMExtensionPolicy-Ressource mit dem Namen apim-extension-policy im Namespace apim geprüft: 

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

Die Ausgabe sieht in etwa so aus:

NAME                      STATE                  ERRORMESSAGE
apim-extension-policy     Create_Update_Failed   Permission denied

Logs ansehen

In diesem Abschnitt wird beschrieben, wie Sie mithilfe von Protokollen Probleme mit der GKE-Gateway-Ressource (Google Kubernetes Engine) und der APIM-Betreiberressource beheben.

GKE-Gateway-Logs

Wenn Sie die APIMExtensionPolicy anwenden, wird das in Ihrem Cluster erstellte GKE-Gateway mit einer Traffic Extension konfiguriert. Die Erweiterung verwendet die externe Verarbeitung von Kubernetes (ext-proc), um die Apigee-Laufzeit- und Prozessrichtlinien aufzurufen. Die Logs, die sich auf den ext-proc-Traffic beziehen, können bei der Fehlerbehebung hilfreich sein.

Logs für ext-proc-Infofelder ansehen

So rufen Sie Logs für den Traffic für Zusatzinformationen vom Typ ext-proc 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 in einem Backend-Dienst aktivieren, um das Logging zu aktivieren.
  3. Rufen Sie in der Google Cloud Console die Seite Log-Explorer auf, um sich Logs anzusehen.

    Log-Explorer

  4. Unter Protokollmeldungen für einen Backend-Dienst finden Sie Informationen zu verfügbaren Popup-Logeinträgen, einschließlich der JSON-Nutzlaststruktur für den service_extension_info-Load Balancer-Logeintrag. Sie können im Log-Explorer über das Feld Suchen nach den relevanten Informationen filtern.

    Das folgende Beispiel ist ein Logeintrag, der bei einem fehlgeschlagenen ext-proc-Infofeld angezeigt werden kann: 

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

    Beachten Sie, dass im Feld grpcStatus ABORTED angezeigt wird.

APIM-Operator-Logs

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

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

  1. Rufen Sie in der Google Cloud Console die Seite Log-Explorer auf, um sich Logs anzusehen.

    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 in Google Cloud networks-Dienste oder Probleme mit API-Produkten in Apigee-Verwaltungsebenen.

    Ein Beispiel für einen Fehler sieht in etwa so aus: 

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

Wenn Sie Fehler mit dem Statuscode 403 erhalten, 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 für Cluster, die im Autopilot-Modus erstellt wurden, standardmäßig aktiviert. Wenn Sie einen Cluster im Standardmodus erstellt haben, aktivieren Sie die Workload Identity-Föderation wie unter Workload Identity-Föderation für GKE aktivieren beschrieben.
  • Das Kubernetes-Dienstkonto (apim-ksa) wird von der Helm-Installation korrekt annotiert. Sie können dies mit dem folgenden Befehl prüfen: 
    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 Anmerkungen der Ausgabe angezeigt wird.

    Beispiel: 

    kubectl describe serviceaccount apim-ksa -n apim

    Die Ausgabe sieht in etwa so aus: Name: apim-ksa Namespace: apim Labels: ... Anmerkungen: iam.gke.io/gcp-service-account: apigee-apim-gsa@apigee-product-demo.iam.gserviceaccount.com ... Secrets für das Abrufen von Images: Bereitstellbare Secrets: Tokens: Ereignisse:

  • Das Dienstkonto apigee-apim-gsa hat die richtigen IAM-Rollen und -Berechtigungen. Sie können dies mit dem folgenden Befehl prüfen: 
     gcloud iam service-accounts get-iam-policy \
apigee-apim-gsa@${PROJECT}.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}.svc.id.goog[/apim-ksa]
  role: roles/iam.workloadIdentityUser
etag: BwYUpeaM7XQ=
version: 1
  • Für die erforderlichen Rollen gelten keine speziellen IAM-Bedingungen, die den Zugriff für den Operator verhindern würden.

Probleme mit Apigee-Laufzeitverkehr beheben

In diesem Abschnitt wird beschrieben, wie Sie Probleme mit Apigee-Laufzeitverkehr 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, liegen möglicherweise die folgenden Probleme vor:

  • 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 der Fehler aus der Erweiterungsanfrage zu ermitteln. Weitere Informationen finden Sie in den GKE-Gateway-Protokollen.
  • Prüfen Sie, ob der Back-End-Dienst, auf den im ext-proc-Dienst verwiesen wird, fehlerfrei ist.
  • Prü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 /** entspricht jedem Pfad. Sie können auch Platzhalter * oder ** verwenden, um einen Abgleich zu ermöglichen.
    • 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üfe, ob der Consumer Key im x-api-key-Header übergeben wird.
    • Der Consumer Key muss gültig sein. Die Anmeldedaten der Entwickler-App müssen für Ihr API-Produkt genehmigt sein.

Ungültige Anfragen werden ausgeführt

Wenn ungültige Anfragen an Ihre Apigee-Laufzeit erfolgreich sind, liegen möglicherweise die folgenden Probleme vor:

  • 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 Diensterweiterung vorhanden ist und auf die richtigen Back-End-Dienste und die Weiterleitungsregel für Ihr GKE-Gateway verweist.

    Verwenden Sie den folgenden Befehl, um die Diensterweiterung 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-Clusters, 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
    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-Betreiber nicht in der Google Cloud Console sehen können, kann die Aufnahme in Apigee um einige Minuten verzögert werden.

    Zusätzliche Ressourcen

    Die folgenden Ressourcen können auch zur Behebung von Problemen mit APIM Operator- und Apigee-Laufzeit-Traffic verwendet werden: