:type: service
:name: EKS AWS Auth Merger
:description: Manage the aws-auth ConfigMap across multiple independent ConfigMaps.
:icon: /_docs/iam-role-icon.png
:category: docker-orchestration
:cloud: aws
:tags: docker, orchestration, kubernetes, containers
:license: gruntwork
:built-with: go, terraform

// AsciiDoc TOC settings
:toc:
:toc-placement!:
:toc-title:

// GitHub specific settings. See https://gist.github.com/dcode/0cfbf2699a1fe9b46ff04c41721dda74 for details.
ifdef::env-github[]
:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]

= EKS AWS Auth Merger

image:https://img.shields.io/badge/maintained%20by-gruntwork.io-%235849a6.svg[link="https://gruntwork.io/?ref=repo_aws_eks"]
image:https://img.shields.io/badge/tf-%3E%3D1.1.0-blue[Terraform version]
image:https://img.shields.io/badge/k8s-1.24%20~%201.28-5dbcd2[K8s version]

This module contains a go CLI, docker container, and terraform module for deploying a Kubernetes controller for managing
mappings between AWS IAM roles and users to RBAC groups in Kubernetes. The official way to manage the mapping is to add
values in a single, central `ConfigMap`. This module allows you to break up the central `ConfigMap` across multiple,
separate `ConfigMaps` each configuring a subset of the mappings you ultimately want to use, allowing you to update
entries in the `ConfigMap` in isolated modules (e.g., when you add a new IAM role in a separate module from the EKS
cluster). The `aws-auth-merger` watches for `aws-auth` compatible `ConfigMaps` that can be merged to manage the
`aws-auth` authentication `ConfigMap` for EKS.


toc::[]




== Features

* Break up the `aws-auth` Kubernetes `ConfigMap` across multiple objects.
* Automatically merge new `ConfigMaps` as they are added and removed.
* Track automatically generated `aws-auth` source `ConfigMaps` that are generated by EKS.



== Learn

NOTE: This repo is a part of https://gruntwork.io/infrastructure-as-code-library/[the Gruntwork Infrastructure as Code
Library], a collection of reusable, battle-tested, production ready infrastructure code. If you've never used the Infrastructure as Code Library before, make sure to read https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/[How to use the Gruntwork Infrastructure as Code Library]!

=== Core concepts

* _link:/modules/eks-k8s-role-mapping/README.md#what-is-kubernetes-role-based-access-control-rbac[What is Kubernetes
  RBAC?]_: overview of Kubernetes RBAC, the underlying system managing authentication and authorization in Kubernetes.

* _link:/modules/eks-k8s-role-mapping/README.md#what-is-aws-iam-role[What is AWS IAM role?]_: overview of AWS IAM Roles,
  the underlying system managing authentication and authorization in AWS.

* _https://docs.aws.amazon.com/eks/latest/userguide/add-user-role.html[Managing users or IAM roles for your cluster]_:
  The official AWS docs on how the `aws-auth` Kubernetes `ConfigMap` works.

* _link:core-concepts.md#what-is-the-aws-auth-merger[What is the aws-auth-merger?]_: overview of the `aws-auth-merger`
  and how it works to manage the `aws-auth` Kubernetes `ConfigMap`.


=== Repo organization

* link:/modules[modules]: the main implementation code for this repo, broken down into multiple standalone, orthogonal submodules.
* link:/examples[examples]: This folder contains working examples of how to use the submodules.
* link:/test[test]: Automated tests for the modules and examples.


== Deploy

=== Non-production deployment (quick start for learning)

If you just want to try this repo out for experimenting and learning, check out the following resources:

* link:/examples[examples folder]: The `examples` folder contains sample code optimized for learning, experimenting, and testing (but not production usage).

=== Production deployment

If you want to deploy this repo in production, check out the following resources:

* https://gruntwork.io/guides/kubernetes/how-to-deploy-production-grade-kubernetes-cluster-aws/#deployment_walkthrough[How to deploy a production-grade Kubernetes cluster on AWS]: A step-by-step guide for deploying a production-grade EKS cluster on AWS using the code in this repo.

**EKS Cluster**: Production-ready example code from the Reference Architecture:
* https://github.com/gruntwork-io/terraform-aws-service-catalog/blob/main/examples/for-production/infrastructure-live/prod/us-west-2/prod/services/eks-cluster/terragrunt.hcl[app account configuration]
* https://github.com/gruntwork-io/terraform-aws-service-catalog/blob/main/examples/for-production/infrastructure-live/_envcommon/services/eks-cluster.hcl[base configuration]




== Manage

* link:core-concepts.md#how-do-i-use-the-aws-auth-merger[How to deploy and use the aws-auth-merger]
* link:core-concepts.md#how-do-i-handle-conflicts-with-automatic-updates-by-eks[How to handle conflicts with automatic
  updates to the aws-auth ConfigMap by EKS]
* link:/modules/eks-k8s-role-mapping/README.md#restricting-specific-actions[How to restrict users to specific actions on the EKS cluster]
* link:/modules/eks-k8s-role-mapping/README.md#restricting-by-namespace[How to restrict users to specific namespaces on the EKS cluster]
* link:/core-concepts.md#how-to-authenticate-kubectl[How to authenticate kubectl to EKS]




== Support

If you need help with this repo or anything else related to infrastructure or DevOps, Gruntwork offers https://gruntwork.io/support/[Commercial Support] via Slack, email, and phone/video. If you're already a Gruntwork customer, hop on Slack and ask away! If not, https://www.gruntwork.io/pricing/[subscribe now]. If you're not sure, feel free to email us at link:mailto:support@gruntwork.io[support@gruntwork.io].




== Contributions

Contributions to this repo are very welcome and appreciated! If you find a bug or want to add a new feature or even contribute an entirely new module, we are very happy to accept pull requests, provide feedback, and run your changes through our automated test suite.

Please see https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/#contributing-to-the-gruntwork-infrastructure-as-code-library[Contributing to the Gruntwork Infrastructure as Code Library] for instructions.




== License

Please see link:LICENSE.md[LICENSE.md] for details on how the code in this repo is licensed.
