Awesome
aws-auth
The aws-auth utility and library makes the management of the aws-auth ConfigMap for EKS Kubernetes clusters easier and safer.
Use cases
-
make bootstrapping a node group or removing/adding user access on EKS fast and easy
-
useful for automation purposes, any workflow that needs to grant IAM access to an EKS cluster can use this library to modify the config map.
-
run as part of a workflow on kubernetes using a docker image
The aws-auth tool is referenced in the AWS EKS best practices documentation here.
Install
aws-auth includes both a CLI and a go library. You can install the CLI via go get or as a kubectl plugin via Krew or by downloading a binary from the releases page.
go get
go get github.com/keikoproj/aws-auth
aws-auth help
kubectl krew
Alternatively, install aws-auth with the krew plugin manager for kubectl.
kubectl krew install aws-auth
kubectl aws-auth
Download release artifact
The latest release artifacts can be downloaded from the GitHub releases page.
Or you can use the following command to download the latest release artifact for your platform:
curl -s https://api.github.com/repos/keikoproj/aws-auth/releases/latest
| grep "browser_download_url" \
| grep $(go env GOARCH) | grep $(go env GOOS) \
| cut -d : -f 2,3 \
| tr -d \" \
| wget -qi -
Usage from command line or Krew
Either download/install a released binary or add as a plugin to kubectl via Krew
$ kubectl krew update
$ kubectl krew install aws-auth
Installing plugin: aws-auth
Installed plugin: aws-auth
$ kubectl krew aws-auth
aws-auth modifies the aws-auth configmap on eks clusters
Usage:
aws-auth [command]
Available Commands:
help Help about any command
remove remove removes a user or role from the aws-auth configmap
remove-by-username remove-by-username removes all map roles and map users from the aws-auth configmap
upsert upsert updates or inserts a user or role to the aws-auth configmap
version Version of aws-auth
Flags:
-h, --help help for aws-auth
Use "aws-auth [command] --help" for more information about a command.
Given a config map with the following data:
$ kubectl get configmap aws-auth -n kube-system -o yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: aws-auth
namespace: kube-system
data:
mapRoles: |
- rolearn: arn:aws:iam::555555555555:role/devel-worker-nodes-NodeInstanceRole-74RF4UBDUKL6
username: system:node:{{EC2PrivateDNSName}}
groups:
- system:bootstrappers
- system:nodes
- rolearn: arn:aws:iam::555555555555:role/abc
username: ops-user
groups:
- system:masters
mapUsers: |
- userarn: arn:aws:iam::555555555555:user/a-user
username: admin
groups:
- system:masters
- userarn: arn:aws:iam::555555555555:user/a-user
username: ops-user
groups:
- system:masters
Remove all access belonging to an ARN (both mapUser roles will be removed)
$ aws-auth remove --mapusers --userarn arn:aws:iam::555555555555:user/a-user
removed arn:aws:iam::555555555555:user/a-user from aws-auth
Remove by full match (only mapUsers[0] will be removed)
$ aws-auth remove --mapusers --userarn arn:aws:iam::555555555555:user/a-user --username admin --groups system:masters
removed arn:aws:iam::555555555555:user/a-user from aws-auth
Remove based on a username
This command removes all map roles and map users that have matching input username. In the above configmap, map role for roleARN arn:aws:iam::555555555555:role/abc and mapUser for userARN arn:aws:iam::555555555555:user/a-user will be removed.
$ aws-auth remove-by-username --username ops-user
Bootstrap a new node group role
$ aws-auth upsert --maproles --rolearn arn:aws:iam::555555555555:role/my-new-node-group-NodeInstanceRole-74RF4UBDUKL6 --username system:node:{{EC2PrivateDNSName}} --groups system:bootstrappers system:nodes
added arn:aws:iam::555555555555:role/my-new-node-group-NodeInstanceRole-74RF4UBDUKL6 to aws-auth
You can also add retries with exponential backoff
$ aws-auth upsert --maproles --rolearn arn:aws:iam::555555555555:role/my-new-node-group-NodeInstanceRole-74RF4UBDUKL6 --username system:node:{{EC2PrivateDNSName}} --groups system:bootstrappers system:nodes --retry
Retries are configurable using the following flags
--retry Retry on failure with exponential backoff
--retry-max-count int Maximum number of retries before giving up (default 12)
--retry-max-time duration Maximum wait interval (default 30s)
--retry-min-time duration Minimum wait interval (default 200ms)
Append groups to mapping instead of overwriting by using --append
$ aws-auth upsert --maproles --rolearn arn:aws:iam::00000000000:role/test --username test --groups test --append
Avoid overwriting username by using --update-username=false
$ aws-auth upsert --maproles --rolearn arn:aws:iam::00000000000:role/test --username test2 --groups test --update-username=false
Use the get command to get a detailed view of mappings
$ aws-auth get
TYPE ARN USERNAME GROUPS
Role Mapping arn:aws:iam::555555555555:role/my-new-node-group system:node:{{EC2PrivateDNSName}} system:bootstrappers, system:nodes
use impersonate
aws-auth get|update|remove --as <username> --as-group <groupname>
Usage as a library
package main
import (
awsauth "github.com/keikoproj/aws-auth/pkg/mapper"
)
func someFunc(client kubernetes.Interface) error {
awsAuth := awsauth.New(client, false)
myUpsertRole := &awsauth.MapperArguments{
MapRoles: true,
RoleARN: "arn:aws:iam::555555555555:role/my-new-node-group-NodeInstanceRole-74RF4UBDUKL6",
Username: "system:node:{{EC2PrivateDNSName}}",
Groups: []string{
"system:bootstrappers",
"system:nodes",
},
WithRetries: true,
MinRetryTime: time.Millisecond * 100,
MaxRetryTime: time.Second * 30,
MaxRetryCount: 12,
}
err = awsAuth.Upsert(myUpsertRole)
if err != nil {
return err
}
}
Run in a container
$ docker run \
-v ~/.kube/:/root/.kube/ \
-v ~/.aws/:/root/.aws/ \
keikoproj/aws-auth:latest \
aws-auth upsert --mapusers \
--userarn arn:aws:iam::555555555555:user/a-user \
--username admin \
--groups system:masters