本頁面由 Cloud Translation API 翻譯而成。

排解 Kubernetes 適用的 Apigee APIM Operator 問題

本頁內容適用於 Apigee，但不適用於 Apigee Hybrid。

查看 Apigee Edge 說明文件。

本頁說明如何排解 Kubernetes 適用的 Apigee APIM 運算子問題。您可以運用多種工具解決遇到的問題。本頁說明如何檢查自訂資源的狀態、使用記錄檔瀏覽器，以及排解 Apigee 執行階段流量的問題。

檢查自訂資源狀態

在 Kubernetes 適用的 Apigee APIM 運算子中使用的每個自訂資源，都包含具有兩個欄位的狀態物件：

STATE：說明資源的狀態。值包括 running 和 created。
ERRORMESSAGE：如果資源作業失敗，錯誤訊息欄位會填入說明訊息。

將自訂資源 yaml 檔案套用至叢集時，Kubernetes 會對基礎架構進行相應變更。檢查自訂資源的狀態物件，可提供資源狀態的相關資訊，並在基礎架構作業失敗時顯示任何產生的錯誤。

您可以使用下列指令檢查自訂資源狀態：

kubectl -n NAMESPACE get CUSTOM_RESOURCE_KIND CUSTOM_RESOURCE_NAME

其中：

NAMESPACE：部署自訂資源的命名空間。
CUSTOM_RESOURCE_KIND：自訂資源的種類。
CUSTOM_RESOURCE_NAME：自訂資源的名稱。

舉例來說，下列指令會檢查 apim 命名空間中，名為 apim-extension-policy 的 APIMExtensionPolicy 自訂資源狀態：

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

輸出結果會與下列內容相似：

NAME                      STATE                  ERRORMESSAGE
apim-extension-policy     Create_Update_Failed   Permission denied

查看記錄

本節說明如何使用記錄，排解 Google Kubernetes Engine (GKE) Gateway 資源和 APIM Operator 資源的問題。

GKE 閘道記錄

套用 APIMExtensionPolicy 時，系統會使用流量擴充功能設定您在叢集中建立的 GKE Gateway。擴充功能會使用 Kubernetes 外部處理 (ext-proc) 呼叫 Apigee 執行階段並處理政策。與 ext-proc 流量相關的記錄有助於排解問題。

查看 `ext-proc` 標註的記錄檔

如要查看 ext-proc 呼叫流量的記錄：

取得為 Apigee 執行階段建立的後端服務 ID：
```
kubectl get gateways.gateway.networking.k8s.io GATEWAY_NAME
  -o=jsonpath="{.metadata.annotations.networking\.gke\.io/backend-services}"
```
其中 GATEWAY_NAME 是 GKE 閘道的名稱。

後端服務的 ID 會包含 apigee-service-extension-backend-service。
按照「啟用後端服務的記錄功能」中的步驟操作，啟用記錄功能。
如要在 Google Cloud 控制台中查看記錄，請前往「Logs Explorer」頁面：
記錄檔探索工具

請參閱「後端服務的記錄訊息」，查看可用的呼叫記錄項目資訊，包括 service_extension_info 負載平衡器記錄項目的 JSON 酬載結構。您可以使用記錄探索器中的「搜尋」欄位，篩選出相關資訊。

以下範例是 ext-proc 呼叫失敗時可能看到的記錄項目：

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

請注意，grpcStatus 欄位會顯示 ABORTED。

APIM Operator 記錄

APIM Operator 是 Kubernetes 運算子，可處理 APIM 自訂資源事件 (例如建立、讀取、更新和刪除)，並將這些事件轉換為適當的 Apigee 設定。

如要查看 APIM 運算子的記錄，請執行下列操作：

如要在 Google Cloud 控制台中查看記錄，請前往「Logs Explorer」頁面：
記錄檔探索工具

在「Query」(查詢) 窗格中，輸入類似下列的查詢：

resource.type="k8s_container"
resource.labels.namespace_name="apim"
labels.k8s-pod/app="apigee-apim-operator" severity>=DEFAULT

點選「執行查詢」
篩選後的記錄項目會顯示在「Query results」(查詢結果) 窗格中。

請記下建立、更新或刪除APIMExtensionPolicy Google Cloud 網路服務時發生的任何問題，或是 Apigee 管理平面中的 API 產品問題。

錯誤範例如下：

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

排解 APIM Operator 中的 403 存取錯誤

如果發現狀態碼 403 錯誤，表示存取權有問題，請確認下列事項：

GKE 叢集已啟用工作負載身分聯盟。以 Autopilot 模式建立的叢集預設會啟用 Workload Identity 聯盟。如果您使用標準模式建立叢集，請按照「為 GKE 啟用工作負載身分聯盟」一文的說明，啟用工作負載身分聯盟。
Helm 安裝作業會正確註解 Kubernetes 服務帳戶 (apim-ksa)。您可以使用下列指令確認：
```
kubectl describe serviceaccount apim-ksa -n NAMESPACE
```
其中 NAMESPACE 是部署 APIM 運算子的命名空間。

確認輸出內容的「Annotations」欄位中顯示 apigee-apim-gsa@$PROJECT.iam.gserviceaccount.com。
例如：
```
kubectl describe serviceaccount apim-ksa -n apim
```
輸出內容如下所示： 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:

apigee-apim-gsa 服務帳戶具備正確的 IAM 角色和權限。您可以使用下列指令確認：

 gcloud iam service-accounts get-iam-policy \
apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com

服務帳戶必須具備 roles/iam.workloadIdentityUser 角色。

舉例來說，下列輸出內容顯示 roles/iam.workloadIdentityUser 角色：

bindings:
- members:
  - serviceAccount:$PROJECT_ID.svc.id.goog[/apim-ksa]
  role: roles/iam.workloadIdentityUser
etag: BwYUpeaM7XQ=
version: 1

必要角色沒有特殊的 IAM 條件，因此不會阻礙作業人員存取。

排解 Apigee 執行階段流量問題

本節說明如何排解 Apigee 執行階段流量問題。下列各節說明如何排解有效和無效要求的問題。

有效要求失敗

如果無法將有效要求傳送至 Apigee 執行階段，可能是發生下列問題：

GKE Gateway 無法連線至 Apigee 執行階段。
您的 API 金鑰或 JWT 憑證無效。
Apigee API 產品未針對正確的目標和環境設定。
Apigee 執行階段不會辨識 Apigee API 產品。

疑難排解步驟

如要排解有效要求的問題，請採取下列做法：

為 GKE Gateway 啟用負載平衡器記錄，並查看記錄，判斷擴充功能呼叫失敗的原因。詳情請參閱 GKE 閘道記錄。
確認 ext-proc 服務參照的後端服務健康狀態良好。
在 Apigee 上檢查 API 產品設定：
- 確認 API 產品已在正確的環境 (例如 test 或 prod) 中啟用。
- 確認資源路徑與要求相符。/ 或 /** 等路徑會比對任何路徑。您也可以使用 * 或 ** 萬用字元進行比對。
- 確認您已為 API 產品設定開發人員應用程式。API 產品必須繫結至開發人員應用程式，才能驗證 API 金鑰。
查看對閘道的要求：
- 確認 Consumer Key 是否已傳遞至 x-api-key 標頭。
- 請確認消費者金鑰是否有效。開發人員應用程式的憑證必須通過 API 產品核准。

無效請求成功

如果對 Apigee 執行階段的無效要求成功，則可能存在下列問題：

在 APIMExtensionPolicy 中，FailOpen 設為 true。
GKE Gateway 的負載平衡器未設定流量擴充功能。

疑難排解步驟

如要排解無效要求的問題，請按照下列步驟操作：

確認服務擴充功能存在，並參照 GKE Gateway 的正確後端服務和轉送規則。

使用下列指令查看服務擴充功能：

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

其中：

NAME_OF_APIM_EXTENSION_POLICY：APIMExtensionPolicy自訂資源名稱。
PROJECT：專案 ID。
LOCATION：部署 Gateway 的 GKE 叢集位置。

輸出內容會與下列內容相似：

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

缺少數據分析

如果無法在 Google Cloud 控制台中查看 APIM Operator 的 Apigee API Analytics，請注意，Apigee 擷取資料可能會延遲幾分鐘。

其他資源

您也可以使用下列資源，排解 APIM Operator 和 Apigee 執行階段流量的問題：

排解 Kubernetes 適用的 Apigee APIM Operator 問題 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

檢查自訂資源狀態

查看記錄

GKE 閘道記錄

查看 ext-proc 標註的記錄檔

APIM Operator 記錄

排解 APIM Operator 中的 403 存取錯誤

排解 Apigee 執行階段流量問題

有效要求失敗

疑難排解步驟

無效請求成功

疑難排解步驟

缺少數據分析

其他資源

排解 Kubernetes 適用的 Apigee APIM Operator 問題

查看 `ext-proc` 標註的記錄檔