View a markdown version of this page

Amazon EKS Hybrid Nodes ゲートウェイのトラブルシューティング - Amazon EKS
ハイブリッドノードのポッドに VPC からアクセスできないハイブリッドノードのウェブフック呼び出しが失敗するVPC ルートテーブルの更新が失敗するゲートウェイポッドの起動に失敗するか異常があるリーダー選出の問題一般的なエラーメッセージ関連トピック

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

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

Amazon EKS Hybrid Nodes ゲートウェイのトラブルシューティング

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

ハイブリッドノードのポッドに VPC からアクセスできない

ハイブリッドノードで実行されているポッドに、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=='[.replaceable]`POD_CIDR`']"

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

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

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

    リースを保持しているポッドがない場合は、「リーダー選出の問題」を参照してください。

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

    kubectl get ciliumvtepconfig hybrid-gateway -o yaml

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

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

    aws ec2 describe-instance-attribute \
  --instance-id GATEWAY_INSTANCE_ID \
  --attribute sourceDestCheck

    sourceDestCheck が true になっている場合は無効にします。「EKS Hybrid Nodes ゲートウェイの使用を開始する」を参照してください。

ハイブリッドノードのウェブフック呼び出しが失敗する

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

考えられる原因:

  • コントロールプレーンからハイブリッドポッドへのトラフィックがゲートウェイでルーティングされていない。

  • CiliumVTEPConfig リソースがないか、古いエンドポイント IP になっている。

診断手順:

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

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

    kubectl get ciliumvtepconfig hybrid-gateway -o yaml

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

VPC ルートテーブルの更新が失敗する

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

考えられる原因:

  • ゲートウェイの IAM ロールに必要な EC2 アクセス許可がない。

  • 設定のルートテーブル ID が正しくないか、ルートテーブルが存在しない。

  • ゲートウェイから EC2 API エンドポイントに到達できない。

診断手順:

  1. IAM アクセス許可を確認します。ゲートウェイには以下の IAM アクションが必要です。

    • ec2:DescribeRouteTables

    • ec2:CreateRoute

    • ec2:ReplaceRoute

    • ec2:DescribeInstances

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

  2. 設定でルートテーブル 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

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

    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 がない可能性があります。

ゲートウェイポッドの起動に失敗するか異常がある

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

考えられる原因:

  • 必要な環境変数 (VPC_CIDR、POD_CIDRS、ROUTE_TABLE_IDS) が設定されていない。

  • ゲートウェイノードで IP 転送が有効になっていない。

  • ノードラベルまたはアンチアフィニティの制約でスケジューリングが禁止されている。

診断手順:

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

    kubectl logs -n eks-hybrid-nodes-gateway LEADER_POD

  2. 必要な環境変数を確認します。ゲートウェイには、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 値から取得されます。正しく設定されていることを確認してください。

  3. 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/ に追加します。

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

    kubectl describe pod -n eks-hybrid-nodes-gateway LEADER_POD

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

リーダー選出の問題

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

考えられる原因:

  • 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 サーバーへの接続が失われている可能性があります。

  2. 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 の動詞が含まれている必要があります。

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

    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 を増やすことを検討してください。

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

    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 より小さいことを確認します。更新期限がリース期間を超えている場合、リーダーは更新前にリースを失います。詳細については、「リーダー選出調整」を参照してください。

一般的なエラーメッセージ

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

エラーメッセージ 原因 解決策

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 リポジトリで問題を報告します。

Unable to create Node controller

CiliumNode リコンシラーをコントローラーマネージャーに登録できませんでした。

ポッドログで追加のコンテキストを確認します。クラスターに CiliumNode CRD がインストールされていることを確認します。

Problem running manager

コントローラーマネージャーが予期せず終了しました。

ポッドログで原因となっているエラーを確認します。一般的な原因には、Kubernetes API サーバーへの接続の喪失、メトリクスまたはヘルスプローブのバインドアドレスにおけるポートの競合などがあります。

failed to access route table <id>

起動時の検証チェックにおいて、ゲートウェイで特定の VPC ルートテーブルを記述できません。

IAM ロールに ec2:DescribeRouteTables アクセス許可があり、ルートテーブル ID が正しいことを確認します。ルートテーブルは、ゲートウェイインスタンスと同じリージョンに存在する必要があります。