How to connect an EKS cluster

1. Bring EKS into your kubeconfig

aws eks update-kubeconfig writes the cluster, the user and the context into ~/.kube/config. The context is named after the cluster ARN; --alias gives it a shorter name:

aws eks update-kubeconfig --region <region> --name <cluster> --alias <name>
kubectl get nodes

2. The exec plugin: aws eks get-token and aws-iam-authenticator

The EKS kubeconfig holds no token: it calls aws eks get-token (or, in older setups, aws-iam-authenticator), an exec plugin that signs a request with your IAM credential and produces a token that lasts a few minutes. That is why kubectl needs the AWS CLI and the credential on the machine.

Besides the credential, the IAM identity needs access to the cluster: an EKS access entry or, on older clusters, a line in the aws-auth ConfigMap.

Connect the EKS cluster to Kubepier Desktop

The desktop app reads the same ~/.kube/config and runs the exec plugin, just like kubectl. After update-kubeconfig, the cluster shows up in the catalog, under the client whose keyword matches its name.

Connect the EKS cluster to Kubepier Web: AWS account

The web connects from Kubepier’s server, where neither your AWS CLI nor your credential exist. That is why a context with an exec plugin is refused when you paste the kubeconfig, and the way in is the Cloud account tab, with an IAM access key. Kubepier scans the regions, adds every EKS it finds and, on each use, builds the same token aws eks get-token produces. Sync reads the account again.

In IAM, the key needs eks:ListClusters and eks:DescribeCluster (ec2:DescribeRegions is optional; without it, Kubepier scans the most common regions). In each cluster, an admin creates the access entry with the read-only policy:

aws eks create-access-entry --region <region> --cluster-name <cluster> \
  --principal-arn arn:aws:iam::<account>:user/<user>
aws eks associate-access-policy --region <region> --cluster-name <cluster> \
  --principal-arn arn:aws:iam::<account>:user/<user> \
  --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSViewPolicy \
  --access-scope type=cluster

If the cluster still authenticates only through the aws-auth ConfigMap, access entries need the API_AND_CONFIG_MAP authentication mode (aws eks update-cluster-config --access-config authenticationMode=API_AND_CONFIG_MAP).

In the form, fill in Access key ID and Secret access key; the session token and regions are optional. A temporary credential, with a session token, stops working when it expires.

Or a read-only kubeconfig with a ServiceAccount

If you do not want to add the AWS account, create a ServiceAccount with the view role in the cluster and build a kubeconfig with its token. Run it in your terminal, with the EKS context active, and paste the generated file under Paste kubeconfig. The view role does not read Secrets, so the Secrets list and the Helm releases stay empty.

kubectl create namespace kubepier
kubectl -n kubepier create serviceaccount kubepier-leitura
kubectl create clusterrolebinding kubepier-leitura \
  --clusterrole=view --serviceaccount=kubepier:kubepier-leitura
kubectl -n kubepier apply -f - <<'EOF'
apiVersion: v1
kind: Secret
metadata:
  name: kubepier-leitura-token
  annotations:
    kubernetes.io/service-account.name: kubepier-leitura
type: kubernetes.io/service-account-token
EOF

TOKEN=$(kubectl -n kubepier get secret kubepier-leitura-token -o jsonpath='{.data.token}' | base64 -d)
SERVER=$(kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}')
CA=$(kubectl config view --minify --raw -o jsonpath='{.clusters[0].cluster.certificate-authority-data}')
NOME=$(kubectl config current-context)

cat > kubepier.kubeconfig <<EOF
apiVersion: v1
kind: Config
clusters:
- name: $NOME
  cluster: { server: $SERVER, certificate-authority-data: $CA }
users:
- name: kubepier-leitura
  user: { token: $TOKEN }
contexts:
- name: $NOME
  context: { cluster: $NOME, user: kubepier-leitura }
current-context: $NOME
EOF

3. EKS endpoint public access CIDRs

If the cluster’s public endpoint only accepts some IPs, add Kubepier Web’s egress IPs (listed above and in Network and egress IPs) next to the ones already allowed. The command replaces the whole list:

aws eks describe-cluster --name <cluster> --query cluster.resourcesVpcConfig.publicAccessCidrs
aws eks update-cluster-config --name <cluster> \
  --resources-vpc-config endpointPublicAccess=true,publicAccessCidrs="<ip-1>/32,<ip-2>/32,<already-allowed-ips>"

The web cannot reach an EKS cluster with only a private endpoint. For it, use Kubepier Desktop through your VPN.

• Network and egress IPs
• Troubleshooting: AWS account and private clusters

Common errors when connecting EKS

• "uses an exec plugin" when pasting the kubeconfig on the web: use the Cloud account tab or the ServiceAccount kubeconfig.
• "no eks:ListClusters permission": the key’s IAM policy lacks the permission, in all or some regions.
• The cluster shows up, but the lists return 401 or 403: the IAM identity’s access entry, or its associated policy, is missing.
• Cluster unreachable: the public endpoint does not accept Kubepier’s egress IPs, or the cluster only has a private endpoint.

• Clusters and resources: what is accepted
• Connect an AKS cluster