Add documentation for pod identity associations feature (eksctl-io#7313)

* Add documentation for pod identity associations * add more details to how pod identity agent addon works * remove unnecessary empty lines * refactor as per PR suggestions * add references to official AWS docs * generate docs * rephrase intro Co-authored-by: Himangini <its_himangini@yahoo.com> * rephrase news section Co-authored-by: Himangini <its_himangini@yahoo.com> * add newline between docs links --------- Co-authored-by: Himangini <its_himangini@yahoo.com>
TiberiuGC · Nov 27, 2023 · ce93249 · ce93249
1 parent 73aa3d1
commit ce93249
Show file tree

Hide file tree

Showing 5 changed files with 227 additions and 0 deletions.
diff --git a/examples/39-pod-identity-association.yaml b/examples/39-pod-identity-association.yaml
@@ -0,0 +1,52 @@
+# An example config for creating pod identity associations.
+---
+apiVersion: eksctl.io/v1alpha5
+kind: ClusterConfig
+
+metadata:
+  name: cluster-39
+  region: us-west-2
+
+managedNodeGroups:
+  - name: mng1
+
+addons:
+  - name: eks-pod-identity-agent # required for `iam.podIdentityAssociations`
+    tags:
+      team: eks
+
+iam:  
+  podIdentityAssociations: 
+  # roleARN is given, eksctl will only create the pod identity association 
+  - namespace: default
+    serviceAccountName: s3-reader
+    roleARN: arn:aws:iam::111122223333:role/role-1 
+
+  # roleARN is not given, eksctl will first create an IAM role with given roleName using:
+  # permissionPolicyARNs, wellKnownPolicies and permissionsBoundaryARN 
+  - namespace: dev
+    serviceAccountName: app-cache-access
+    roleName: pod-identity-role-app-cache
+    permissionPolicyARNs: ["arn:aws:iam::111122223333:policy/permission-policy-1", "arn:aws:iam::111122223333:policy/permission-policy-2"]
+    wellKnownPolicies:
+      autoScaler: true
+      externalDNS: true
+    permissionsBoundaryARN: arn:aws:iam::111122223333:policy/permission-boundary
+
+  # roleARN is not given, eksctl will first create an IAM role with automatically generated roleName,
+  # using the permissionPolicy inline document
+  - namespace: dev
+    serviceAccountName: nginx
+    permissionPolicy:
+      Version: "2012-10-17"
+      Statement:
+      - Effect: Allow
+        Action:
+        - "autoscaling:DescribeAutoScalingGroups"
+        - "autoscaling:DescribeAutoScalingInstances"
+        - "autoscaling:DescribeLaunchConfigurations"
+        - "autoscaling:DescribeTags"
+        - "autoscaling:SetDesiredCapacity"
+        - "autoscaling:TerminateInstanceInAutoScalingGroup"
+        - "ec2:DescribeLaunchTemplateVersions"
+        Resource: '*'
diff --git a/userdocs/mkdocs.yml b/userdocs/mkdocs.yml
@@ -187,6 +187,7 @@ nav:
       - usage/iam-policies.md
       - usage/iam-identity-mappings.md
       - usage/iamserviceaccounts.md
+      - usage/pod-identity-associations.md
     - usage/dry-run.md
     - usage/schema.md
     - usage/eksctl-anywhere.md

diff --git a/userdocs/src/getting-started.md b/userdocs/src/getting-started.md
@@ -1,6 +1,8 @@
 # Getting started
 
 !!! tip "New for 2023"
+    `eksctl` now supports configuring fine-grained permissions to EKS running apps via [EKS Pod Identity Associations](/usage/pod-identity-associations)
+
     `eksctl` now supports [updating the subnets and security groups](/usage/cluster-subnets-security-groups) associated with the EKS control plane.
 
     `eksctl` now supports creating fully private clusters on [AWS Outposts](/usage/outposts).

diff --git a/userdocs/src/usage/pod-identity-associations.md b/userdocs/src/usage/pod-identity-associations.md
@@ -0,0 +1,171 @@
+# EKS Pod Identity Associations
+
+## Introduction
+
+AWS EKS has introduced a new enhanced mechanism called Pod Identity Association for cluster administrators to configure Kubernetes applications to receive IAM permissions required to connect with AWS services outside of the cluster. Pod Identity Association leverages IRSA however, it makes it configurable directly through EKS API, eliminating the need for using IAM API altogether. 
+
+As a result, IAM roles no longer need to reference an [OIDC provider](/usage/iamserviceaccounts/#how-it-works) and hence won't be tied to a single cluster anymore. This means, IAM roles can now be used across multiple EKS clusters without the need to update the role trust policy each time a new cluster is created. This in turn, eliminates the need for role duplication and simplifies the process of automating IRSA altogether.
+
+## Prerequisites
+
+Behind the scenes, the implementation of pod identity associations is running an agent as a daemonset on the worker nodes. To run the pre-requisite agent on the cluster, EKS provides a new add-on called EKS Pod Identity Agent. Therefore, creating pod identity associations (with `eksctl`) requires the `eks-pod-identity-agent` addon pre-installed on the cluster. This addon can be [created using `eksctl`](/usage/addons/#creating-addons) in the same fashion any other supported addon is, e.g.
+
+```
+eksctl create addon --cluster my-cluster --name eks-pod-identity-agent
+```
+
+Additionally, if using a pre-existing IAM role when creating a pod identity association, you must configure the role to trust the newly introduced EKS service principal (`pods.eks.amazonaws.com`). An example IAM trust policy can be found below:
+
+```json
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Effect": "Allow",
+            "Principal": {
+                "Service": "pods.eks.amazonaws.com"
+            },
+            "Action": [
+                "sts:AssumeRole",
+                "sts:TagSession"
+            ]
+        }
+    ]
+}
+```
+
+If instead you do not provide the ARN of an existing role to the create command, `eksctl` will create one behind the scenes and configure the above trust policy.
+
+## Creating Pod Identity Associations
+
+For manipulating pod identity associations, `eksctl` has added a new field under `iam.podIdentityAssociations`, e.g.
+
+```yaml
+iam:  
+  podIdentityAssociations: 
+  - namespace: <string> #required
+    serviceAccountName: <string> #required
+    roleARN: <string> #required if none of permissionPolicyARNs, permissionPolicy and wellKnownPolicies is specified. Also, cannot be used together with any of the three other referenced fields.
+    roleName: <string> #optional, generated automatically if not provided, ignored if roleARN is provided
+    permissionPolicy: {} #optional
+    permissionPolicyARNs: [] #optional
+    wellKnownPolicies: {} #optional
+    permissionsBoundaryARN: <string> #optional
+    tags: {} #optional
+```
+
+For a complete example, refer to [pod-identity-associations.yaml](https://github.com/eksctl-io/eksctl/blob/main/examples/38-cluster-subnets-sgs.yaml).
+
+???+ note
+    Apart from `permissionPolicy` which is used as an inline policy document, all other fields have a CLI flag counterpart.
+
+Creating pod identity associations can be achieved in the following ways. During cluster creation, by specifying the desired pod identity associations as part of the config file and running:
+
+```
+eksctl create cluster -f config.yaml
+```
+
+Post cluster creation, using either a config file e.g.
+
+```
+eksctl create podidentityassociation -f config.yaml
+```
+
+OR using CLI flags e.g.
+
+```bash
+eksctl create podidentityassociation \
+    --cluster my-cluster \
+    --namespace default \
+    --service-account-name s3-reader \
+    --permission-policy-arns="arn:aws:iam::111122223333:policy/permission-policy-1, arn:aws:iam::111122223333:policy/permission-policy-2" \
+    --well-known-policies="autoScaler,externalDNS" \
+    --permissions-boundary-arn arn:aws:iam::111122223333:policy/permissions-boundary
+```
+
+???+ note
+    Only a single IAM role can be associated with a service account at a time. Therefore, trying to create a second pod identity association for the same service account will result in an error.
+
+## Fetching Pod Identity Associations
+
+To retrieve all pod identity associations for a certain cluster, run one of the following commands:
+
+```
+eksctl get podidentityassociation -f config.yaml
+```
+
+OR
+
+```
+eksctl get podidentityassociation --cluster my-cluster
+```
+
+Additionally, to retrieve only the pod identity associations within a given namespace, use the `--namespace` flag, e.g.
+
+```
+eksctl get podidentityassociation --cluster my-cluster --namespace default
+```
+
+Finally, to retrieve a single association, corresponding to a certain K8s service account, also include the `--service-account-name` to the command above, i.e.
+
+```
+eksctl get podidentityassociation --cluster my-cluster --namespace default --service-account-name s3-reader
+```
+
+## Updating Pod Identity Associations
+
+To update the IAM role of one or more pod identity associations, either pass the new `roleARN(s)` to the config file e.g.
+
+```yaml
+iam:
+  podIdentityAssociations:
+    - namespace: default
+      serviceAccountName: s3-reader
+      roleARN: new-role-arn-1
+    - namespace: dev
+      serviceAccountName: app-cache-access
+      roleARN: new-role-arn-2
+```
+
+and run:
+
+```
+eksctl update podidentityassociation -f config.yaml
+```
+
+OR (to update a single association) pass the new `--role-arn` via CLI flags:
+
+```
+eksctl update podidentityassociation --cluster my-cluster --namespace default --service-account-name s3-reader --role-arn new-role-arn
+```
+
+## Deleting Pod Identity Associations
+
+To delete one or more pod identity associations, either pass `namespace(s)` and `serviceAccountName(s)` to the config file e.g.
+
+```yaml
+iam:
+  podIdentityAssociations:
+    - namespace: default
+      serviceAccountName: s3-reader
+    - namespace: dev
+      serviceAccountName: app-cache-access
+```
+
+and run:
+
+```
+eksctl delete podidentityassociation -f config.yaml
+```
+
+OR (to delete a single association) pass the `--namespace` and `--service-account-name` via CLI flags:
+
+```
+eksctl delete podidentityassociation --cluster my-cluster --namespace default --service-account-name s3-reader 
+```
+
+## Further references
+
+[Official AWS Blog Post](https://aws.amazon.com/blogs/aws/amazon-eks-pod-identity-simplifies-iam-permissions-for-applications-on-amazon-eks-clusters/)
+
+[Official AWS userdocs](https://docs.aws.amazon.com/eks/latest/userguide/pod-identities.html)
diff --git a/userdocs/theme/home.html b/userdocs/theme/home.html
@@ -541,6 +541,7 @@ <h2><code>eksctl create cluster</code></h2>
                         <a href="/usage/outposts" tabindex="-1" title="Usage Outposts"><img src="assets/images/outposts.png" alt="Usage Outposts" loading="lazy"></a>
                         <figcaption class="md-typeset">
                             <h2>New for {{ build_date_utc.strftime('%Y') }}</h2>
+                            <p>Configuring fine-grained permissions to EKS running apps via <a href="/usage/pod-identity-associations">EKS Pod Identity Associations</a>.</p>
                             <p>Creating fully private clusters on <a href="/usage/outposts">AWS Outposts</a>.</p> 
                             <p>Supported Regions - Zurich (<code>eu-central-2</code>), 
                                     Spain (<code>eu-south-2</code>),