aws eks list-clusters: List EKS Clusters in CI
aws eks list-clusters returns the names of EKS clusters in the current region, the discovery step before a pipeline points kubectl at one.
Before a Kubernetes deploy, CI often confirms the target cluster exists and then fetches its kubeconfig. list-clusters is the lookup; it is strictly per-region.
What it does
aws eks list-clusters returns a clusters array of cluster names in the configured region. It paginates automatically. The output is just names; use describe-cluster for endpoint and version details, or update-kubeconfig to wire up kubectl.
Common usage
aws eks list-clusters --region us-east-1 \
--query 'clusters' --output text
# Then point kubectl at one
aws eks update-kubeconfig --region us-east-1 --name prod-clusterOptions
| Flag | What it does |
|---|---|
| --region <region> | Region to list (clusters are regional) |
| --query clusters --output text | Bare list of names |
| --max-results <n> | Page size |
In CI
EKS clusters are regional, so an empty list almost always means the wrong --region, not missing clusters. After confirming the cluster, run aws eks update-kubeconfig to write credentials for kubectl; that step needs eks:DescribeCluster. Authenticate via OIDC role assumption and ensure that role is mapped in the cluster aws-auth config (or an access entry) or kubectl calls return Unauthorized.
Common errors in CI
"An error occurred (AccessDeniedException) when calling the ListClusters operation: ... is not authorized to perform: eks:ListClusters" means missing list permission. An empty clusters array is usually a region mismatch. Note a separate, common follow-on failure: kubectl returning "error: You must be logged in to the server (Unauthorized)" means the assumed role is not mapped in the cluster's aws-auth ConfigMap or access entries, which is an EKS RBAC issue, not a CLI permission one.