kubectl を使用して EKS クラスターに接続できない原因を教えてください。

所要時間3分

kubectl コマンドラインツールを使用して Amazon Elastic Kubernetes Service (Amazon EKS) クラスターに接続しようとすると、エラーメッセージが表示されます。

解決策

kubectl の使用時に Amazon EKS クラスターに接続できない場合は、サービス、アクセス、または設定が正しく構成されていない可能性があります。ローカル環境が EKS クラスターの API サーバーと通信できない場合も、エラーが発生する可能性があります。表示されたエラーメッセージに応じて、問題をトラブルシューティングしてください。

注: AWS コマンドラインインターフェイス (AWS CLI) コマンドの実行中にエラーが発生した場合は、「AWS CLI で発生したエラーのトラブルシューティング」を参照してください。また、AWS CLI の最新バージョンを使用していることを確認してください。

前提条件:

次のコマンドを実行し、システムが正しいクラスターとの接続を確立できるかどうかを確認してください。
```
kubectl config current-context
```
次の AWS CLI コマンド get-caller-identity を実行し、現在認証されている AWS Identity and Access Management (IAM) ユーザーまたはロールが正確であることを確認してください。
```
aws sts get-caller-identity
```
注: IAM プリンシパルが、クラスター認証モードに基づいてクラスター上の Kubernetes オブジェクトにアクセスできるようにしてください。

エラーメッセージ "exec plugin invalid"

kubeconfig ファイル内の認証 API バージョンが Kubernetes API コントロールプレーンのバージョンと互換性がない場合、次のエラーメッセージが表示されます。

"exec plugin: invalid apiVersion "client.authentication.k8s.io/v1alpha""

次の update-kubeconfig コマンドを実行し、クラスターの kubeconfig ファイルを更新してください。

aws eks update-kubeconfig --region region-code --name my-cluster

注: 実際のものでそれぞれ、region-code をクラスターが置かれた AWS リージョンに、my-cluster をクラスター名に置き換えてください。

kubectl のバージョンは、使用する Amazon EKS クラスターのコントロールプレーンと比較して、前後 1 以内のマイナーバージョン差である必要があります。例えば、kubectl バージョン 1.29 のクライアントは Kubernetes 1.28、1.29、および 1.30 のクラスターで動作します。

エラーメッセージ "couldn't get current server API group list"

kubeconfig ファイルが存在しないか、認証機関 (CA) が含まれていない場合に次のエラーメッセージが表示されます。

"couldn't get current server API group list: Get "https://xxxxxxxxxxxxxxxxxxxx..eks.amazonaws.com/api?timeout=32s": tls: failed to verify certificate: x509: certificate signed by unknown authority"

次のコマンドを実行し、kubeconfig ファイルがホームディレクトリのデフォルトの場所 (.kube) に存在するかどうかを確認してください。
```
cat ~/.kube/config
```
ファイルが存在する場合は、base64 エンコードされたクラスター CA が kubeconfig ファイルに含まれるかどうかを確認してください。さらに、certificate-authority-data ファイルが存在し、正しく構成されているかどうかを確認してください。

kubeconfig ファイルが存在しない場合は、次のコマンドを実行して再作成してください。

kubectl get svc --insecure-skip-tls-verify

TLS をブロックする可能性のあるプロキシまたは VPN を使用していないかを確認してください。

タイムアウトエラーメッセージ "could not get current server API group list"

ソースホストが API サーバーとポート 443 で通信できない場合、リクエストはタイムアウトし、次のエラーメッセージが表示されます。

"could not get current server API group list: Get "https://xxxxxxxxxxxxxxxxxxxx.gr7.<region-code>.eks.amazonaws.com/api?timeout=32s": dial tcp xx.yy.zz.vvv:443: i/o timeout"

次のコマンドを実行すると、telnet をポート 443 に対して使用し、デバイスからの API サーバーエンドポイントへの接続を確認できます。

$ echo exit | telnet

出力例:

xxxxxxxxxxxxxxxxxxxx.gr7.us-east-2.eks.amazonaws.com 443Trying 18.224.160.210...
Connected to xxxxxxxxxxxxxxxxxxxx.gr7.us-east-2.eks.amazonaws.com.
Escape character is '^]'.
Connection closed by foreign host.

telnet コマンドでは問題が解決しない場合は、次の手順を実行してください。

API サーバーエンドポイントでパブリックアクセスを有効にした場合は、API サーバーエンドポイントへのアクセスを特定の CIDR 範囲に制限していないか確認してください。デバイスの IP アドレスが CIDR ブロック範囲内であることを確認してください。さらに、API サーバーエンドポイントへのアクセス動作を確認してください。
API サーバーエンドポイントでプライベートアクセスのみを有効にした場合は、すべてのクラスター API サーバーのトラフィックは、仮想プライベートクラウド (VPC) またはコネクテッドネットワークから送信する必要があります。なお、kubectl コマンドは、その VPC 内またはコネクテッドネットワーク内から実行する必要があります。詳細については、「プライベート専用 API サーバーへのアクセス」を参照してください。
セキュリティグループまたはネットワークアクセスコントロールリスト (ネットワーク ACL) が Kubernetes API サーバーへのリクエストをブロックしないかを確認してください。クラスターのセキュリティグループは、ソースの CIDR からのトラフィックをポート 443 で許可する必要があります。

エラーメッセージ "couldn't get current API server group list"

Amazon EKS クラスターの Kubernetes API へのアクセス許可が欠けた状態でアクションを実行しようとした場合、次のエラーメッセージが表示されます。

"couldn't get current server API group list: the server has asked for the client to provide credentials"

この問題を解決するには、次の手順を実行します。

get-caller-identity コマンドを実行し、EKS クラスターへのアクセスをリクエストしたユーザーを確認します。

aws sts get-caller-identity

出力例:

{
 "UserId": "user-ID",
 "Account": "account-ID",
 "Arn": "arn:aws:iam::account-ID:user/kube-user"
}

注: 上記の出力例には、リクエストを行った IAM エンティティのユーザー ID、AWS アカウント、ARN が含まれています。

認証モードを API_AND_CONFIG_MAP または API に変更し、EKS のアクセスエントリを使用して IAM ユーザーに Kubernetes へのアクセスを付与します。

適切な許可を付与するには、認証モードを API または API_AND_CONFIG_MAP に設定し、IAM エンティティのエントリを追加してください。
API 認証モード
次の create-access-entry を実行し、IAM プリンシパルが Amazon EKS クラスターに対する認証を行えるアクセスエントリを作成します。

aws eks create-access-entry --cluster-name my-cluster --principal-arn arn:aws:iam::111122223333:user/my-user --type STANDARD --username my-user

注: 上記のコマンドでは、プリンシパルの ARN を使用する IAM エンティティの ARN に置き換えてください。
次の associate-access-policy コマンドを実行して、アクセスエントリをアクセスポリシーに関連付けます。

aws eks associate-access-policy --cluster-name my-cluster --principal-arn arn:aws:iam::111122223333:role/my-role \
    --access-scope type=cluster --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSViewPolicy

API_AND_CONFIG_MAP 認証モード
API_AND_CONFIG_MAP 認証モードでは、上記の API 認証モードを使用しても、configmap を編集してもかまいません。
aws-auth configmap を編集するには、次のコマンドを実行します。

kubectl edit configmap aws-auth -n kube-system

IAM ロールまたはユーザーを mapRoles または mapUsers セクションに追加します。
IAM ロール用のエントリを含む mapRoles セクション例を次に示します。

mapRoles: |
    - groups:
      - system:masters
      rolearn: arn:aws:iam::111122223333:role/MyEKSrole
      username: eks-user

注: 例示した ARN を、使用する IAM ロールの ARN に置き換えてください。IAM ユーザーを使用する場合は、mapRoles を mapUsers に置き換え、ARN を IAM ユーザーの ARN に置き換えてください。

上記の例では、IAM プリンシパルを system:masters グループにマッピングしています。このグループは、クラスターに完全な管理アクセスを付与します。制限的なアクセスを付与する場合は、IAM プリンシパルをカスタム Kubernetes ユーザーまたはグループにマッピングし、Kubernetes のロールベースアクセス制御 (RBAC) を使用して必要な許可を定義してください。詳細については、Kubernetes のウェブサイトで「](https://kubernetes.io/docs/reference/access-authn-authz/rbac/)RBAC 認可を使用する[」を参照してください。

エラーメッセージ "Did you specify the right host or port?"

kubeconfig ファイルに構成ミスがある場合、kubectl は EKS クラスターに接続できず、次のエラーメッセージが表示されます。

"The connection to the server localhost:8080 was refused - did you specify the right host or port?"