Apigee ハイブリッドが作成状態またはリリース状態から先に進まない場合のトラブルシューティング

現在、Apigee と Apigee ハイブリッドのドキュメントが表示されています。
このトピックに対応する Apigee Edge のドキュメントはありません。

このドキュメントでは、Apigee ハイブリッド コンポーネントが creating や releasing 状態から動かない場合に、そのコンポーネントをリセットする方法について説明します。

Apigee ハイブリッド インストールのメイン コンポーネントは、次のコマンドを実行して一覧表示します。

kubectl get crd | grep apigee

apigeeorganization (apigeeorganizations.apigee.cloud.google.com)
apigeeenvironment (apigeeenvironments.apigee.cloud.google.com)
apigeedatastore (apigeedatastores.apigee.cloud.google.com)
apigeetelemetries (apigeetelemetries.apigee.cloud.google.com)
apigeeredis (apigeeredis.apigee.cloud.google.com)

現在の状態は、次のコマンドを実行して表示します。

kubectl get apigeedatastore -n NAMESPACE

すべてが機能している場合、こうしたコンポーネントそれぞれは、running 状態になります。次に例を示します。

NAME      STATE     AGE
default   running   5d6h

インストールが失敗すると、コンポーネントは、creating（または releasing）状態のまま変化しなくなることがあります。次に例を示します。

NAME      STATE     AGE
default   creating   5d6h

問題を特定する

問題の原因を特定するには、まず各コンポーネントの詳細を表示します。各コンポーネントは、次のように構成されています。

各 ApigeeOrganization カスタム リソースは、次の階層構造で表されます。

ApigeeOrganization/HASHED_VALUE
├─ApigeeDeployment/apigee-connect-agent-HASHED_VALUE
│ ├─HorizontalPodAutoscaler/apigee-connect-agent-HASHED_VALUE-VER-xxxx
│ ├─PodDisruptionBudget/apigee-connect-agent-HASHED_VALUE
│ ├─ReplicaSet/apigee-connect-agent-HASHED_VALUE-VER-xxxx
│ │ └─Pod/apigee-connect-agent-HASHED_VALUE-VER-xxxx
├─ApigeeDeployment/apigee-mart-HASHED_VALUE
│ ├─HorizontalPodAutoscaler/apigee-mart-HASHED_VALUE-VER-xxxx
│ ├─PodDisruptionBudget/apigee-mart-HASHED_VALUE
│ ├─ReplicaSet/apigee-mart-HASHED_VALUE-VER-xxxx
│ │ └─Pod/apigee-mart-HASHED_VALUE-VER-xxxx
├─ApigeeDeployment/apigee-watcher-HASHED_VALUE
│ ├─HorizontalPodAutoscaler/apigee-watcher-HASHED_VALUE-VER-xxxx
│ ├─PodDisruptionBudget/apigee-watcher-HASHED_VALUE
│ ├─ReplicaSet/apigee-watcher-HASHED_VALUE-VER-xxxx
│ │ └─Pod/apigee-watcher-HASHED_VALUE-VER-xxxx

各 ApigeeEnvironment カスタム リソースは、次の階層構造で表されます。

ApigeeEnvironment/HASHED_VALUE
├─ApigeeDeployment/apigee-runtime-HASHED_VALUE
│ ├─HorizontalPodAutoscaler/apigee-runtime-HASHED_VALUE-VER-xxxx
│ ├─PodDisruptionBudget/apigee-runtime-HASHED_VALUE
│ ├─ReplicaSet/apigee-runtime-HASHED_VALUE-VER-xxxx
│ │ └─Pod/apigee-runtime-HASHED_VALUE-VER-xxxx
├─ApigeeDeployment/apigee-synchronizer-HASHED_VALUE
│ ├─HorizontalPodAutoscaler/apigee-synchronizer-HASHED_VALUE-VER-xxxx
│ ├─PodDisruptionBudget/apigee-synchronizer-HASHED_VALUE
│ ├─ReplicaSet/apigee-synchronizer-HASHED_VALUE-VER-xxxx
│ │ └─Pod/apigee-synchronizer-HASHED_VALUE-VER-xxxx
├─ApigeeDeployment/apigee-udca-HASHED_VALUE
│ ├─HorizontalPodAutoscaler/apigee-udca-HASHED_VALUE-VER-xxxx
│ ├─PodDisruptionBudget/apigee-udca-HASHED_VALUE
│ ├─ReplicaSet/apigee-udca-HASHED_VALUE-VER-xxxx
│ │ └─Pod/apigee-udca-HASHED_VALUE-VER-xxxx

問題の特定は、ルート コンポーネントの詳細を表示することから開始します。次に例を示します。

kubectl describe apigeeorganization -n NAMESPACE COMPONENT_NAME

コンポーネントの State が running であるかどうかを確認します。

      Replicas:
        Available:  1
        Ready:      1
        Total:      1
        Updated:    1
      State:        running
  State:            running
Events:             <none>

このレベルでロギングされたイベントがない場合は、apigeedeployments の後に ReplicaSet を続けてこのプロセスを繰り返します。次に例を示します。

kubectl get apigeedeployment -n NAMESPACE AD_NAME>

apigeedeployments と ReplicaSet でエラーが表示されない場合は、準備ができていない Pod に注目します。

kubectl get pods -n NAMESPACE

NAME                                                              READY   STATUS
apigee-cassandra-default-0                                        1/1     Running
apigee-connect-agent-apigee-b56a362-150rc2-42gax-dbrrn            1/1     Running
apigee-logger-apigee-telemetry-s48kb                              1/1     Running
apigee-mart-apigee-b56a362-150rc2-bcizm-7jv6w                     0/2     Running
apigee-runtime-apigee-test-0d59273-150rc2-a5mov-dfb29             0/1     Running

この例では、mart と runtime の準備ができていません。Pod ログを検査してエラーを特定します。

kubectl logs -n NAMESPACE POD_NAME

コンポーネントの削除

これらのコンポーネントに間違いがあった場合は、そのコンポーネントを削除して apigeectl を適用します。たとえば、環境を削除するには、次のようにします。

kubectl delete -n apigee apigeeenv HASHED_ENV_NAME

必要な変更を行ってから、次のようにして環境を作成します。

apigeectl apply -f overrides.yaml –env=$ENV

コントローラを検査する

Pod に明白なエラー メッセージがなく、コンポーネントが running 状態に移行していない場合は、apigee-controller にエラー メッセージがないか確認します。apigee-controller は apigee-system Namespace で実行されます。

kubectl logs -n apigee-system $(k get pods -n apigee-system | sed -n '2p' | awk '{print $1}') | grep -i error

これにより、コントローラがリクエスト（create / delete / update など）を処理できなかった理由を確認できます。

Apigee データストア

Apache Cassandra は StatefulSet として実装されます。各 Cassandra インスタンスには次のものが含まれています。 

ApigeeDatastore/default
├─Certificate/apigee-cassandra-default
│ └─CertificateRequest/apigee-cassandra-default-wnd7s
├─Secret/config-cassandra-default
├─Service/apigee-cassandra-default
│ ├─EndpointSlice/apigee-cassandra-default-7m9kx
│ └─EndpointSlice/apigee-cassandra-default-gzqpr
└─StatefulSet/apigee-cassandra-default
  ├─ControllerRevision/apigee-cassandra-default-6976b77bd
  ├─ControllerRevision/apigee-cassandra-default-7fc76588cb
  └─Pod/apigee-cassandra-default-0

この例では、1 つの Pod を示しています。ただし、一般的な本番環境のインストールには、3 つ以上の Pod が含まれています。

Cassandra の状態が creating または releasing の場合は、状態をリセットする必要があります。Cassandra パスワードの変更などの特定の問題と、ネットワーキングに関係のない問題では、コンポーネントの削除が必要になる場合があります。このような場合、インスタンスを削除できない可能性があります（kubectl delete apigeedatastore -n NAMESPACE default）。--force や --grace-period=0 を使用しても解決しません。

reset の目的は、コンポーネント（apigeedatastore）の状態を creating または releasing から running に戻すことです。この方法で状態を変更しても、通常は根本的な問題が解決されません。ほとんどの場合、コンポーネントはリセット後に削除する必要があります。

  1. 削除を試みます（これは成功しません）。

    kubectl delete -n NAMESPACE apigeedatastore default

    このコマンドは、完了しないことがよくあります。Ctrl+C を押して呼び出しを終了します。

  2. 状態をリセットします。

    ウィンドウ 1 で次のようにします。

    kubectl proxy

    ウィンドウ 2 で次のようにします。

    curl -X PATCH -H "Accept: application/json" -H "Content-Type: application/json-patch+json" --data '[{"op": "replace", "path": "/status/nestedState", "value": ""},{"op": "replace", "path": "/status/state", "value": "running"}]' 'http://127.0.0.1:8001/apis/apigee.cloud.google.com/v1alpha1/namespaces/apigee/apigeedatastores/default/status'

    ファイナライザを削除します（ウィンドウ 2）。

    kubectl edit -n NAMESPACE apigeedatastore default

    次の 2 行を探して削除します。

    finalizers:
- apigeedatastore.apigee.cloud.google.com

一般的なエラーのシナリオ

プロキシ構成がランタイムで使用できない

このエラーは、次のいずれかのような形で発生します。

  • runtime が ready 状態ではありません。
  • runtime が最新バージョンの API を受信していない。

  1. synchronizer Pod から始めます。

    ログで synchronizer を調べます。一般的なエラーは次のとおりです。

    • ネットワーク接続がない（*.googleapi.com に対して）
    • 不適切な IAM アクセス権（サービス アカウントを利用できない、または Synchronizer 管理者権限で提供されない）
    • setSyncAuthorization API が呼び出されなかった

  2. runtime Pod を調べます。

    runtime Pod のログを調べると、runtime が構成を読み込まなかった理由がわかります。コントロール プレーンは、ほとんどの構成ミスがデータプレーンに影響することを防止しようとします。妥当性確認ができないか、正しく実装されていない場合、runtime は読み込みに失敗します。

コントロール プレーンに「ランタイム Pod なし」と表示される

  1. synchronizer Pod から始めます。

    ログで synchronizer を調べます。一般的なエラーは次のとおりです。

    • ネットワーク接続がない（*.googleapi.com に対して）
    • 不適切な IAM アクセス権（サービス アカウントを利用できない、または Synchronizer 管理者権限で提供されない）
    • setSyncAuthorization API が呼び出されなかった構成がデータプレーンに送られていない可能性があります。

  2. runtime Pod を調べます。

    runtime Pod のログを調べると、runtime が構成を読み込まなかった理由がわかります。

  3. watcher Pod を調べます。

    これは、Ingress（ルーティング）を構成し、プロキシと Ingress のデプロイ ステータスをコントロール プレーンに報告する watcher コンポーネントです。これらのログを調べて、watcher がステータスを報告していない理由を確認してください。overrides.yaml ファイルの名前と環境名や環境グループ名のコントロール プレーンの不一致がよくある理由として挙げられます。

デバッグ セッションがコントロール プレーンに表示されない

  1. synchronizer Pod から始めます。

    ログで synchronizer を調べます。一般的なエラーは次のとおりです。

    • ネットワーク接続がない（*.googleapi.com に対して）
    • 不適切な IAM アクセス権（サービス アカウントを利用できない、または Synchronizer 管理者権限で提供されない）
    • setSyncAuthorization API が呼び出されなかった
  2. runtime Pod を調べます。
    runtime Pod のログを調べると、runtime が UDCA にデバッグログを送信していない理由がわかります。
  3. UDCA Pod を検査します。
    UDCA のログを調べると、UDCA がデバッグ セッション情報をコントロール プレーンに送信していない理由がわかります。

Cassandra が大きなキャッシュ レスポンスを返す

次の警告メッセージは、Cassandra がより大きなペイロードの読み取りリクエストまたは書き込みリクエストを受信していることを示しています。この警告しきい値は、レスポンスのペイロード サイズを示す低い値に設定されているため、無視しても問題ありません。

Batch for [cache_ahg_gap_prod_hybrid.cache_map_keys_descriptor, cache_ahg_gap_prod_hybrid.cache_map_entry] is of size 79.465KiB, exceeding specified threshold of 50.000KiB by 29.465KiB