AWS EKS Authentication: A Guide for IAM Principals with Terraform Example

Understanding how users or roles gain access to AWS Elastic Kubernetes Service (EKS) can be tricky for Kubernetes Developers. It’s quite differen from how access works on Azure Kubernetes Service (AKS) or self-hosted Kubernetes clusters. There are two main aspects to EKS access: IAM principles (like IAM users and IAM roles) and Cluster authentication.

To authenticate and access an EKS cluster, you need to be a valid IAM user and have access key ID and secret key for CLI tools. But let’s focus on how IAM users or roles authorize themselves for an EKS cluster. Each cluster has its own authentication method, and you can configure it using methods like the aws-auth ConfigMap, Access Entries, or a combination of both.

In the aws-auth ConfigMap method, the initial user is granted admin permission by default, and this user cannot be removed. They can add other IAM principles and permissions to the aws-auth ConfigMap in the kube-system namespace. However, this method is now deprecated.

A better approach is creating access entries to authenticate with the EKS cluster and attaching access entities policy to them. This method is preferable, especially for those using Infrastructure as Code (IAC) tools, as it allows managing access without directly accessing the cluster with CLI tools like kubectl and eksctl. This approach is beneficial when running IAC configuration code from a pipeline with a different user having limited access. With access entries, IAM principles can be added to a Kubernetes group, and access policies can be set at the cluster or namespace level.

You can also use a combination of these two methods, but once you switch from using only the ConfigMap option, you can’t revert back to it. For access entries, you need to enable the EKS API option in the access configuration section. Various policies like AmazonEKSAdminPolicy, AmazonEKSClusterAdminPolicy, AmazonEKSAdminViewPolicy, AmazonEKSEditPolicy, and AmazonEKSViewPolicy can be assigned to access entries for different levels of permissions.

Below, I’ve provided a simple Terraform example to show how to set up access entries and link policies to them.

In this demonstration, I’ll illustrate how access entries work for both an IAM user and an IAM role in EKS. You’ll see how to create access entries and then connect policies to them.

For further details on configuring your cluster, you can refer to the links below.

Terraform Registry

Terraform Registry

variable "iam_access_entries" {
  type = list(object({
    policy_arn     = string
    principal_arn  = string
  }))

  default = [
    {
      policy_arn    = "arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy"
      principal_arn = "arn:aws:iam::<YOUR_ACCOUNT_ID>:user/<USERNAME>"
    },
    {
      policy_arn    = "arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy"
      principal_arn = "arn:aws:iam::<YOUR_ACCOUNT_ID>:role/<ROLE_NAME>"
    },

  ]
}

resource "aws_eks_access_entry" "eks_access_entry" {
  for_each       = { for entry in var.iam_access_entries : entry.principal_arn => entry }
  cluster_name  = aws_eks_cluster.eks.name  # ensure that eks cluster is created with name eks
  principal_arn = each.value.principal_arn
  type          = "STANDARD"
}

resource "aws_eks_access_policy_association" "eks_policy_association" {
  for_each       = { for entry in var.iam_access_entries : entry.principal_arn => entry }
  cluster_name  = aws_eks_cluster.eks.name # ensure that eks cluster is created with name eks
  policy_arn    = each.value.policy_arn
  principal_arn = each.value.principal_arn

  access_scope {
    type       = "cluster"
  }
}

Reference:

Grant access to Kubernetes APIs