Memecahkan masalah Operator Apigee APIM untuk Kubernetes

Halaman ini berlaku untuk Apigee, tetapi tidak untuk Apigee Hybrid.

Lihat dokumentasi Apigee Edge.

Halaman ini menjelaskan cara memecahkan masalah Apigee APIM Operator untuk Kubernetes. Ada sejumlah alat yang tersedia untuk mengatasi masalah yang mungkin Anda alami. Halaman ini menjelaskan cara memeriksa status resource kustom, menggunakan Logs Explorer, dan memecahkan masalah terkait traffic runtime Apigee.

Memeriksa status resource kustom

Setiap resource kustom yang digunakan di Apigee APIM Operator untuk Kubernetes berisi objek status dengan dua kolom:

  • STATE: Menjelaskan status resource. Nilai mencakup running dan created.
  • ERRORMESSAGE: Jika operasi resource gagal, kolom pesan error akan diisi dengan pesan penjelasan.

Saat file yaml resource kustom diterapkan ke cluster, Kubernetes akan membuat perubahan yang sesuai pada infrastruktur yang mendasarinya. Memeriksa objek status resource kustom dapat memberikan informasi tentang status resource dan menampilkan error yang terjadi jika operasi infrastruktur yang mendasarinya gagal.

Anda dapat memeriksa status resource kustom dengan perintah berikut:

kubectl -n NAMESPACE get CUSTOM_RESOURCE_KIND CUSTOM_RESOURCE_NAME

Dengan:

  • NAMESPACE: Namespace tempat resource kustom di-deploy.
  • CUSTOM_RESOURCE_KIND: Jenis resource kustom.
  • CUSTOM_RESOURCE_NAME: Nama resource kustom.

Misalnya, perintah berikut memeriksa status resource kustom APIMExtensionPolicy bernama apim-extension-policy di namespace apim:

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

Outputnya mirip dengan hal berikut ini:

NAME                      STATE                  ERRORMESSAGE
apim-extension-policy     Create_Update_Failed   Permission denied

Melihat log

Bagian ini menjelaskan cara menggunakan log untuk memecahkan masalah resource Gateway Google Kubernetes Engine (GKE) dan resource APIM Operator.

Log GKE Gateway

Saat Anda menerapkan APIMExtensionPolicy, GKE Gateway yang Anda buat di cluster Anda akan dikonfigurasi dengan ekstensi traffic. Ekstensi ini menggunakan pemrosesan eksternal Kubernetes (ext-proc) untuk memanggil runtime Apigee dan memproses kebijakan. Log yang terkait dengan traffic ext-proc dapat berguna saat memecahkan masalah.

Melihat log untuk info ext-proc

Untuk melihat log traffic info ext-proc:

  1. Dapatkan ID layanan backend yang dibuat untuk runtime Apigee:
    kubectl get gateways.gateway.networking.k8s.io GATEWAY_NAME
      -o=jsonpath="{.metadata.annotations.networking\.gke\.io/backend-services}"

    Dengan GATEWAY_NAME adalah nama Gateway GKE.

    Layanan backend akan berisi apigee-service-extension-backend-service di ID.

  2. Ikuti langkah-langkah di Mengaktifkan logging pada layanan backend untuk mengaktifkan logging.
  3. Untuk melihat log di konsol Google Cloud , buka halaman Logs Explorer:

    Logs Explorer

  4. Tinjau Pesan log untuk layanan backend untuk melihat informasi entri log anotasi yang tersedia, termasuk struktur payload JSON untuk entri log load balancer service_extension_info. Anda dapat menggunakan kolom Penelusuran di Logs Explorer untuk memfilter informasi yang relevan.

    Contoh berikut adalah entri log yang mungkin Anda lihat untuk panggilan ext-proc yang gagal:

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

    Perhatikan bahwa kolom grpcStatus menampilkan ABORTED.

Log Operator APIM

Operator APIM adalah operator Kubernetes yang memproses peristiwa resource kustom APIM (seperti buat, baca, perbarui, dan hapus), serta menerjemahkan peristiwa tersebut dalam konfigurasi Apigee yang sesuai.

Untuk melihat log untuk Operator APIM:

  1. Untuk melihat log di konsol Google Cloud , buka halaman Logs Explorer:

    Logs Explorer

  2. Di Query pane, masukkan kueri yang mirip dengan berikut:
    resource.type="k8s_container"
    resource.labels.namespace_name="apim"
    labels.k8s-pod/app="apigee-apim-operator" severity>=DEFAULT
    
  3. Klik Run query.
  4. Entri log yang difilter ditampilkan di panel Query results.
  5. Catat masalah apa pun terkait pembuatan, pembaruan, atau penghapusan layanan APIMExtensionPolicy dalam Google Cloud jaringan atau masalah terkait Produk API di bidang pengelolaan Apigee.

    Contoh error akan terlihat mirip dengan berikut ini:

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

Memecahkan masalah error akses 403 di Operator APIM

Jika Anda menemukan error kode status 403 yang menunjukkan masalah akses, pastikan hal berikut:

  • Cluster GKE Anda telah mengaktifkan workload identity federation. Workload identity federation diaktifkan secara default untuk cluster yang dibuat dengan mode autopilot. Jika Anda membuat cluster menggunakan mode standar, jika Anda menggunakan cluster standar, aktifkan workload identity federation seperti yang dijelaskan dalam Mengaktifkan Workload Identity Federation untuk GKE.
  • Akun layanan Kubernetes (apim-ksa) dianotasi dengan benar oleh penginstalan Helm. Anda dapat mengonfirmasi hal ini dengan perintah berikut:
    kubectl describe serviceaccount apim-ksa -n NAMESPACE

    Dengan NAMESPACE adalah namespace tempat APIM Operator di-deploy.

    Pastikan apigee-apim-gsa@$PROJECT. muncul di kolom Anotasi output.

    Contoh:

    kubectl describe serviceaccount apim-ksa -n apim

    Outputnya mirip dengan berikut ini: Name: apim-ksa Namespace: apim Labels: ... Annotations: iam.gke.io/gcp-service-account: apigee-apim-gsa@apigee-product-demo. ... Image pull secrets: Mountable secrets: Tokens: Events:

  • Akun layanan apigee-apim-gsa memiliki peran dan izin IAM yang benar. Anda dapat mengonfirmasi hal ini dengan perintah berikut:
     gcloud iam service-accounts get-iam-policy \
    apigee-apim-gsa@$PROJECT_ID.

    Akun layanan harus memiliki peran roles/iam.workloadIdentityUser.

    Misalnya, output berikut menunjukkan peran roles/iam.workloadIdentityUser:

    bindings:
    - members:
      - serviceAccount:$PROJECT_ID.svc.id.goog[/apim-ksa]
      role: roles/iam.workloadIdentityUser
    etag: BwYUpeaM7XQ=
    version: 1
    
  • Tidak ada kondisi IAM khusus pada peran yang diperlukan, yang akan mencegah akses untuk operator.

Memecahkan masalah terkait traffic runtime Apigee

Bagian ini menjelaskan cara memecahkan masalah terkait traffic runtime Apigee. Bagian berikut menjelaskan cara memecahkan masalah terkait permintaan yang valid dan tidak valid.

Permintaan yang valid gagal

Jika Anda tidak dapat mengirim permintaan yang valid ke runtime Apigee, mungkin ada masalah berikut:

  • GKE Gateway tidak dapat menjangkau runtime Apigee.
  • Kredensial JWT atau Kunci API Anda tidak valid.
  • Produk API Apigee tidak dikonfigurasi untuk target dan lingkungan yang benar.
  • Runtime Apigee tidak mengetahui Produk API Apigee.

Langkah pemecahan masalah

Untuk memecahkan masalah terkait permintaan yang valid:

  • Aktifkan log load balancer untuk GKE Gateway dan tinjau log untuk menentukan penyebab kegagalan dari anotasi ekstensi. Lihat log GKE Gateway untuk mengetahui detail selengkapnya.
  • Pastikan layanan backend yang dirujuk dari layanan ext-proc responsif.
  • Tinjau konfigurasi Produk API di Apigee:
    • Pastikan produk API diaktifkan untuk lingkungan yang benar (misalnya, test atau prod).
    • Pastikan jalur resource cocok dengan permintaan Anda. Jalur seperti / atau /** akan cocok dengan jalur apa pun. Anda juga dapat menggunakan karakter pengganti * atau ** untuk pencocokan.
    • Konfirmasi bahwa Anda telah mengonfigurasi Aplikasi Developer untuk Produk API. Produk API harus terikat ke Aplikasi Developer untuk memvalidasi kunci API-nya.
  • Tinjau permintaan Anda ke Gateway:
    • Pastikan Kunci Konsumen diteruskan di header x-api-key.
    • Pastikan Kunci Konsumen valid. Kredensial dari Aplikasi Developer harus disetujui untuk Produk API Anda.

Permintaan tidak valid berhasil

Jika permintaan tidak valid ke runtime Apigee Anda berhasil, maka masalah berikut mungkin terjadi:

  • FailOpen ditetapkan ke true di APIMExtensionPolicy Anda.
  • Tidak ada ekstensi traffic yang ditetapkan untuk load balancer GKE Gateway Anda.

Langkah pemecahan masalah

Untuk memecahkan masalah terkait permintaan tidak valid:

  • Pastikan ekstensi layanan ada dan mereferensikan layanan backend dan aturan penerusan yang benar untuk GKE Gateway Anda.

    Gunakan perintah berikut untuk melihat ekstensi layanan:

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

    Dengan:

    • NAME_OF_APIM_EXTENSION_POLICY: Nama resource kustom APIMExtensionPolicy.
    • PROJECT: Project ID.
    • LOCATION: Lokasi cluster GKE tempat Gateway Anda di-deploy.

    Outputnya akan seperti ini:

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

    Analisis tidak ada

    Jika Anda tidak dapat melihat Analisis API Apigee untuk Operator APIM di konsol, perhatikan bahwa penyerapan Apigee dapat tertunda selama beberapa menit. Google Cloud

    Referensi lainnya

    Referensi berikut juga dapat digunakan untuk memecahkan masalah pada Operator APIM dan traffic runtime Apigee: