Why can't I use kubectl to connect to my EKS cluster?

Resolution

If you can't connect to your Amazon EKS cluster when you use kubectl, then you might have incorrectly configured a service, permission, or setting. An error can also occur when the local environment can't communicate with the EKS cluster's API server. Troubleshoot your issue based on the error message that you receive.

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

Prerequisites:

• Run the following command to check whether the system can establish a connection with the correct cluster:

  kubectl config current-context

• Run the following get-caller-identity AWS CLI command to verify that the currently authenticated AWS Identity and Access Management (IAM) user or role is correct:

  aws sts get-caller-identity

  Note: Allow the IAM principal to access Kubernetes objects on your cluster based on the cluster authentication mode.

"exec plugin invalid" error message

When the authentication API version in the kubeconfig file isn't compatible with the Kubernetes API control plane version, you receive the following error message:

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

Run the following update-kubeconfig command to update the kubeconfig file for your cluster:

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

Note: Replace region-code with the AWS Region that your cluster is in and my-cluster with the name of your cluster.

Your kubectl version must be within one minor earlier or later version difference of your Amazon EKS cluster control plane. For example, a kubectl version 1.29 client works with Kubernetes 1.28, 1.29, and 1.30 clusters.

"couldn't get current server API group list" error message

When the kubeconfig file doesn't exist or doesn't contain the certificate authority (CA), you receive the following error message:

"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"

1. Run the following command to check whether the kubeconfig file exists in the default location (.kube) in your home directory:

   cat ~/.kube/config

2. If the file exists, then verify that the base64-encoded cluster CA is in the kubeconfig file. Also, check whether the certificate-authority-data file exists and you correctly configured it.

3. If the kubeconfig file doesn't exist, then run the following command to recreate it:

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

4. Check whether you use a proxy or VPN that might block TLS.

"could not get current server API group list" timeout error message

If the source host can't communicate with the API server on port 443, then the request times out and you receive the following error message:

"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"

Run the following command to use telnet on port 443 to check the API server endpoint connectivity from your device:

$ echo exit | telnet

Example output:

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.

If the telnet command doesn't resolve the issue, then take the following actions:

• If you activated public access on the API server endpoint, then check whether you restricted access to the API server endpoint to a certain CIDR range. Make sure that the device's IP address belongs to the CIDR block. Also, check the API server endpoint access behavior.
• If you activated only private access on the API server endpoint, then all cluster API server traffic must come from the virtual private cloud (VPC) or a connected network. Also, kubectl commands must come from within the VPC or a connected network. For more information, see Accessing a private only API server.
• Check whether the security groups or network access control lists (network ACLs) block requests to the Kubernetes API server. Make sure that the cluster security group allows traffic on port 443 from the source's CIDR.

"couldn't get current API server group list" error message

When you try to perform an action without permission to access the Kubernetes API on the Amazon EKS cluster, you receive the following error message:

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

To resolve the issue, complete the following steps:

1. Run the get-caller-identity command to check who made the request to access the EKS cluster:

   aws sts get-caller-identity

   Example output:

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

   Note: The preceding example output contains the User ID, AWS account, and ARN of the IAM entity that made the request.

2. Change the authentication mode to either API_AND_CONFIG_MAP or API, and then use EKS access entries to grant IAM users access to Kubernetes.

3. To grant the appropriate permissions, use either API or API_AND_CONFIG_MAP authentication mode to add the entry of the IAM entity.
   API authentication mode
   Run the following create-access-entry to create an access entry that allows the IAM principal to authenticate to your Amazon EKS cluster:

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

   Note: In the preceding command, replace the principal ARN with your IAM entity's ARN.
   Run the following associate-access-policy command to associate the access entry with an 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 authentication mode
   For API_AND_CONFIG_MAP authentication mode, you can use either the preceding API authentication mode, or you can edit the configmap.
   To edit aws-auth configmap, run the following command:

   kubectl edit configmap aws-auth -n kube-system

   Add your IAM role or user to the mapRoles or mapUsers section.
   The following is an example mapRoles section with an entry for an IAM role:

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

   Note: Replace the example ARN with the ARN of your IAM role. If you're using an IAM user, then replace MapRoles with MapUsers and the ARN with the IAM user's ARN.

The preceding example maps the IAM principal to the system:masters group that grants full administrative access to the cluster. For more restrictive access, map the IAM principal to a custom Kubernetes user or group, and use Kubernetes role-based access control (RBAC) objects to define the necessary permissions. For more information, see Using RBAC Authorization on the Kubernetes website.

"Did you specify the right host or port?" error message

If you didn't correctly configure the kubeconfig file, then kubectl can't connect to the EKS cluster, and you receive the following error message:

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

To resolve this issue, take the following actions:

• Run the following command to update the kubeconfig file:

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

• Run the following command to check the current context in your kubeconfig file:

  kubectl config current-context

• If the output of the current-context command doesn't point to the expected EKS cluster, then run the following command:

  kubectl config use-context ;

Related information

Connect kubectl to an EKS cluster by creating a kubeconfig file