このページは Cloud Translation API によって翻訳されました。

Kubernetes 用の Apigee APIM Operator のトラブルシューティング

このページの内容は Apigee に適用されます。Apigee ハイブリッドには適用されません。

Apigee Edge のドキュメントを表示する。

このページでは、Kubernetes 用の Apigee APIM Operator のトラブルシューティング方法について説明します。発生する可能性のある問題を解決するためのツールがいくつかあります。このページでは、カスタムリソースのステータスを確認する方法、ログエクスプローラを使用する方法、Apigee ランタイムトラフィックに関する問題のトラブルシューティングを行う方法について説明します。

カスタムリソースのステータスを確認する

Apigee APIM Operator for Kubernetes で使用されるすべてのカスタムリソースには、次の 2 つのフィールドを含むステータスオブジェクトが含まれています。

STATE: リソースの状態を表します。値には running と created があります。
ERRORMESSAGE: リソースオペレーションが失敗すると、エラーメッセージフィールドに説明メッセージが入力されます。

カスタムリソース yaml ファイルがクラスタに適用されると、Kubernetes は基盤となるインフラストラクチャに対応する変更を加えます。カスタムリソースのステータスオブジェクトを確認すると、リソースの状態に関する情報を取得し、基盤となるインフラストラクチャオペレーションでエラーが発生した場合にそのエラーを検出できます。

カスタムリソースのステータスは、次のコマンドで確認できます。

kubectl -n NAMESPACE get CUSTOM_RESOURCE_KIND CUSTOM_RESOURCE_NAME

ここで

NAMESPACE: カスタムリソースがデプロイされる Namespace。
CUSTOM_RESOURCE_KIND: カスタムリソースの種類。
CUSTOM_RESOURCE_NAME: カスタムリソースの名前。

たとえば、次のコマンドは、apim Namespace 内の 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 Gateway のログ

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 Gateway の名前です。

バックエンドサービスの ID には apigee-service-extension-backend-service が含まれます。
バックエンドサービスでロギングを有効にするの手順に沿って、ロギングを有効にします。
Google Cloud コンソールでログを表示するには、[ログエクスプローラ] ページに移動します。
ログエクスプローラ

バックエンドサービスのログメッセージを確認して、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}/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"
}

grpcStatus フィールドには ABORTED が表示されます。

APIM オペレーターログ

APIM Operator は、APIM カスタムリソースイベント（作成、読み取り、更新、削除など）を処理し、適切な Apigee 構成でそれらのイベントを変換する Kubernetes オペレーターです。

APIM Operator のログを表示するには:

Google Cloud コンソールでログを表示するには、[ログエクスプローラ] ページに移動します。
ログエクスプローラ

[クエリペイン] に、次のようなクエリを入力します。

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

[クエリを実行] をクリックします。
フィルタされたログエントリが [クエリ結果] ペインに表示されます。

Google Cloud networks サービスでの APIMExtensionPolicy の作成、更新、削除に関する問題や、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 オペレーターで 403 アクセスエラーのトラブルシューティングを行う

アクセスの問題を示すステータスコード 403 エラーが見つかった場合は、次の点を確認してください。

GKE クラスタで Workload Identity 連携が有効になっている。Workload Identity 連携は、Autopilot モードで作成されたクラスタでデフォルトで有効になっています。標準モードを使用してクラスタを作成した場合、または標準クラスタを使用している場合は、 GKE 用 Workload Identity 連携を有効にするで説明されているように、Workload Identity 連携を有効にします。
Kubernetes サービスアカウント（apim-ksa）に Helm インストールによって正しくアノテーションが付けられています。これは次のコマンドで確認できます。
```
kubectl describe serviceaccount apim-ksa -n NAMESPACE
```
ここで、NAMESPACE は APIM Operator がデプロイされている Namespace です。

出力の [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}.iam.gserviceaccount.com
```
サービスアカウントには roles/iam.workloadIdentityUser ロールが必要です。

たとえば、次の出力は roles/iam.workloadIdentityUser ロールを示しています。
```
bindings:
- members:
  - serviceAccount:${PROJECT}.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 Gateway ログをご覧ください。
ext-proc サービスから参照されるバックエンドサービスが正常であることを確認します。
Apigee で API プロダクトの構成を確認します。
- API プロダクトが正しい環境（test や prod など）で有効になっていることを確認します。
- リソースパスがリクエストと一致していることを確認します。/ や /** のようなパスは、どのパスとも一致します。マッチングには、ワイルドカード * または ** を使用することもできます。
- API プロダクトにデベロッパーアプリが構成されていることを確認します。API キーを検証するには、API プロダクトがデベロッパーアプリにバインドされている必要があります。
Gateway へのリクエストを確認します。
- コンシューマキーが x-api-key ヘッダーで渡されていることを確認します。
- コンシューマキーが有効であることを確認します。デベロッパーアプリの認証情報が、API プロダクトに対して承認されている必要があります。

無効なリクエストが成功する

Apigee ランタイムへの無効なリクエストが成功した場合は、次の問題が発生している可能性があります。

FailOpen は、APIMExtensionPolicy で 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
    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 オペレーターの Apigee API アナリティクスを表示できない場合は、Apigee の取り込みが数分遅れることがあります。

参考情報

APIM Operator と Apigee ランタイムトラフィックに関する問題のトラブルシューティングには、次のリソースも使用できます。

Kubernetes 用の Apigee APIM Operator のトラブルシューティング

カスタム リソースのステータスを確認する

ログを表示

GKE Gateway のログ

ext-proc コールアウトのログを表示する

APIM オペレーター ログ

APIM オペレーターで 403 アクセス エラーのトラブルシューティングを行う

Apigee ランタイム トラフィックに関する問題のトラブルシューティング

有効なリクエストが失敗する

トラブルシューティング手順

無効なリクエストが成功する

トラブルシューティング手順

分析が表示されない

参考情報

カスタムリソースのステータスを確認する

`ext-proc` コールアウトのログを表示する

APIM オペレーターログ

APIM オペレーターで 403 アクセスエラーのトラブルシューティングを行う

Apigee ランタイムトラフィックに関する問題のトラブルシューティング