**このページの改善にご協力ください**
このユーザーガイドに貢献するには、すべてのページの右側のペインにある「**GitHub でこのページを編集する**」リンクを選択してください。
# Amazon EKS Connector の問題をトラブルシューティングする
このトピックでは、Amazon EKS Connector の使用中に発生する可能性があるいくつかの一般的なエラーについて説明します。これには、解決方法および回避策も含まれています。
## 基本的なトラブルシューティング
このセクションでは、Amazon EKS Connector の問題を診断する手順について説明します。
### Amazon EKS Connector の状態を確認する
Amazon EKS Connector の状態を確認するには、次のように入力します。
```
kubectl get pods -n eks-connector
```
### Amazon 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 の Pod で使用されるイメージを収集するには、次のコマンドを使用します。
```
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 Pod がクラッシュループしている](#symp-loop) を参照してください。
## コンソールのエラー: ユーザーシステム:serviceaccount:eks-connector:eks-connector can’t impersonate resource users in API group at cluster scope (eks-connector はクラスタースコープで API グループのリソースユーザーを偽装できません)
Amazon EKS Connector は、Kubernetes [ユーザー偽装](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation)を使用して AWS マネジメントコンソール から [IAM プリンシパル](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html#iam-term-principal)に代わってアクションを実行します。AWS `eks-connector` のサービスアカウントから Kubernetes API にアクセスする各プリンシパルについては、Kubernetes ユーザー名として IAM ARN で対応する Kubernetes ユーザーを偽装するために許可を付与する必要があります。次の例では、Kubernetes ユーザーに IAM ARN がマッピングされています。
+ AWS アカウント {{111122223333}} からの IAM ユーザー {{john}} は、Kubernetes ユーザーにマッピングされています。[IAM のベストプラクティス](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html)では、ユーザーではなくロールに許可を付与することが推奨されています。
```
arn:aws:iam::111122223333:user/john
```
+ AWS アカウント {{111122223333}} からの IAM ロール{{管理者}}は、Kubernetes ユーザーにマッピングされています。
```
arn:aws:iam::111122223333:role/admin
```
結果は、AWS STS セッションの ARN ではなく IAM ロールの ARN になります。
マッピングされたユーザーを偽装するアカウント権限を `eks-connector` サービスに付与するために `ClusterRole` および `ClusterRoleBinding` を設定する方法については、「[Amazon EKS コンソールで Kubernetes クラスターのリソースを表示するためのアクセスを付与する](connector-grant-access.md)」を参照してください。テンプレートで、`%IAM_ARN%` が AWS マネジメントコンソール IAM プリンシパルの IAM ARN に置き換えられていることを確認してください。
## コンソールのエラー: […] is forbidden: User […] cannot list resource […] in API group at the cluster scope ([…] は禁止されています: ユーザー […] が、クラスタースコープで API グループのリソース […] をリストできません)
次の問題を検討します。Amazon EKS Connector により、ターゲットの Kubernetes クラスターでリクエストしている AWS マネジメントコンソール 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 クラスターのリソースを表示するためのアクセスを付与する](connector-grant-access.md) を参照してください。
## コンソールのエラー: Amazon EKS can't communicate with your Kubernetes cluster API server. 正常に接続するには、クラスターが ACTIVE 状態である必要があります。数分後にもう一度お試しください。
Amazon EKS サービスがターゲットクラスター内の Amazon EKS Connector と通信できない場合、次のいずれかの原因が考えられます。
+ ターゲットクラスターの Amazon EKS Connector に異常があります。
+ ターゲットクラスターと AWS リージョン間の接続が悪い、または中断している。
この問題を解決するには、[Amazon EKS Connector ログ](#tsc-logs)を確認してください。Amazon EKS Connector のエラーが表示されない場合、数分後に接続を再試行してください。ターゲットクラスターで高レイテンシーや接続が断続的になる状況が定期的に発生する場合は、近くにある AWS リストにクラスターを再登録することを検討してください。
## Amazon EKS Connector Pod がクラッシュループしている
Amazon EKS Connector Pod が `CrashLoopBackOff` 状態になる原因は数多くあります。この問題は `connector-init` コンテナに関係している可能性があります。Amazon EKS Connector Pod のステータスを確認します。
```
kubectl get pods -n eks-connector
```
出力例は次のとおりです。
```
NAME READY STATUS RESTARTS AGE
eks-connector-0 0/2 Init:CrashLoopBackOff 1 7s
```
出力が前の出力と似ている場合、[Amazon EKS Connector のログを検査します](#tsc-logs) を参照して問題をトラブルシューティングしてください。
## 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: クラスターの登録](connecting-cluster.md#connector-connecting)」を参照してください。
+ アクティベーションの有効期限が切れたため、登録が失敗した可能性があります。これは、セキュリティ上の理由により、クラスターを登録してから 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 の考慮事項](eks-connector.md#connect-cluster-reqts)」を参照してください。
## Amazon EKS Connector Pod が `ImagePullBackOff` 状態になっている
`get pods` コマンドを実行しているときに Pod が `ImagePullBackOff` 状態にある場合、正常に動作しません。Amazon EKS Connector Pod が `ImagePullBackOff` 状態の場合、正常に作動できません。Amazon EKS Connector Pod の状態を確認してください。
```
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](https://gallery.ecr.aws/)」からイメージを参照します。ターゲットの Kubernetes クラスターが Amazon ECR Public Gallery からイメージをプルできない可能性があります。Amazon ECR Public Gallery のイメージのプルに関する問題を解決するか、選択したプライベートコンテナレジストリ内のイメージのミラーリングを検討してください。