**このページの改善にご協力ください** 

このユーザーガイドに貢献するには、すべてのページの右側のペインにある「**GitHub でこのページを編集する**」リンクを選択してください。

# Amazon EKS Hybrid Nodes ゲートウェイのトラブルシューティング
<a name="hybrid-nodes-gateway-troubleshooting"></a>

このページでは、Amazon EKS Hybrid Nodes ゲートウェイの一般的な問題の診断と解決に関するガイダンスを提供します。それぞれのセクションで、症状、考えられる原因、診断手順、解決策を説明しています。運用の詳細については、「[Amazon EKS Hybrid Nodes ゲートウェイオペレーション](hybrid-nodes-gateway-operations.md)」を参照してください。

## ハイブリッドノードのポッドに VPC からアクセスできない
<a name="hybrid-nodes-gateway-ts-unreachable"></a>

ハイブリッドノードで実行されているポッドに、EC2 インスタンス、ロードバランサー、Kubernetes コントロールプレーンなどの VPC のリソースからアクセスできません。

 **考えられる原因:** 
+ VPC ルートテーブルエントリがないか、誤った ENI を指している。
+ ゲートウェイリーダーポッドが実行されていないか、セットアップが完了していない。
+ ハイブリッドノードで Cilium VTEP が有効になっていないか設定されていない。
+ ゲートウェイ EC2 インスタンスで送信元/送信先チェックが有効になっている。

 **診断手順:** 

1.  **VPC ルートテーブルエントリを確認します。**ハイブリッドポッド CIDR のルートが存在し、アクティブなゲートウェイインスタンスのプライマリ ENI を指していることを確認します。

   ```
   aws ec2 describe-route-tables \
     --route-table-ids {{ROUTE_TABLE_ID}} \
     --query "RouteTables[].Routes[?DestinationCidrBlock=='POD_CIDR']"
   ```

   ルートがない場合は、ゲートウェイログでルートテーブルエラーがないか確認します。ルートが間違った ENI を指している場合は、フェイルオーバーが正常に完了していない可能性があります。

1.  **ゲートウェイポッドのステータスとリーダー選出を確認します。**2 つのゲートウェイポッドが実行されていて、一方がリーダーリースを保持していることを確認します。

   ```
   kubectl get pods -n eks-hybrid-nodes-gateway
   kubectl get lease -n eks-hybrid-nodes-gateway
   ```

   リースを保持しているポッドがない場合は、「[リーダー選出の問題](#hybrid-nodes-gateway-ts-leader)」を参照してください。

1.  **ハイブリッドノードの Cilium VTEP 設定を確認します。**`CiliumVTEPConfig` リソースが存在し、リーダーのノード IP が含まれていることを確認します。

   ```
   kubectl get ciliumvtepconfig hybrid-gateway -o yaml
   ```

   `spec.endpoints[0].tunnelEndpoint` は、リーダーゲートウェイノードの IP アドレスと一致している必要があります。このリソースがないか、古い IP になっている場合、ゲートウェイでリーダーのセットアップが完了していない可能性があります。

1.  **送信元/送信先チェックを確認します。**ゲートウェイ EC2 インスタンスで送信元/送信先チェックが無効になっていることを確認します。

   ```
   aws ec2 describe-instance-attribute \
     --instance-id {{GATEWAY_INSTANCE_ID}} \
     --attribute sourceDestCheck
   ```

   `sourceDestCheck` が `true` になっている場合は無効にします。「[EKS Hybrid Nodes ゲートウェイの使用を開始する](hybrid-nodes-gateway-getting-started.md)」を参照してください。

## ハイブリッドノードのウェブフック呼び出しが失敗する
<a name="hybrid-nodes-gateway-ts-webhooks"></a>

ハイブリッドノードで実行されているウェブフックエンドポイントに Kubernetes API サーバーから到達できません。ウェブフックアドミッションリクエストがタイムアウトするか、接続エラーが返されます。

 **考えられる原因:** 
+ コントロールプレーンからハイブリッドポッドへのトラフィックがゲートウェイでルーティングされていない。
+ `CiliumVTEPConfig` リソースがないか、古いエンドポイント IP になっている。

 **診断手順:** 

1.  **コントロールプレーンからゲートウェイノード IP に到達できることを確認します。**トラフィックはコントロールプレーンから VPC ルートテーブルに送信され、そこからゲートウェイの ENI に転送されます。「[ハイブリッドノードのポッドに VPC からアクセスできない](#hybrid-nodes-gateway-ts-unreachable)」の手順を使用して、VPC ルートテーブルエントリが正しいことを確認します。

1.  **CiliumVTEPConfig リソースを確認します。**このリソースが存在し、`tunnelEndpoint` が現在のリーダーのノード IP と一致していることを確認します。

   ```
   kubectl get ciliumvtepconfig hybrid-gateway -o yaml
   ```

   トンネルエンドポイントが古くなっている場合 (以前のリーダーを指している場合)、ゲートウェイでリーダーセットアップシーケンスが完了していない可能性があります。ゲートウェイログで `CiliumVTEPConfig` アップサート時のエラーがないか確認してください。

## VPC ルートテーブルの更新が失敗する
<a name="hybrid-nodes-gateway-ts-routes"></a>

ゲートウェイログに VPC ルートテーブルオペレーションに関連するエラーが表示され、ハイブリッドポッド CIDR のルートが作成または更新されません。

 **考えられる原因:** 
+ ゲートウェイの IAM ロールに必要な EC2 アクセス許可がない。
+ 設定のルートテーブル ID が正しくないか、ルートテーブルが存在しない。
+ ゲートウェイから EC2 API エンドポイントに到達できない。

 **診断手順:** 

1.  **IAM アクセス許可を確認します。**ゲートウェイには以下の IAM アクションが必要です。
   +  `ec2:DescribeRouteTables` 
   +  `ec2:CreateRoute` 
   +  `ec2:ReplaceRoute` 
   +  `ec2:DescribeInstances` 

     ゲートウェイノードのインスタンスプロファイルまたは Pod Identity 設定にアタッチされている IAM ロールを確認します。

1.  **設定でルートテーブル ID を確認します。**`ROUTE_TABLE_IDS` 環境変数にゲートウェイデプロイの有効なルートテーブル ID が含まれていることを確認します。

   ```
   kubectl get deployment eks-hybrid-nodes-gateway -n eks-hybrid-nodes-gateway -o jsonpath='{.spec.template.spec.containers[0].env}' | jq .
   ```

   VPC にルートテーブル ID が存在することを確認します。

   ```
   aws ec2 describe-route-tables --route-table-ids {{ROUTE_TABLE_ID}}
   ```

1.  **ゲートウェイログでルートテーブルエラーがないか確認します。**ルートテーブルオペレーションに関連するエラーメッセージを探します。

   ```
   kubectl logs -n eks-hybrid-nodes-gateway {{LEADER_POD}} | grep -i "route table"
   ```

   一般的なエラーメッセージとしては以下があります。
   +  `Failed to verify route table access` — ゲートウェイでルートテーブルを記述できません。IAM アクセス許可とルートテーブル ID を確認します。
   +  `Failed to update route tables` — ゲートウェイでルートの作成または置き換えができません。IAM 許可を確認します。
   +  `failed to access route table` — ルートテーブル ID が正しくないか、IAM ロールに `ec2:DescribeRouteTables` がない可能性があります。

## ゲートウェイポッドの起動に失敗するか異常がある
<a name="hybrid-nodes-gateway-ts-pods"></a>

ゲートウェイポッドの状態が `CrashLoopBackOff`、`Error`、または `Pending` であるか、ヘルスエンドポイントからエラーが返されます。

 **考えられる原因:** 
+ 必要な環境変数 (`VPC_CIDR`、`POD_CIDRS`、`ROUTE_TABLE_IDS`) が設定されていない。
+ ゲートウェイノードで IP 転送が有効になっていない。
+ ノードラベルまたはアンチアフィニティの制約でスケジューリングが禁止されている。

 **診断手順:** 

1.  **ポッドログを確認します。**問題があるポッドのログを確認してエラーを特定します。

   ```
   kubectl logs -n eks-hybrid-nodes-gateway {{LEADER_POD}}
   ```

1.  **必要な環境変数を確認します。**ゲートウェイには、`NODE_IP`、`VPC_CIDR`、および `POD_CIDRS` が必要です。いずれかがない場合、ゲートウェイはすぐに終了します。ポッド仕様を確認します。

   ```
   kubectl get pod -n eks-hybrid-nodes-gateway {{LEADER_POD}} -o jsonpath='{.spec.containers[0].env}' | jq .
   ```
   +  `NODE_IP` は、ポッド仕様の `status.hostIP` から自動的に設定されます。空の場合、ポッドがノードでまだスケジュールされていない可能性があります。
   +  `VPC_CIDR` と `POD_CIDRS` は Helm 値から取得されます。正しく設定されていることを確認してください。

1.  **IP 転送を確認します。**ゲートウェイの起動時に IP 転送が有効になっているかが確認され、有効になっていないとゲートウェイは終了します。ポッドログで `IP forwarding is not enabled` というエラーメッセージを探します。ノードで IP 転送を有効にします。

   ```
   # Check current setting
   cat /proc/sys/net/ipv4/ip_forward
   
   # Enable if not set
   sudo sysctl -w net.ipv4.ip_forward=1
   ```

   永続的な設定にするには、kubelet から IP 転送を設定するか、`net.ipv4.ip_forward=1` を `/etc/sysctl.d/` に追加します。

1.  **ノードラベルとスケジューリングの制約を確認します。**ゲートウェイポッドのノードには `hybrid-gateway-node=true` というラベルが必要です。ポッドアンチアフィニティにより、各ポッドが個別のノードで実行されます。ポッドが `Pending` の場合は、スケジューリングの問題がないか確認します。

   ```
   kubectl describe pod -n eks-hybrid-nodes-gateway {{LEADER_POD}}
   ```

   ノードの不足、ラベルの欠落、アンチアフィニティの競合を示すイベントを探します。

## リーダー選出の問題
<a name="hybrid-nodes-gateway-ts-leader"></a>

ゲートウェイポッドが実行されていますが、いずれのポッドもリーダーリースを取得しないか、リーダーシップの移行が頻繁に発生します。

 **考えられる原因:** 
+ Lease オブジェクトに対する RBAC アクセス許可がない。
+ ゲートウェイポッドと Kubernetes API サーバーの間のネットワーク接続が不安定である。
+ リーダー選出パラメータの設定が間違っている。

 **診断手順:** 

1.  **Lease オブジェクトを確認します。**Lease が存在することを確認し、現在のホルダーを調べます。

   ```
   kubectl get lease -n eks-hybrid-nodes-gateway hybrid-gateway-leader -o yaml
   ```

   現在のリーダーは `spec.holderIdentity` フィールドに表示されます。リースが最後にいつ更新されたかが `spec.renewTime` に表示されます。`renewTime` が古くなっている場合、リーダーの API サーバーへの接続が失われている可能性があります。

1.  **RBAC アクセス許可を確認します。**ゲートウェイサービスアカウントには、ゲートウェイ名前空間で Lease オブジェクトを取得、作成、更新するためのアクセス許可が必要です。Role と RoleBinding を確認します。

   ```
   kubectl get role -n eks-hybrid-nodes-gateway
   kubectl get rolebinding -n eks-hybrid-nodes-gateway
   ```

   Role の `coordination.k8s.io` API グループに、`leases` リソースに対する `get`、`create`、および `update` の動詞が含まれている必要があります。

1.  **ポッドログでリースエラーがないか確認します。**ポッドログでリーダー選出エラーを探します。

   ```
   kubectl logs -n eks-hybrid-nodes-gateway {{LEADER_POD}} | grep -i "leader\|lease"
   ```

   一般的な問題は次のとおりです。
   +  `Failed to acquire lease` — ポッドでリースオブジェクトを作成または更新できません。RBAC アクセス許可を確認します。
   + `Leadership ended` に続いて `Leader setup complete` というメッセージが頻繁に発生 — リーダーがリースを失って再取得しています。これは、ポッドと API サーバーの間のネットワークが不安定であることを示している可能性があります。`--leader-election-lease-duration` を増やすことを検討してください。

1.  **リーダー選出パラメータを確認します。**設定されている値を確認します。

   ```
   kubectl get deployment eks-hybrid-nodes-gateway -n eks-hybrid-nodes-gateway -o jsonpath='{.spec.template.spec.containers[0].args}'
   ```

   `--leader-election-renew-deadline` が `--leader-election-lease-duration` より小さいことを確認します。更新期限がリース期間を超えている場合、リーダーは更新前にリースを失います。詳細については、「[リーダー選出調整](hybrid-nodes-gateway-configuration.md#hybrid-nodes-gateway-leader-tuning)」を参照してください。

## 一般的なエラーメッセージ
<a name="hybrid-nodes-gateway-ts-errors"></a>

次の表に、ゲートウェイポッドログに表示される可能性があるエラーメッセージとその解決策を示します。


| エラーメッセージ | 原因 | 解決策 | 
| --- | --- | --- | 
|  `IP forwarding is not enabled`  | ゲートウェイノードでカーネルパラメータ `net.ipv4.ip_forward` が `1` に設定されていません。 | kubelet 設定を使用するか `sysctl -w net.ipv4.ip_forward=1` を実行して IP 転送を有効にします。 | 
|  `Failed to setup VXLAN`  | ゲートウェイで VXLAN ネットワークインターフェイスを作成できません。通常、これはポッドに `NET_ADMIN` 機能がない場合に発生します。 | デプロイ仕様で `securityContext.capabilities.add` に `NET_ADMIN` が含まれていることを確認します。Helm チャートが正しくデプロイされていることを確認します。 | 
|  `Failed to verify route table access`  | 起動時に、ゲートウェイで 1 つ以上の VPC ルートテーブルを記述できません。 | IAM ロールに `ec2:DescribeRouteTables` アクセス許可があり、設定のルートテーブル ID が正しいことを確認します。 | 
|  `Failed to update route tables`  | ゲートウェイで VPC ルートテーブルのルートの作成または置き換えができません。 | IAM ロールに `ec2:CreateRoute` および `ec2:ReplaceRoute` のアクセス許可があることを確認します。 | 
|  `Failed to create route table manager`  | ゲートウェイで AWS EC2 クライアントを初期化できないか、インスタンスのプライマリ ENI を取得できません。 | IAM ロールに `ec2:DescribeInstances` アクセス許可があり、インスタンスメタデータサービス (IMDS) にアクセスできることを確認します。 | 
|  `NODE_IP is required`  | `NODE_IP` 環境変数または `--node-ip` フラグが設定されていません。 | ポッド仕様で `fieldRef` を使用して `status.hostIP` の `NODE_IP` が設定されていることを確認します。Helm チャートが正しくデプロイされていることを確認します。 | 
|  `Invalid NODE_IP`  | `NODE_IP` に指定された値が有効な IP アドレスではありません。 | ポッド仕様で `NODE_IP` 環境変数の値を確認します。 | 
|  `pod-cidrs and vpc-cidr are required`  | `POD_CIDRS` または `VPC_CIDR` 環境変数が空です。 | インストール時に `podCIDRs` と `vpcCIDR` の Helm 値を設定します。 | 
|  `No valid route table IDs provided`  | `ROUTE_TABLE_IDS` の値が設定されていますが、有効なルートテーブル ID が解析で見つかりません。 | `routeTableIDs` の Helm 値にフォーマットエラーがないか確認します。ルートテーブル ID はカンマで区切る必要があります (例: `rtb-abc123,rtb-def456`)。 | 
|  `Failed to auto-detect AWS region`  | ゲートウェイで EC2 インスタンスメタデータから AWS リージョンを取得できません。 | インスタンスメタデータサービス (IMDS) にアクセスできることを確認します。あるいは、`--aws-region` フラグまたは `AWS_REGION` 環境変数を明示的に設定します。 | 
|  `Failed to auto-detect AWS instance ID`  | ゲートウェイで EC2 インスタンスメタデータからインスタンス ID を取得できません。 | インスタンスメタデータサービス (IMDS) にアクセスできることを確認します。あるいは、`--aws-instance-id` フラグまたは `AWS_INSTANCE_ID` 環境変数を明示的に設定します。 | 
|  `CiliumNode has no internal IP`  | ハイブリッドノードの `CiliumNode` オブジェクトの仕様に内部 IP アドレスがありません。 | ハイブリッドノードが正しく登録され、Cilium エージェントが実行されていることを確認します。ノードの `CiliumNode` リソースを確認します。 | 
|  `CiliumNode <name> has no pod CIDRs allocated`  | ハイブリッドノードの `CiliumNode` オブジェクトに、Cilium IPAM によって割り当てられたポッド CIDR がありません。 | ハイブリッドノードで Cilium IPAM が正しく設定されていることを確認します。`CiliumNode` リソースでノードの IPAM ステータスを確認します。 | 
|  `Failed to upsert CiliumVTEPConfig`  | ゲートウェイで `CiliumVTEPConfig` カスタムリソースを作成または更新できません。 | クラスターに CRD がインストールされており、ゲートウェイサービスアカウントに `CiliumVTEPConfig` リソースを管理するためのアクセス許可があることを確認します。 | 
|  `Unable to create manager`  | コントローラーランタイムマネージャーの初期化に失敗しました。 | ポッドログで追加のコンテキストを確認します。一般的な原因には、無効な kubeconfig や Kubernetes API サーバーに到達できないことなどがあります。 | 
|  `Failed to add gateway setup`  | リーダー選出ランナブルをコントローラーマネージャーに登録できませんでした。 | 通常、これは内部エラーです。ポッドログ全体で追加のコンテキストを確認し、[GitHub リポジトリ](https://github.com/aws/eks-hybrid-nodes-gateway)で問題を報告します。 | 
|  `Unable to create Node controller`  | CiliumNode リコンシラーをコントローラーマネージャーに登録できませんでした。 | ポッドログで追加のコンテキストを確認します。クラスターに CiliumNode CRD がインストールされていることを確認します。 | 
|  `Problem running manager`  | コントローラーマネージャーが予期せず終了しました。 | ポッドログで原因となっているエラーを確認します。一般的な原因には、Kubernetes API サーバーへの接続の喪失、メトリクスまたはヘルスプローブのバインドアドレスにおけるポートの競合などがあります。 | 
|  `failed to access route table <id>`  | 起動時の検証チェックにおいて、ゲートウェイで特定の VPC ルートテーブルを記述できません。 | IAM ロールに `ec2:DescribeRouteTables` アクセス許可があり、ルートテーブル ID が正しいことを確認します。ルートテーブルは、ゲートウェイインスタンスと同じリージョンに存在する必要があります。 | 

## 関連トピック
<a name="hybrid-nodes-gateway-ts-related"></a>
+  [Amazon EKS Hybrid Nodes ゲートウェイ](hybrid-nodes-gateway-overview.md) — ゲートウェイアーキテクチャの概要とユースケース。
+  [EKS Hybrid Nodes ゲートウェイの使用を開始する](hybrid-nodes-gateway-getting-started.md) — 前提条件とインストール手順。
+  [Amazon EKS Hybrid Nodes ゲートウェイ設定リファレンス](hybrid-nodes-gateway-configuration.md) — Helm 値、CLI フラグ、環境変数の完全なリファレンス。
+  [Amazon EKS Hybrid Nodes ゲートウェイオペレーション](hybrid-nodes-gateway-operations.md) — モニタリング、フェイルオーバー動作、スケーリングのガイダンス。