Amazon EKS Connector の問題をトラブルシューティングする - Amazon EKS
基本的なトラブルシューティングHelm の問題: 403 Forbiddenクラスターが Pending 状態でスタックしていますサービスアカウントは API グループの「ユーザー」を偽装することはできませんユーザーは API グループのリソースを一覧表示できませんAmazon EKS は API サーバーと通信できませんAmazon EKS Connector の Pods がクラッシュループしている Failed to initiate eks-connector: InvalidActivationクラスターノードにアウトバウンド接続がありません Amazon EKS Connector Pods が ImagePullBackOff 状態になっています

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

本ユーザーガイドの改善にご協力いただけませんか? このページの下部までスクロールし、[GitHub でこのページの編集] を選択します。皆さまにご協力いただくことで、あらゆる人々に使いやすいユーザーガイドになります。

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

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

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

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

Amazon EKS Connector の状態を確認する

Amazon EKS Connector の状態を確認します。

kubectl get pods -n eks-connector

Amazon EKS Connector のログを検査します

Amazon EKS Connector の Pod は 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

Helm の問題: 403 Forbidden

Helm インストールコマンドの実行中に以下のエラーが表示された場合:

Error: INSTALLATION FAILED: unexpected status from HEAD request to https://public.ecr.aws/v2/eks-connector/eks-connector-chart/manifests/0.0.6: 403 Forbidden

以下の行を実行して修正できます。

docker logout public.ecr.aws

コンソールのエラー: クラスターが Pending 状態でスタックしています

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

コンソールエラー: クラスタースコープで User “system:serviceaccount:eks-connector:eks-connector” can't impersonate resource “users” in API group “”

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

  • AWS アカウント 111122223333 からの IAM ユーザー john は、Kubernetes ユーザーにマッピングされています。IAM のベストプラクティスでは、ユーザーではなくロールに許可を付与することが推奨されています。

    arn:aws:iam::111122223333:user/john

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

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

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

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

コンソールエラー: クラスタースコープで [...] is forbidden: User [...] cannot list resource “[...] in API group”

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

この問題を解決するには、追加のユーザーに権限を付与する方法が 2 つあります。以前に Helm チャート 経由で eks-connector をインストールしたことがある場合は、以下のコマンドを実行することでユーザーにアクセス権を簡単に付与できます。userARN1 と userARN2 を IAM ロールの ARN のリストに置き換えて、Kubernetes リソース表示のアクセス権を付与します。

helm upgrade eks-connector oci://public.ecr.aws/eks-connector/eks-connector-chart \
    --reuse-values \
    --set 'authentication.allowedUserARNs={userARN1,userARN2}'

または、クラスターの管理者として個々の Kubernetes ユーザーに適切なレベルの RBAC 権限を付与します。詳細な説明と例については、「Amazon EKS コンソールで Kubernetes クラスターのリソースを表示するためのアクセスを付与する」を参照してください。

コンソールエラー:「Amazon EKS が Kubernetes クラスターの API サーバーと通信できません。」 正常に接続するには、クラスターが ACTIVE 状態である必要があります。数分後にもう一度お試しください。

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

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

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

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

Amazon EKS Connector の Pods がクラッシュループしている

Amazon EKS Connector の Pod が CrashLoopBackOff 状態になる原因は数多くあります。この問題は connector-init コンテナに関係している可能性があります。Amazon EKS コネクタの Pod ステータスを確認します。

kubectl get pods -n eks-connector

出力例は次のとおりです。

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

出力が前の出力と似ている場合、Amazon EKS Connector のログを検査します を参照して問題をトラブルシューティングしてください。

Failed to initiate eks-connector: InvalidActivation

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 日以内に Amazon EKS Connector をアクティブ化する必要があるためです。この問題を解決するには、Amazon EKS Connector のマニフェストが有効期限の日時よりも前にターゲットの Kubernetes クラスターに適用されていることを確認してください。アクティブ化の有効期限を確認するには、DescribeCluster API オペレーションを呼び出します。

    aws eks describe-cluster --name my-cluster

    次のレスポンスの例では、有効期限の日時は 2021-11-12T22:28:51.101000-08:00 として記録されています。

    
{
    "cluster": {
        "name": "my-cluster",
        "arn": "arn:aws:eks:region:111122223333: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::111122223333:role/my-connector-role"
        }
    }
}

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

クラスターノードにアウトバウンド接続がありません

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

Amazon EKS Connector Pods が ImagePullBackOff 状態になっています

get pods コマンドを実行しているときに Pods が ImagePullBackOff 状態にある場合、正常に動作しません。Amazon EKS Connector Pods が ImagePullBackOff 状態の場合、正常に作動できません。Amazon EKS Connector Pods の状態を確認してください。

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 Public Gallery」からイメージを参照します。ターゲットの Kubernetes クラスターが Amazon ECR Public Gallery からイメージをプルできない可能性があります。Amazon ECR Public Gallery のイメージのプルに関する問題を解決するか、選択したプライベートコンテナレジストリ内のイメージのミラーリングを検討してください。