https://github.com/qovery/iam-eks-user-mapper
A tool to automatically give AWS IAM users access to your Kubernetes cluster.
https://github.com/qovery/iam-eks-user-mapper
aws eks iam kubernetes rust
Last synced: 8 months ago
JSON representation
A tool to automatically give AWS IAM users access to your Kubernetes cluster.
- Host: GitHub
- URL: https://github.com/qovery/iam-eks-user-mapper
- Owner: Qovery
- License: mit
- Created: 2023-07-16T22:22:38.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2025-05-13T14:59:41.000Z (about 1 year ago)
- Last Synced: 2025-10-01T05:51:40.665Z (9 months ago)
- Topics: aws, eks, iam, kubernetes, rust
- Language: Rust
- Homepage:
- Size: 1.46 MB
- Stars: 51
- Watchers: 4
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# IAM EKS user mapper
This tool aims to automatically give selected AWS IAM users access to your Kubernetes cluster.
It's based on this [tool](https://github.com/ygrene/iam-eks-user-mapper) which is now archived, its main features were reported and extended (role based auth, and SSO for example).
## Design overview
IAM EKS user mapper is running as a pod in the kubernetes cluster.
At a given interval (default 30s) it executes the following:
**IF Groups users sync enabled**
1. Get IAM users from IAM groups to be given access to the cluster
2. Add IAM users from IAM groups `aws-auth` configmap in the cluster giving them access to the cluster
**IF SSO enabled**
- Add SSO role arn to `aws-auth` configmap in the cluster allowing users allowed to use this SSO role to connect to the cluster via SSO.
**IF Karpenter enabled**
- Add Karpenter role arn to `aws-auth` configmap in the cluster allowing Karpenter to create nodes in the cluster.
## Usage
```shell
./iam-eks-user-mapper \
--service-account-name \
# either fill aws-role-arn or aws-access-key-id and aws-secret-access-key
--aws-role-arn \
--aws-access-key-id \
--aws-secret-access-key \
--aws-default-region \
--admins-users-arns \
--enable-group-user-sync \
--iam-k8s-groups \
--enable-sso \
--iam-sso-role-arn \
--karpenter-arn \
--refresh-interval-seconds \
--verbose
```
| Parameter | Type | Default | Required | Description | Example |
| -------------------------- | --------- | ------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `service-account-name` | `String` | | `true` | Service account name to be used | `my-service-account` |
| `aws-role-arn` | `String` | | `true` if aws_access_key_id and aws_secret_access_key are not specified | AWS role ARN to be used | `arn:aws:iam::12345678910:role/my-role` |
| `aws_access_key_id` | `String` | | `true` if aws-role-arn is not specified | AWS Access Key ID to be used | `EXAMPLEACCESSKEYID` |
| `aws_secret_access_key` | `String` | | `true` if aws-role-arn is not specified | AWS Secret Access Key to be used | `EXAMPLESECRETACCESSKEY` |
| `aws_default_region` | `String` | | `true` | AWS default region to be used | `eu-west-3` |
| `refresh_interval_seconds` | `Integer` | `30` | `false` | Refresh interval in seconds between two user synchronization | `120` |
| `enable_group_user_sync` | `Boolean` | `false` | `false` | Activate User Groups sync | `true` |
| `admins_users_arns` | `String` | `""` | `false` | IAM users to be mapped into Kubernetes `system:masters`, syntax is `,` | `arn:aws:iam::123456789012:user/JohnDoe,arn:aws:iam::123456789012:user/JohnDoe2` |
| `iam_k8s_groups` | `String` | `""` | `false` (`true` if `enable_group_user_sync` == `true`) | IAM groups to be mapped into Kubernetes, syntax is `->,->` | `Admins->system:masters`, `Admins->system:masters,Devops->system:devops` |
| `enable_sso` | `Boolean` | `false` | `false` | Activate SSO support to connect to the cluster | `true` |
| `iam_sso_role_arn` | `String` | `""` | `false` (`true` if `enable_sso` == `true`) | IAM SSO role ARN to be used to connect to the cluster | `"arn:aws:iam::[AWS_ACCOUNT_ID]:role/aws-reserved/sso.amazonaws.com/[AWS_REGION]/AWSReservedSSO_AdministratorAccess_53b82e109c5e2cac"` |
| `karpenter_role_arn` | `String` | `""` | `false` | Enable Karpenter role ARN | `arn:aws:iam::account_id:role/role_id` |
| `verbose` | `Boolean` | `false` | `false` | Activate verbose mode | `Admins->system:masters`, `Admins->system:masters,Devops->system:devops` |
**Note:** Either `aws_role_arn` or `aws_access_key_id` and `aws_secret_access_key` must be provided. Both cannot be provided at the same time.
All parameters can be set as environment variables as well:
```shell
SERVICE_ACCOUNT_NAME= \
AWS_ROLE_ARN= \
AWS_ACCESS_KEY_ID= \
AWS_SECRET_ACCESS_KEY= \
AWS_DEFAULT_REGION= \
ADMINS_USERS_ARNS= \
ENABLE_GROUP_USER_SYNC= \
IAM_K8S_GROUPS= \
ENABLE_SSO= \
IAM_SSO_ROLE_ARN= \
KARPENTER_ROLE_ARN= \
REFRESH_INTERVAL_SECONDS= \
VERBOSE= \
./iam-eks-user-mapper
```
### Helm
Giving a `iam-eks-user-mapper.yaml` file with the following content:
```yaml
adminsUsersArns:
enabled:
arns: [] # ["arn:aws:iam::123456789012:user/JohnDoe"]
groupUsersSync:
enabled:
iamK8sGroups: # "group1,group2"
sso:
enabled:
iamSSORoleArn: # "arn:aws:iam::[AWS_ACCOUNT_ID]:role/aws-reserved/sso.amazonaws.com/[AWS_REGION]/AWSReservedSSO_AdministratorAccess_53b82e109c5e2cac"
karpenter:
enabled: false
iamKarpenterRoleArn: # "arn:aws:iam::[AWS_ACCOUNT_ID]:role/[ROLE_NAME]"
refreshIntervalSeconds:
aws:
defaultRegion:
# either fill roleArn or accessKeyId and secretAccessKey or existingSecretName
roleArn:
# if you want to use an existing secret, set the name here
# it must contain AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
existingSecretName:
accessKeyId:
secretAccessKey:
# Repository for the image is there
# https://github.com/Qovery/iam-eks-user-mapper
image:
repository: docker pull ghcr.io/qovery/iam-eks-user-mapper
pullPolicy: IfNotPresent
tag: main
serviceAccount:
name:
annotations:
- eks\\.amazonaws\\.com/role-arn=
resources:
limits:
cpu:
memory:
requests:
cpu:
memory:
```
```shell
helm upgrade \
--kubeconfig \
--install --namespace "kube-system" \
-f "iam-eks-user-mapper.yaml" \
iam-eks-user-mapper ./charts/iam-eks-user-mapper"
```
### Cargo
```shell
git clone https://github.com/Qovery/iam-eks-user-mapper.git && cd $_
cargo run -- \
--service-account-name \
--aws-role-arn \
--aws-default-region \
--admins-iam-users \
--enable-group-user-sync \
--iam-k8s-groups \
--enable-sso \
--iam-sso-role-arn \
--refresh-interval-seconds \
--verbose
```
### Docker
```shell
docker run ghcr.io/qovery/iam-eks-user-mapper:main \
-e IAM_K8S_GROUPS="" \
-e REFRESH_INTERVAL_SECONDS="" \
-e ENABLE_GROUP_USER_SYNC="" \
-e IAM_K8S_GROUPS="" \
-e ENABLE_SSO="" \
-e IAM_SSO_ROLE_ARN="" \
-e AWS_DEFAULT_REGION="" \
-e AWS_ROLE_ARN="" \
-e SERVICE_ACCOUNT_NAME=""
```
## AWS setup
### Setup a group to allow group sync
Allowing to sync IAM users from an IAM group giving IAM users access to the cluster.
First step to allow IAM user groups sync is to create a group to sync IAM side.
(Steps below are taken from [Qovery's official doc to setup an AWS cluster](https://hub.qovery.com/docs/using-qovery/configuration/cloud-service-provider/amazon-web-services/), it requires a dedicated group to run.)
1. Go to IAM AWS console
2. Create a new group **without permissions** (`Admins` in our example)
3. Add / create users within this `Admins` group
4. Pass group info `Admins` to be mapped to `system:masters` K8s role to `iam-eks-user-mapper`.
```shell
./iam-eks-user-mapper \
--service-account-name \
--aws-role-arn \
--aws-default-region \
--enable-group-user-sync true \
--iam-k8s-groups "Admins->system:masters"
```
### Setup SSO to allow SSO connection to the cluster
Allowing SSO connection to your k8s cluster.
You can use [this documentation](https://aws.amazon.com/fr/blogs/containers/a-quick-path-to-amazon-eks-single-sign-on-using-aws-sso/) to setup SSO to your AWS organization.
Once you've got your CLI configured and an `AWSReservedSSO_` role in IAM:
1. you can copy this role ARN
2. and pass it to `iam-eks-user-mapper`.
```shell
./iam-eks-user-mapper \
--service-account-name \
--aws-role-arn \
--aws-default-region \
--enable-sso true \
--iam-sso-role-arn "arn:aws:iam::84[..]37:role/aws-reserved/sso.amazonaws.com/us-east-2/AWSReservedSSO_AdministratorAccess_53b82e109c5e2cac"
```
## Good to know
The tool flags automatically synced entries via a custom field `syncedBy` set to `iam-eks-user-mapper`. This way, if you delete users from synced group and / or deactivate SSO sync or group sync, users / roles will be removed automatically.
```
│ - userarn: arn:aws:iam::843237546537:user/pleco
│ username: pleco
│ syncedBy: iam-eks-user-mapper
│ groups:
│ - system:masters
```
## Want to contribute?
This tool is far from perfect and we will be happy to have people helping making it better.
You can either:
- open an issue for bugs / enhancements
- open a PR linked to an issue
- pick an issue and submit a PR