Amazon EKS Connector での問題のトラブルシューティング - Amazon EKS

Amazon EKS Connector での問題のトラブルシューティング

このトピックでは、Amazon EKS Connector の使用中に発生する可能性があるいくつかの一般的なエラーについて説明します。これには、解決方法、回避策、よくある質問も含まれています。

一般的な問題

このセクションでは、Amazon EKS Connector の使用中に発生する可能性がある機能上の問題をトラブルシューティングする方法について説明します。これにより、これらの問題の解決策と回避策が提供されます。

クラスターの登録後、クラスターが Amazon EKS コンソールで Pending 状態のままスタックしている場合、Amazon EKS Connector でクラスターが AWS に正常に接続されなかったことが原因である可能性があります。登録済みのクラスターの場合、Pending 状態は、接続がまだ正常に確立されていないことを意味します。この問題を解決するには、ターゲットの Kubernetes クラスターにマニフェストを適用していることを確認します。クラスターにマニュフェストを適用したにもかかわらず、まだ Pending 状態である場合、クラスターの Amazon EKS Connector に異常がある可能性があります。この問題をトラブルシューティングするには、このトピックの Amazon EKS Connector の pods がクラッシュループしている というセクションを参照してください。

Amazon EKS Connector では、AWS Management Console からユーザーに代わって動作を行うために Kubernetes の ユーザー偽装 を使用します。AWS eks-connector のサービスアカウントから Kubernetes API にアクセスする各 IAM アイデンティティについては、ユーザー名に IAM ARN を使用して、対応する Kubernetes ユーザーを偽装するアクセス許可を付与する必要があります。次の例では、Kubernetes ユーザーに IAM ARN がマッピングされています。

  • AWS アカウント 111122223333 からの IAM ユーザー john は、Kubernetes ユーザーにマッピングされています。

    arn:aws:iam::111122223333:user/john
  • AWS アカウント 111122223333 からの IAM ロール admin は、Kubernetes ユーザーにマッピングされています。

    arn:aws:iam::111122223333:role/admin

    結果は、STS セッションの ARN ではなく IAM ロールの ARN になります。

マッピングされたユーザーを偽装するアカウント権限を eks-connector サービスに付与するよう ClusterRole および ClusterRoleBinding を設定する方法については、「クラスター上の Kubernetes リソースを表示するためのアクセス権をユーザーにグラントする」を参照してください。テンプレートで、%IAM_ARN% が AWS Management Console ユーザーの IAM ARN に置き換えられていることを確認してください。

次の問題を検討します。Amazon EKS Connector により、ターゲットの Kubernetes クラスターでリクエストしている AWS Management Console ユーザーが正常に偽装されました。ただし、偽装されたユーザーには Kubernetes API オペレーションに対する RBAC アクセス許可がありません。

この問題を解決するには、クラスターの管理者として、個々の Kubernetes ユーザーに適切なレベルの RBAC 権限を付与する必要があります。詳細な説明と例については、クラスター上の Kubernetes リソースを表示するためのアクセス権をユーザーにグラントするを参照してください。

Amazon EKS サービスがターゲットクラスター内の Amazon EKS Connector と通信できない場合は、次のいずれかの理由が考えられます。

  • ターゲットクラスターの Amazon EKS Connector に異常がある。

  • ターゲットクラスターと AWS リージョン 間の接続が悪い、または中断している。

これを解決するには、「Amazon EKS Connector のログを検査する」を確認してください。Amazon EKS Connector のエラーが表示されない場合は、数分後に接続を再試行してください。ターゲットクラスターで高レイテンシーや断続的な接続が定期的に発生する場合は、近くにある AWS リージョン にクラスターを再登録することを検討してください。

EKS Connector の pod が CrashLoopBackOff 状態になる原因は数多くあります。この問題は、おそらく connector-init コンテナに関係しています。次の例では、CrashLoopBackOff 状態に入ったのは connector-init コンテナです。

kubectl get pods -n eks-connector NAME READY STATUS RESTARTS AGE eks-connector-0 0/2 Init:CrashLoopBackOff 1 7s

この問題のトラブルシューティングを行うには、「Amazon EKS Connector のログを検査する」を参照してください。

Amazon EKS Connector を初めて起動する場合、Amazon Web Services で activationId および activationCode を登録します。登録が失敗すると、connector-init コンテナがクラッシュする可能性があります。

F1116 20:30:47.261469 1 init.go:43] failed to initiate eks-connector: InvalidActivation:

この問題のトラブルシューティングを行うには、次の原因および推奨される修正を検討してください。

  • activationId と activationCode がマニフェストファイルにないために、登録が失敗した可能性があります。このような場合、値が RegisterCluster API オペレーションから返された正しいものであり、activationCode がマニフェストファイルに含まれていることを確認してください。activationCode は Kubernetes シークレットに追加されるため、base64 でエンコードする必要があります。詳細については、「ステップ 1: クラスターの登録」を参照してください。

  • アクティベーションの有効期限が切れたため、登録が失敗した可能性があります。これは、セキュリティ上の理由から、クラスターを登録してから 3 日以内に EKS Connector をアクティブ化する必要があるためです。この問題を解決するには、EKS Connector のマニフェストが有効期限の日時よりも前にターゲットの Kubernetes クラスターに適用されていることを確認してください。アクティベーションの有効期限を確認するには、DescribeCluster API オペレーションを呼び出します。次のレスポンスの例では、有効期限の日時は 2021-11-12T22:28:51.101000-08:00 と記録されています。

    aws eks describe-cluster --name my-cluster { "cluster": { "name": "my-cluster", "arn": "arn:aws:eks:us-east-1:123456789012:cluster/my-cluster", "createdAt": "2021-11-09T22:28:51.449000-08:00", "status": "FAILED", "tags": { }, "connectorConfig": { "activationId": "00000000-0000-0000-0000-000000000000", "activationExpiry": "2021-11-12T22:28:51.101000-08:00", "provider": "OTHER", "roleArn": "arn:aws:iam::123456789012:role/my-connector-role" } } }

    activationExpiry が渡されたら、クラスターの登録を解除し、再度登録します。これにより、新しいアクティベーションが生成されます。

正常に動作するには、EKS Connector に複数の AWS エンドポイントへのアウトバウンド接続が必要です。ターゲットの AWS リージョン へのアウトバウンド接続が使用可能でないと、プライベートクラスターを接続することはできません。この問題を解決するには、必要なアウトバウンド接続を追加する必要があります。コネクタの要件については、「Amazon EKS Connector の考慮事項」を参照してください。

getpods コマンドを実行しており、pods が ImagePullBackOff 状態にある場合、正常に動作しません。EKS Connector の pod が ImagePullBackOff 状態の場合、正常に動作しません。次の例を参照してください。

kubectl get pods -n eks-connector NAME READY STATUS RESTARTS AGE eks-connector-0 0/2 Init:ImagePullBackOff 0 4s

デフォルトの Amazon EKS Connector のマニフェストファイルについては、Amazon ECR パブリックレジストリからイメージを参照できます。ターゲットの Kubernetes クラスターが Amazon ECR パブリックからイメージをプルできない可能性があります。Amazon ECR パブリックからのイメージのプルに関する問題を解決するか、選択したプライベートコンテナレジストリ内のイメージのミラーリングを検討してください。

よくある質問

Q: Amazon EKS Connector の基盤となるテクノロジーはどのように機能しますか?

A: Amazon EKS Connector は、System Manager (SSM) Agent に基づいています。EKS Connector は、Kubernetes クラスター上で StatefulSet として実行されます。これにより接続が確立され、クラスターの API サーバーと Amazon Web Services 間の通信がプロキシされます。これは、AWS からクラスターが切断されるまで Amazon EKS コンソールにクラスターデータを表示しておくためです。SSM エージェントはオープンソースのプロジェクトです。このプロジェクトについての詳細は、「GitHub GitHub project page」を参照してください。

質問: 接続したいオンプレミスの Kubernetes クラスターがあります。接続するにはファイアウォールポートを開く必要がありますか?

A: いいえ。ファイアウォールポートを開く必要はありません。Kubernetes クラスターは、AWS リージョン へのアウトバウンド接続のみを必要とします。AWS のサービスがオンプレミスネットワークのリソースにアクセスすることはありません。Amazon EKS Connector はクラスターで実行され、AWS への接続を開始します。クラスターの登録が完了すると、クラスター上の Kubernetes API サーバーからの情報を必要とする Amazon EKS コンソールからアクションを開始した後にのみ、AWS により Amazon EKS Connector にコマンドが発行されます。

Q: Amazon EKS Connector によってクラスターから AWS に送信されるデータはどのようなものですか?

A: Amazon EKS Connector により送信されるのは、AWS でのクラスターの登録に必要な技術情報です。また、お客様がリクエストする Amazon EKS コンソールにおける機能のクラスターとワークロードのメタデータも送信されます。Amazon EKS Connector は、AWS へのデータの送信を必要とする Amazon EKS コンソールまたは Amazon EKS API からアクションを開始した場合にのみ、このデータを収集または送信します。デフォルトでは、AWS で Kubernetes のバージョン番号以外のデータが保存されることはありません。許可した場合にのみ保存されます。

Q: AWS リージョン の外部のクラスターを接続できますか?

A: はい、任意の場所からクラスターを Amazon EKS に接続できます。さらに EKS のサービスは、すべての AWS 公開商用 AWS リージョン でサポートされています。これは、クラスターからターゲットの AWS リージョン への有効なネットワーク接続により動作します。UI パフォーマンスを最適化するため、クラスターの場所に最も近い AWS リージョン を選択することをお勧めします。例えば、東京で実行しているクラスターがある場合、レイテンシーを低くするためにクラスターを東京の AWS リージョン (つまり ap-northeast-1 AWS リージョン) に接続します。任意の場所から、中国リージョンまたは GovCloud AWS リージョン を除くあらゆるパブリックな商用 AWS リージョン の Amazon EKS にクラスターを接続できます。

基本的なトラブルシューティング

このセクションでは、問題が不明な場合の診断手順について説明します。

次のコマンドを使用して、Amazon EKS Connector の状態を確認します。

kubectl get pods -n eks-connector

Amazon EKS Connector のポッドは 3 つのコンテナで構成されています。これらすべてのコンテナの完全なログを取得して検査できるようにするには、次のコマンドを実行します。

  • connector-init

    kubectl logs eks-connector-0 --container connector-init -n eks-connector kubectl logs eks-connector-1 --container connector-init -n eks-connector
  • connector-proxy

    kubectl logs eks-connector-0 --container connector-proxy -n eks-connector kubectl logs eks-connector-1 --container connector-proxy -n eks-connector
  • connector-agent

    kubectl exec eks-connector-0 --container connector-agent -n eks-connector -- cat /var/log/amazon/ssm/amazon-ssm-agent.log kubectl exec eks-connector-1 --container connector-agent -n eks-connector -- cat /var/log/amazon/ssm/amazon-ssm-agent.log

Amazon EKS クラスターは、単一の AWS アカウントおよび AWS リージョン 内で clusterName により一意に識別されます。Amazon EKS に接続されたクラスターが複数ある場合、現在の Kubernetes クラスターが登録されている Amazon EKS クラスターを確認できます。これを行うには、次のコマンドを入力して、現在のクラスターの clusterName を確認します。

kubectl exec eks-connector-0 --container connector-agent -n eks-connector \ -- cat /var/log/amazon/ssm/amazon-ssm-agent.log \ | grep -m1 -oE "eks_c:[a-zA-Z0-9_-]+" \ | sed -E "s/^.*eks_c:([a-zA-Z0-9_-]+)_[a-zA-Z0-9]+.*$/\1/" kubectl exec eks-connector-1 --container connector-agent -n eks-connector \ -- cat /var/log/amazon/ssm/amazon-ssm-agent.log \ | grep -m1 -oE "eks_c:[a-zA-Z0-9_-]+" \ | sed -E "s/^.*eks_c:([a-zA-Z0-9_-]+)_[a-zA-Z0-9]+.*$/\1/"

次のコマンドは、問題のトラブルシューティングに必要な情報の取得に役立ちます。

  • Amazon EKS Connector の pods で使用されるイメージを収集するには、次のコマンドを使用します。

    kubectl get pods -n eks-connector -o jsonpath="{.items[*].spec.containers[*].image}" \ | tr -s '[[:space:]]' '\n'
  • Amazon EKS Connector が実行されているワーカーノード名を収集するには、次のコマンドを使用します。

    kubectl get pods -n eks-connector -o jsonpath="{.items[*].spec.nodeName}" \ | tr -s '[[:space:]]' '\n'
  • Kubernetes クライアントおよびサーバーのバージョンを取得するには、次のコマンドを実行します。

    kubectl version
  • ワーカーノードに関する情報を取得するには、次のコマンドを実行します。

    kubectl get nodes -o wide --show-labels