Two EKS clusters, one AWS account, one console. I created the first one from inside SUSE Rancher for AWS and it went from Waiting to Active without asking me for anything at all. I imported the second one, a cluster that already existed, and it stopped dead on “Failed to communicate with cluster: Unauthorized”, zero machines, nothing on the screen telling me what to do next.

That error is not a bug and it is not a trial limitation. It is EKS being honest about where Kubernetes authorization actually lives, and it is the most useful thing in this article, because once you can read it you can predict which clusters in your account will stop before you touch any of them.

There are exactly two fixes. One command tells you which one you need, and getting that wrong is how an afternoon disappears into the wrong documentation page.

SUSE Rancher for AWS manages Amazon EKS clusters only. If your fleet is mixed, self-hosted SUSE Rancher Prime is the better fit.

 

What AWS gave your IAM role, and what it did not

The role you created when you linked your AWS account lets SUSE Rancher for AWS talk to the EKS API. Describe the cluster, list the node groups, manage the AWS resources around it.

It gives it nothing inside the cluster.

Kubernetes authorization is cluster local. It lives in the cluster’s own configuration, and AWS does not grant it on your behalf. An IAM role holding every EKS permission there is can read your cluster’s endpoint and its version, and cannot list a single pod in it.

That is the whole explanation. Everything below is the two sides of it.

 

Create: admin from birth

EKS Clusters

Figure 1. Active, one machine, and not one question asked of me on the way there.

When SUSE Rancher for AWS creates the cluster, its IAM role is the creator, and EKS gives the creating principal access to the inside of the cluster at build time. On a ConfigMap cluster that grant is implicit and there is no entry to manage or remove. On an access entry cluster it arrives as a cluster admin access entry, created by default unless whoever built the cluster switched that off. Either way the thing that built it is already in there.

Worth being precise about what you are looking at, because it is easy to read this as the tool being clever. It is not. It is what owning a cluster from birth buys you, and anything that creates the cluster gets the same deal.

 

Import: a stranger at the door

EKS Clusters

Figure 2. Two clusters built by two different tools, stopped in the same place, by the same sentence.

An imported cluster was built by somebody else. eksctl, Terraform, a colleague in the console two years ago, another Rancher. Whoever that was holds the access, and the role you just linked is not it.

Discovery finds the cluster, the import registers, the record appears in the list. Then the cluster agent cannot install itself, and you get the error.

Both rows in that screenshot are the same story. One of those clusters was built by SUSE Rancher for AWS and the other by Terraform, and the interesting part is that they need different fixes even though they failed identically.

 

The one command worth memorizing

Before you touch anything, read the cluster’s authentication mode:

aws eks describe-cluster --name <cluster> --region <region> \
  --query cluster.accessConfig.authenticationMode --output text

Check the mode first. It tells you whether the fix is a ConfigMap edit or an API call.

Three possible answers, which collapse into two fixes. CONFIG_MAP means editing the aws-auth ConfigMap from a kubectl session that already holds admin inside the cluster. API_AND_CONFIG_MAP and API both mean access entries: two AWS API calls, no kubectl anywhere.

The two clusters in the screenshot answered differently, and not by accident. The one SUSE Rancher for AWS built reported CONFIG_MAP. The one built by a current Terraform module reported API_AND_CONFIG_MAP, because the module defaults to access entries, which is the method AWS now recommends.

That split is the part to take away. If your clusters came from more than one place, and many fleets did, expect both answers inside the same account, and expect the one-liner above to be the fastest thing you run all week.

 

Fix one, CONFIG_MAP: edit aws-auth

From a kubectl session that already has admin in the cluster:

kubectl -n kube-system edit configmap aws-auth

Add the SUSE Rancher for AWS role ARN to mapRoles, leaving every existing entry exactly where it is (the node instance role is usually already in there, and removing it is a bad afternoon):

- rolearn: arn:aws:iam::<account>:role/<SRFA-role>
  username: sra
  groups:
  - system:masters

The constraint hiding in that first line is the interesting one. Only somebody who is already admin inside the cluster can make this edit, and on a cluster built by another Rancher the session that qualifies may be that Rancher’s own kubectl shell. So the fix does not start with the command. It starts with working out who owns the thing that built the cluster, which is a question some accounts can answer in a minute and some cannot answer at all.

 

Fix two, API_AND_CONFIG_MAP or API: create an access entry

aws eks create-access-entry --cluster-name <cluster> --region <region> --principal-arn "$ROLE_ARN"

aws eks associate-access-policy --cluster-name <cluster> --region <region> --principal-arn "$ROLE_ARN" \
  --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy \
  --access-scope type=cluster

No kubeconfig, no kubectl, and nobody needs to be inside the cluster already. An IAM administrator can run both commands having never had access to it, which is why this route moves through a change process more easily than the first one.

Clean the grant up the same way when you have finished evaluating: aws eks delete-access-entry --cluster-name <cluster> --region <region> --principal-arn "$ROLE_ARN", or edit aws-auth back.

The paragraph this section owes you

AmazonEKSClusterAdminPolicy is cluster admin. Not read only, not scoped to a namespace, cluster admin, and the same is true of system:masters in the other fix.

That is the correct grant for a management plane that is going to deploy an agent, reconcile state and run your RBAC. It is still a real change, and it deserves ten seconds of thought rather than a paste, because the honest version of “how long does importing a cluster take” is not three minutes. It is however long it takes you to decide that an external role should hold admin in that cluster.

 

Both of them, a minute later

EKS Clusters

Figure 3. Same two rows, two different fixes, and nothing was done on the Rancher side in between.

The ConfigMap cluster came back about 45 seconds after the entry was saved. The access entry cluster took about 90, most of it waiting for the cluster agent pod to come up. Neither number is worth optimizing and neither is worth quoting at anybody, because in the lab they swapped places depending on the run.

What matters is the shape of it. Nobody clicked anything in the console. Nobody re-ran the import. The cluster agent had been sitting there waiting for permission, not for an instruction, and the moment the permission existed it got on with it.

 

Three things not to conclude from this

aws-auth is not dead. AWS marks the ConfigMap as deprecated and points you at access entries. Clusters on CONFIG_MAP still work today, and your fleet will hold them for a long time yet.

Do not switch a cluster’s mode just to get the easier fix. aws eks update-cluster-config --name <cluster> --region <region> --access-config authenticationMode=API_AND_CONFIG_MAP works, and it only goes one way. If you want to move a cluster, rehearse it on one you do not care about first.

The Rancher EKS documentation covers the aws-auth route. It is right for a CONFIG_MAP cluster and it is not the fix for a cluster on access entries, so run the describe-cluster command before you follow it. That gap is the reason the one command above is the first thing I would tell anyone.

 

Doing this once is fine. Doing it per cluster is the problem

Everything above is one grant on one cluster. If you have one cluster, that is not a problem worth solving and you should go and do something else.

Now count the people who need access, multiply by the number of clusters, and add the ones you will build next quarter. Each cluster holds its own answer, in its own mechanism, and they drift apart quietly. Nothing in EKS gives you a view across them, and that is not a criticism of EKS. It runs clusters, and it runs them well. Fleet access sits on a different layer and was never in scope.

I make that argument properly in Do you really need more than EKS? An honest answer, which is the one to read if you are still deciding whether the layer is worth anything to you at all.

If you are past that question, take the smaller thing from this one. Unauthorized is not a failure. It is EKS telling you where authorization lives. Read the mode, grant the access once, and make that the last time you do it by hand.

 

The facts, plainly

  • SUSE Rancher for AWS manages Amazon EKS clusters. Not other clouds, not on-premises, not self-managed Kubernetes on EC2.

  • Reproduced in a lab on v2.15.1, with two clusters in one AWS account, one built by SUSE Rancher for AWS and one built by Terraform, both imported into a second instance.

  • EKS gives the principal that creates a cluster access inside it from the start. Every other principal, including an IAM role with full EKS permissions, starts with nothing.

  • cluster.accessConfig.authenticationMode tells you which fix applies. CONFIG_MAP means aws-auth. API_AND_CONFIG_MAP and API mean access entries.

  • AWS documents the aws-auth ConfigMap as deprecated and recommends access entries.

  • Pricing: $168 per month for a base of 24 managed vCPUs, then $7 per additional managed vCPU. EKS and EC2 costs are billed by AWS. There is a 30-day free trial.

 

Where to go next

Pick the EKS cluster somebody else built, the one where you are not completely sure who owns it. Read its authentication mode, grant the access once, and watch the row go Active while you are still looking at it.

One command and one grant, and at the end of it you can see that cluster from the same place as the others. Which is either worth something to you or it is not, and now you can find out without taking my word for it.

Start the 30-day trial on AWS Marketplace

Victor Estival Victor Estival is a Technical Marketing Manager at SUSE. Victor has been in the IT industry since 2002 and previously he worked for IBM, Canonical, Red Hat and Microsoft.