From bacd7c39bf847e093d1215e5b8e1c740c96aa92f Mon Sep 17 00:00:00 2001
From: Justinas <12399634+justinas-b@users.noreply.github.com>
Date: Thu, 28 Sep 2023 13:10:14 +0300
Subject: [PATCH] docs: updating README.md with info (#16)

---
 README.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 91 insertions(+)

diff --git a/README.md b/README.md
index 49a99e2..c6b74d1 100644
--- a/README.md
+++ b/README.md
@@ -8,3 +8,94 @@
 ![GitHub](https://img.shields.io/github/license/justinas-b/aws-iam-authenticator-sso-wrapper)
 [![Go Report Card](https://goreportcard.com/badge/github.com/justinas-b/aws-iam-authenticator-sso-wrapper)](https://goreportcard.com/report/github.com/justinas-b/aws-iam-authenticator-sso-wrapper)
 ![GitHub last commit (branch)](https://img.shields.io/github/last-commit/justinas-b/aws-iam-authenticator-sso-wrapper/main)
+![Docker Image Version (latest semver)](https://img.shields.io/docker/v/justinasb/aws-iam-authenticator-sso-wrapper?logo=docker)
+![Docker Image Size (tag)](https://img.shields.io/docker/image-size/justinasb/aws-iam-authenticator-sso-wrapper/latest?logo=docker)
+
+## Purpose
+
+This tool addressess an issue when you use AWS SSO (AWS IAM Identity Center) roles to authenticate against your AWS EKS clusters. AWS natively supports authentication to AWS EKS when using [AWS IAM Roles](https://docs.aws.amazon.com/eks/latest/userguide/add-user-role.html), however you need to provide a role ARN and there is no way to provide AWS SSO PermissionSet name.
+
+IAM roles that are created from PermissionSets contain random suffixes, that can change whenever you would update PermissionSet's configuration locking you out from access to EKS. This becomes especially a headache when you have multiple EKS clusters that are spread across multiple AWS accounts.
+
+By default, on every EKS cluster you would have to provide `aws-auth` ConfigMap in `kube-system` namespace with corresponding role's ARN (excluding role's path):
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: aws-auth
+  namespace: kube-system
+data:
+  mapAccounts: |
+    []
+  mapRoles: |
+    - "groups":
+      - "system:masters"
+        "rolearn": "arn:aws:iam::000000000000:role/AWSReservedSSO_AdminRole_0123456789abcdef"
+        "username": "AdminRole:{{SessionName}}"
+  mapUsers: |
+    []
+```
+
+While using this tool, it enables you to deplou `aws-auth` ConfigMap to tool's namespace and provide PermissionSet's name instead of role ARN under `mapRoles` key:
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: aws-auth
+  namespace: aws-iam-authenticator-sso-wrapper
+data:
+  mapAccounts: |
+    []
+  mapRoles: |
+    - "groups":
+      - "system:masters"
+        "permissionSet": AdminRole"
+        "username": "AdminRole:{{SessionName}}"
+  mapUsers: |
+    []
+```
+
+The tool will process `aws-auth` ConfigMap from it's local kubernetes namespace and transform it to the format AWS EKS cluster expects. After processing ConfigMap, it's output is saved `kube-system` namespace where PermissionSet's name is translated to corresponding role ARN, meaning `"permissionSet": AdminRole"` line will become `"rolearn": "arn:aws:iam::000000000000:role/AWSReservedSSO_AdminRole_0123456789abcdef"`
+
+More details on this problem can found on below issues:
+
+- <https://github.com/aws/containers-roadmap/issues/185>
+- <https://github.com/aws/containers-roadmap/issues/474>
+- <https://github.com/aws/containers-roadmap/issues/1837>
+- <https://github.com/kubernetes-sigs/aws-iam-authenticator/pull/416>
+- <https://github.com/kubernetes-sigs/aws-iam-authenticator/issues/333>
+
+## Usage
+
+```text
+❯ aws-iam-authenticator-sso-wrapper -h
+Usage of aws-iam-authenticator-sso-wrapper:
+  -aws-region string
+        AWS region to use when interacting with IAM service (default "us-east-1")
+  -debug
+        Enable debug logging
+  -dst-configmap string
+        Name of the destination Kubernets ConfigMap which will be updated after transformation (default "aws-auth")
+  -dst-namespace string
+        Name of the destination Kubernetes Namespace where new ConfigMap will be updated (default "kube-system")
+  -interval int
+        Interval in seconds on which application will check for updates (default 1800)
+  -src-configmap string
+        Name of the source Kubernetes ConfigMap to read data from and perform transformation upon (default "aws-auth")
+  -src-namespace string
+        Kubernetes namespace from which to read ConfigMap which containes mapRoles with permissionset names. If not defined, current namespace of pod will be used
+```
+
+## Deployment
+
+Docker image can be obtained from [justinasb/aws-iam-authenticator-sso-wrapper](https://hub.docker.com/r/justinasb/aws-iam-authenticator-sso-wrapper).
+
+### Helm chart
+
+[work-in-progress]
+
+### Authentication
+
+For this tool to be able to authenticate with AWS (required when translating PermissionSet name to role ARN) it is recommended to use [AWS IRSA](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html), however any authentication methos it supported (you can also add ~/.aws/config or `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables.