Warning

This project is archived as EKS now offers a viable alternative with Access Entries and we no longer intend to maintain this controller. If you still need it, please feel free to fork this repository.

---

AWS EKS iam-auth-controller

Kubernetes Controller tracking IAMIdentityMapping Custom Resource objects to maintain the AWS EKS aws-auth ConfigMap.

Background & Motivation for this project

AWS EKS uses the aws-auth ConfigMap in the kube-system namespace to map authenticated identities to Kubernetes username and groups. Using a single ConfigMap makes it hard and error prone to manage identity mappings using GitOps approach. The Kubernetes SIG's AWS IAM Authenticator for Kubernetes addresses this by providing a IAMIdentityMapping Custom Resource. However, that Custom Resource is still in alpha stage and is not yet enabled on the EKS control plane (master nodes).

This Kubernetes Controller closes the gap by implementing a Custom Resource Controller, updating the aws-auth ConfigMap from IAMIdentityMapping objects. Once #550 or #512 is resolved this controller will no longer be needed.

Examples

---
apiVersion: iamauthenticator.k8s.aws/v1alpha1
kind: IAMIdentityMapping
metadata:
  name: kubernetes-admin-user
spec:
  arn: arn:aws:iam::XXXXXXXXXXXX:user/KubernetesAdmin
  username: kubernetes-admin
  groups:
    - system:masters
---
apiVersion: iamauthenticator.k8s.aws/v1alpha1
kind: IAMIdentityMapping
metadata:
  name: kubernetes-admin-role
spec:
  arn: arn:aws:iam::XXXXXXXXXXXX:role/KubernetesAdmin
  username: kubernetes-admin
  groups:
    - system:masters

Getting Started

Add Helm Repository

AWS EKS iam-auth-controller can be installed via Helm Chart, which by default will use the prebuilt OCI Images for Linux (amd64 and arm64) from DockerHub.

helm repo add aws-eks-iam-auth-controller https://rustrial.github.io/aws-eks-iam-auth-controller

Install Helm Chart

helm install my-rustrial-aws-eks-iam-auth-controller aws-eks-iam-auth-controller/rustrial-aws-eks-iam-auth-controller --version 0.1.0

Adding default IAMIdentityMapping objects for EKS Nodes

As it is implemented today, the controller does only reconcile IAMIdentityMapping objects, and will overwrite (remove) all entries in aws-auth which have no corresponding IAMIdentityMapping object. To enable your EKS worker nodes respectively Fargate nodes to join your cluster, you have to deploy the corresponding IAMIdentityMapping objects like this:

kubectl apply -f- <<EOF
---
apiVersion: iamauthenticator.k8s.aws/v1alpha1
kind: IAMIdentityMapping
metadata:
  name: aws-ec2-nodes
spec:
  arn: 'arn:aws:iam::999999999999:role/your-ec2-node-role-name-here'
  groups:
    - 'system:bootstrappers'
    - 'system:nodes'
  username: 'system:node:{{EC2PrivateDNSName}}'
---
apiVersion: iamauthenticator.k8s.aws/v1alpha1
kind: IAMIdentityMapping
metadata:
  name: aws-fargate-nodes
spec:
  arn: 'arn:aws:iam::999999999999:role/your-fargate-node-role-name-here'
  groups:
    - 'system:bootstrappers'
    - 'system:nodes'
    - 'system:node-proxier'
  username: 'system:node:{{SessionName}}'
EOF

---

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
• The Unlicense (UNLICENSE or https://opensource.org/licenses/unlicense)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be triple licensed as above, without any additional terms or conditions. See the WAIVER and CONTRIBUTING.md files for more information.