Memecahkan masalah Operator Apigee APIM untuk Kubernetes

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

Baca dokumentasi Apigee Edge.

Halaman ini menjelaskan cara memecahkan masalah Operator APIM Apigee 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 Operator APIM Apigee 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 dihasilkan 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 keterangan:

  • 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 Operator APIM.

Log GKE Gateway

Saat Anda menerapkan APIMExtensionPolicy, Gateway GKE yang Anda buat di cluster 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 GKE Gateway.

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

  2. Ikuti langkah-langkah di Mengaktifkan logging di 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 guna melihat informasi entri log info yang tersedia, termasuk struktur payload JSON untuk entri log load balancer service_extension_info. Anda dapat menggunakan kolom Telusuri di Logs Explorer untuk memfilter informasi yang relevan.

    Contoh berikut adalah entri log yang mungkin Anda lihat untuk info 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}/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"
}

    Perhatikan bahwa kolom grpcStatus menampilkan ABORTED.

Log Operator APIM

Operator APIM adalah operator Kubernetes yang memproses peristiwa resource kustom APIM (seperti membuat, membaca, memperbarui, dan menghapus), serta menerjemahkan peristiwa tersebut dalam konfigurasi Apigee yang sesuai.

Untuk melihat log Operator APIM:

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

    Logs Explorer

  2. Di panel Kueri, 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 in Google Cloud networks atau masalah terkait Produk API di platform pengelolaan Apigee.

    Contoh error akan terlihat seperti berikut: 

    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, konfirmasi hal berikut:

  • Cluster GKE Anda telah mengaktifkan workload identity federation. Federasi identitas beban kerja 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 mengonfirmasinya dengan perintah berikut: 
    kubectl describe serviceaccount apim-ksa -n NAMESPACE

    Dengan NAMESPACE adalah namespace tempat Operator APIM di-deploy.

    Pastikan apigee-apim-gsa@${PROJECT}.iam.gserviceaccount.com muncul di kolom Annotations pada output.

    Contoh: 

    kubectl describe serviceaccount apim-ksa -n apim

    Outputnya mirip dengan yang berikut ini: 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:

  • Akun layanan apigee-apim-gsa memiliki peran dan izin IAM yang benar. Anda dapat mengonfirmasinya dengan perintah berikut: 
     gcloud iam service-accounts get-iam-policy \
apigee-apim-gsa@${PROJECT}.iam.gserviceaccount.com

    Akun layanan harus memiliki peran roles/iam.workloadIdentityUser.

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

    bindings:
- members:
  - serviceAccount:${PROJECT}.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 valid gagal

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

  • GKE Gateway tidak dapat menjangkau runtime Apigee.
  • Kredensial Kunci API atau JWT 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 panggilan 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.
    • Pastikan Anda memiliki Aplikasi Developer yang dikonfigurasi untuk Produk API. Produk API harus terikat dengan 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 yang tidak valid ke runtime Apigee berhasil, 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 yang 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 keterangan:

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

    Outputnya akan mirip dengan berikut 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
    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 Analytics API Apigee untuk Operator APIM di konsol Google Cloud, perhatikan bahwa proses pengambilan data Apigee dapat tertunda beberapa menit.

    Referensi lainnya

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