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 dell'operatore APIM di Apigee per Kubernetes. Esistono diversi strumenti disponibili 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 status con due campi:

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

Quando un file yaml della risorsa personalizzata viene applicato al cluster, Kubernetes apporta le modifiche corrispondenti all'infrastruttura di base. La verifica dell'oggetto dello stato della risorsa personalizzata può fornire informazioni sullo stato della risorsa e mostrare eventuali errori risultanti se le operazioni di infrastruttura sottostanti non riescono.

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 è dipiattata la 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 Operator APIM.

Log di GKE Gateway

Quando applici APIMExtensionPolicy, il gateway GKE che hai creato nel tuo cluster è configurato con un'estensione del traffico. L'estensione utilizza l'elaborazione esterna di Kubernetes (ext-proc) per chiamare il runtime di Apigee e i criteri di elaborazione. I log relativi al traffico ext-proc possono essere utili per la risoluzione dei problemi.

Visualizza i log per i callout ext-proc

Per visualizzare i log relativi al traffico dei callout ext-proc:

  1. Recupera l'ID del servizio di backend creato per il runtime Apigee: 
    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. Per abilitare il logging, segui i passaggi descritti in Abilita il logging su un servizio di backend.
  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 sulle voci di log dei callout disponibili, 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.

    Di seguito è riportato un esempio di 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}/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"
}

    Tieni presente che il campo grpcStatus mostra ABORTED.

Log di APIM Operator

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

Per visualizzare i log di APIM Operator:

  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 dei servizi APIMExtensionPolicy in Google Cloud networks o 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 gli errori di accesso 403 in APIM Operator

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

  • Nel 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 Attivare 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 verificare questa informazione con il comando seguente: 
    kubectl describe serviceaccount apim-ksa -n NAMESPACE

    dove NAMESPACE è lo spazio dei nomi in cui è dipiegato l'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 ... Image pull secrets: Mountable secrets: Tokens: Events:

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

    Il service account deve avere il ruolo roles/iam.workloadIdentityUser.

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

    bindings:
- members:
  - serviceAccount:${PROJECT}.svc.id.goog[/apim-ksa]
  role: roles/iam.workloadIdentityUser
etag: BwYUpeaM7XQ=
version: 1
  • Nei ruoli richiesti non sono presenti condizioni IAM speciali che impediranno all'operatore di accedere.

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 verificarsi i seguenti problemi:

  • La porta di accesso GKE non riesce a raggiungere il runtime Apigee.
  • Le tue credenziali JWT o della chiave API non sono valide.
  • Il prodotto API Apigee non è configurato per il target e l'ambiente corretti.
  • Il runtime Apigee non è a conoscenza del 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 la porta di accesso GKE ed esaminali per determinare la causa degli errori dal callout dell'estensione. Per ulteriori dettagli, consulta i log di GKE Gateway.
  • Verifica che il servizio di backend a cui fa riferimento il 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 avere 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 richiesta inviata al gateway:
    • Verifica che la chiave utente venga passata nell'intestazione x-api-key.
    • Assicurati che la chiave consumer sia valida. Le credenziali dell'app per sviluppatori devono essere approvate per il tuo prodotto API.

Le richieste non valide vanno a buon fine

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 di GKE Gateway.

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 inoltro corretti per il tuo gateway GKE.

    Utilizza il seguente 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 è dipiegato il 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
    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

    Dati e analisi mancanti

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

    Risorse aggiuntive

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