Risolvere i problemi relativi all'operatore Apigee APIM per Kubernetes

Questa pagina si applica ad Apigee, ma non ad Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Questa pagina descrive come risolvere i problemi relativi all'operatore Apigee APIM per Kubernetes. Sono disponibili diversi strumenti per risolvere eventuali problemi che potresti riscontrare. Questa pagina descrive come controllare lo stato delle risorse personalizzate, utilizzare Esplora log e risolvere i problemi relativi al traffico di runtime di Apigee.

Controllare lo stato della risorsa personalizzata

Ogni risorsa personalizzata utilizzata in Apigee APIM Operator per Kubernetes contiene un oggetto di stato con due campi:

  • STATE: descrive lo stato della risorsa. I valori includono running e created.
  • ERRORMESSAGE: se l'operazione sulla risorsa non riesce, il campo del messaggio di errore viene compilato con un messaggio esplicativo.

Quando un file di risorsa personalizzata yaml viene applicato al cluster, Kubernetes apporta le modifiche corrispondenti all'infrastruttura sottostante. Il controllo dell'oggetto di stato della risorsa personalizzata può fornire informazioni sullo stato della risorsa e mostrare eventuali errori risultanti se le operazioni dell'infrastruttura sottostante non vanno a buon fine.

Puoi controllare lo stato della risorsa personalizzata con il seguente comando: 

kubectl -n NAMESPACE get CUSTOM_RESOURCE_KIND CUSTOM_RESOURCE_NAME

Dove:

  • NAMESPACE: lo spazio dei nomi in cui viene eseguito il deployment della risorsa personalizzata.
  • CUSTOM_RESOURCE_KIND: il tipo della risorsa personalizzata.
  • CUSTOM_RESOURCE_NAME: il nome della risorsa personalizzata.

Ad esempio, il seguente comando controlla lo stato della risorsa personalizzata APIMExtensionPolicy denominata apim-extension-policy nello spazio dei nomi apim: 

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

L'output è simile al seguente:

NAME                      STATE                  ERRORMESSAGE
apim-extension-policy     Create_Update_Failed   Permission denied

Visualizza i log

Questa sezione descrive come utilizzare i log per risolvere i problemi relativi alla risorsa Gateway di Google Kubernetes Engine (GKE) e alla risorsa APIM Operator.

Log di GKE Gateway

Quando applichi APIMExtensionPolicy, il gateway GKE che hai creato nel cluster viene configurato con un'estensione del traffico. L'estensione utilizza l'elaborazione esterna di Kubernetes (ext-proc) per chiamare il runtime Apigee ed elaborare i criteri. I log relativi al traffico ext-proc possono essere utili per risolvere i problemi.

Visualizza i log per i callout ext-proc

Per visualizzare i log per il traffico callout ext-proc:

  1. Recupera l'ID del servizio di backend creato per Apigee Runtime: 
    kubectl get gateways.gateway.networking.k8s.io GATEWAY_NAME
  -o=jsonpath="{.metadata.annotations.networking\.gke\.io/backend-services}"

    Dove GATEWAY_NAME è il nome del gateway GKE.

    Il servizio di backend conterrà apigee-service-extension-backend-service nell'ID.

  2. Segui i passaggi descritti in Abilitare il logging su un servizio di backend per abilitare il logging.
  3. Per visualizzare i log nella console Google Cloud , vai alla pagina Esplora log:

    Esplora log

  4. Consulta Messaggi di log per un servizio di backend per visualizzare le informazioni disponibili sulle voci di log di callout, inclusa la struttura del payload JSON per la voce di log del bilanciatore del carico service_extension_info. Puoi utilizzare il campo Cerca in Esplora log per filtrare le informazioni pertinenti.

    Il seguente esempio è una voce di log che potresti visualizzare per un callout ext-proc non riuscito: 

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

    Tieni presente che il campo grpcStatus mostra ABORTED.

Log dell'operatore APIM

L'operatore APIM è un operatore Kubernetes che elabora gli eventi delle risorse personalizzate APIM (ad esempio creazione, lettura, aggiornamento ed eliminazione) e li traduce nella configurazione Apigee appropriata.

Per visualizzare i log per l'operatore APIM:

  1. Per visualizzare i log nella console Google Cloud , vai alla pagina Esplora log:

    Esplora log

  2. Nel riquadro Query, inserisci una query simile alla seguente: 
    resource.type="k8s_container"
resource.labels.namespace_name="apim"
labels.k8s-pod/app="apigee-apim-operator" severity>=DEFAULT
  3. Fai clic su Esegui query.
  4. Le voci di log filtrate vengono visualizzate nel riquadro Risultati query.
  5. Prendi nota di eventuali problemi relativi alla creazione, all'aggiornamento o all'eliminazione di APIMExtensionPolicy nei servizi di rete Google Cloud o di problemi relativi ai prodotti API nei piani di gestione Apigee.

    Un esempio di errore potrebbe essere simile al seguente: 

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

Risolvere i problemi relativi agli errori di accesso 403 in APIM Operator

Se riscontri errori con codice di stato 403 che indicano problemi di accesso, verifica quanto segue:

  • Nel tuo cluster GKE è abilitata la federazione delle identità per i carichi di lavoro. La federazione delle identità per i carichi di lavoro è abilitata per impostazione predefinita per i cluster creati con la modalità Autopilot. Se hai creato un cluster utilizzando la modalità standard, abilita la federazione delle identità per i carichi di lavoro come descritto in Abilita la federazione delle identità per i carichi di lavoro per GKE.
  • L'account di servizio Kubernetes (apim-ksa) è annotato correttamente dall'installazione di Helm. Puoi verificarlo con il comando seguente: 
    kubectl describe serviceaccount apim-ksa -n NAMESPACE

    Dove NAMESPACE è lo spazio dei nomi in cui viene eseguito il deployment dell'operatore APIM.

    Verifica che apigee-apim-gsa@$PROJECT.iam.gserviceaccount.com venga visualizzato nel campo Annotazioni dell'output.

    Ad esempio: 

    kubectl describe serviceaccount apim-ksa -n apim

    L'output è simile al seguente: Name: apim-ksa Namespace: apim Labels: ... Annotations: iam.gke.io/gcp-service-account: apigee-apim-gsa@apigee-product-demo.iam.gserviceaccount.com ... Segreti di pull delle immagini: Segreti montabili: Token: Eventi:

  • L'account di servizio apigee-apim-gsa dispone dei ruoli e delle autorizzazioni IAM corretti. Puoi verificarlo con il comando seguente: 
     gcloud iam service-accounts get-iam-policy \
apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com

    Il account di servizio deve disporre del ruolo roles/iam.workloadIdentityUser.

    Ad esempio, l'output seguente mostra il ruolo roles/iam.workloadIdentityUser: 

    bindings:
- members:
  - serviceAccount:$PROJECT_ID.svc.id.goog[/apim-ksa]
  role: roles/iam.workloadIdentityUser
etag: BwYUpeaM7XQ=
version: 1
  • Non sono presenti condizioni IAM speciali sui ruoli richiesti, che impedirebbero l'accesso all'operatore.

Risolvere i problemi relativi al traffico di runtime di Apigee

Questa sezione descrive come risolvere i problemi relativi al traffico di runtime di Apigee. Le sezioni seguenti descrivono come risolvere i problemi relativi alle richieste valide e non valide.

Richieste valide non riuscite

Se non riesci a inviare richieste valide al runtime Apigee, potrebbero essere presenti i seguenti problemi:

  • Il gateway GKE non riesce a raggiungere il runtime Apigee.
  • La chiave API o le credenziali JWT non sono valide.
  • Il prodotto API Apigee non è configurato per la destinazione e l'ambiente corretti.
  • Il runtime Apigee non riconosce il prodotto API Apigee.

Passaggi per la risoluzione dei problemi

Per risolvere i problemi relativi alle richieste valide:

  • Attiva i log del bilanciatore del carico per il gateway GKE ed esamina i log per determinare la causa degli errori del callout dell'estensione. Per maggiori dettagli, consulta i log del gateway GKE.
  • Verifica che il servizio di backend a cui viene fatto riferimento dal servizio ext-proc sia integro.
  • Esamina la configurazione del prodotto API su Apigee:
    • Verifica che il prodotto API sia abilitato per l'ambiente corretto (ad esempio test o prod).
    • Verifica che il percorso della risorsa corrisponda alla tua richiesta. Un percorso come / o /** corrisponderà a qualsiasi percorso. Puoi anche utilizzare i caratteri jolly * o ** per la corrispondenza.
    • Verifica di aver configurato un'app per sviluppatori per il prodotto API. Il prodotto API deve essere associato a un'app per sviluppatori per convalidare le relative chiavi API.
  • Rivedi la tua richiesta al gateway:
    • Verifica che la chiave utente sia passata nell'intestazione x-api-key.
    • Assicurati che la chiave utente sia valida. Le credenziali dell'app per sviluppatori devono essere approvate per il tuo prodotto API.

Richieste non valide riuscite

Se le richieste non valide al runtime Apigee vanno a buon fine, potrebbero essere presenti i seguenti problemi:

  • FailOpen è impostato su true in APIMExtensionPolicy.
  • Non è impostata alcuna estensione del traffico per il bilanciatore del carico del gateway GKE.

Passaggi per la risoluzione dei problemi

Per risolvere i problemi relativi alle richieste non valide:

  • Verifica che esista un'estensione di servizio e che faccia riferimento ai servizi di backend e alla regola di forwarding corretti per il tuo gateway GKE.

    Utilizza questo comando per visualizzare l'estensione del servizio: 

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

    Dove:

    • NAME_OF_APIM_EXTENSION_POLICY: il nome della risorsa personalizzata APIMExtensionPolicy.
    • PROJECT: l'ID progetto.
    • LOCATION: la posizione del cluster GKE in cui viene eseguito il deployment del gateway.

    L'output sarà simile al seguente: 

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

    Analisi mancanti

    Se non riesci a visualizzare Apigee API Analytics per l'operatore APIM nella console Google Cloud , tieni presente che l'inserimento di Apigee può essere ritardato di alcuni minuti.

    Risorse aggiuntive

    Per risolvere i problemi relativi all'operatore APIM e al traffico di runtime di Apigee, puoi utilizzare anche le seguenti risorse: