Refactor driver permissions docs and add Pod Identities

Signed-off-by: Connor Catlett <[email protected]>

docs/install.md

@@ -50,20 +50,40 @@ Note: Add the below statement to the example policy if you want to encrypt the E
 }
 ```
 
-For more information, review ["Creating the Amazon EBS CSI driver IAM role for service accounts" from the EKS User Guide.](https://docs.aws.amazon.com/eks/latest/userguide/csi-iam-role.html) 
+#### (EKS Only) EKS Pod Identity
 
-There are several methods to grant the driver IAM permissions:
-* Using IAM [instance profile](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html) - attach the policy to the instance profile IAM role and turn on access to [instance metadata](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) for the instance(s) on which the driver Deployment will run
-* EKS only: Using [IAM roles for ServiceAccounts](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) - create an IAM role, attach the policy to it, then follow the IRSA documentation to associate the IAM role with the driver Deployment service account, which if you are installing via Helm is determined by value `controller.serviceAccount.name`, `ebs-csi-controller-sa` by default. If you are using k8s 1.24 or higher, the ServiceAccountToken is not mounted because the `LegacyServiceAccountTokenNoAutoGeneration` feature gate is enabled.
-Therefore, if you are using k8s 1.24 or higher, you need to set `true` to `controller.serviceAccount.autoMountServiceAccountToken`.
-* Using secret object - create an IAM user, attach the policy to it, then create a generic secret in the `kube-system` namespace with the user's credentials. The snippet below creates the generic secret named `aws-secret` that the driver accepts by default. You can customize the default secret and key names via the Helm parameters `awsAccessSecret.name`, `awsAccessSecret.keyId`, and `awsAccessSecret.accessKey` in the chart's [values.yaml](https://github.com/kubernetes-sigs/aws-ebs-csi-driver/blob/master/charts/aws-ebs-csi-driver/values.yaml). 
-```sh
-kubectl create secret generic aws-secret \
-    --namespace kube-system \
-    --from-literal "key_id=${AWS_ACCESS_KEY_ID}" \
-    --from-literal "access_key=${AWS_SECRET_ACCESS_KEY}"
+[EKS Pod Identity](https://docs.aws.amazon.com/eks/latest/userguide/pod-identities.html) is the recoomended method to provide IAM credentials to pods running on EKS clusters. 
+
+When using EKS pod identity with the EBS CSI Driver, grant a role containing the policy to the `ebs-csi-controller-sa` service account in the namespace the EBS CSI Driver is deployed (typically `kube-system`). Using EKS Pod Identity requires installation of the EKS Pod Identity agent and the role trust policy must trust `pods.eks.amazonaws.com` - for full instructions see the [EKS docs for setting up EKS Pod Identity](https://docs.aws.amazon.com/eks/latest/userguide/pod-identities.html#pod-id-setup-overview).
+
+#### IAM Roles for ServiceAccounts (i.e. IRSA)
+
+[IAM roles for ServiceAccounts](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) is a method of enabling pods using a Kubernetes ServiceAccount to exhance the service account token for IAM credentials. Using IRSA requires a specially configured trust policy, as well as setup of an OIDC endpoint for the cluster. On EKS, [refer to the EKS docs for setting up IRSA](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html#:~:text=Enable%20IAM%20roles%20for%20service%20accounts%20by%20completing%20the%20following%20procedures:). On other cluster providers, refer to their documentation for steps to setup IRSA.
+
+When deploying the EBS CSI Driver via Helm, the parameter `controller.serviceAccount.annotations` can be used to add the necessary annotation for IRSA, for example with the following values:
+```
+controller:
+  serviceAccount:
+    annotations:
+      eks.amazonaws.com/role-arn: arn:aws:iam::123412341234:role/ebs-csi-role
 ```
 
+#### Secret Object
+
+When deplying via Helm, the chart can be configured to pass IAM credentials stored in a Kubernetes `Secret` to the EBS CSI Driver. This option may be useful in confunction with third party software that stores credentials in a secret. This is configured using the `awsAccessSecret` Helm parameter:
+```
+awsAccessSecret:
+  name: aws-secret # This should be the name of the secret (must be in the same namespace as the driver deployment, typically kube-system)
+  keyId: key_id # This is the name of the key on the secret that holds the AWS Key ID
+  accessKey: access_key # This is the name of the key on the secret that holds the AWS Secret Access Key
+```
+
+#### (Not Recommended) IAM Instance Profile
+
+[EC2 IAM Instance Profiles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html) enable sharing IAM credentials with software running on EC2 instances. The policy must be attached to the instance IAM role, and the EBS CSI Driver must be able to reach IMDS in order to retrieve the credentials. In order for the driver to access IMDS, it either must be run in host networking mode, or with a [hop limit of at least 2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-IMDS-existing-instances.html#modify-PUT-response-hop-limit).
+
+This method is not recommended in production environments because any pod or software running on the ndoe with access to IMDS could assume the role and access the wide permissions of the EBS CSI Driver, violating the best practice of [restricting pod access to the instance role](https://aws.github.io/aws-eks-best-practices/security/docs/iam/#restrict-access-to-the-instance-profile-assigned-to-the-worker-node).
+
 ### Configure driver toleration settings
 By default, the driver controller tolerates taint `CriticalAddonsOnly` and has `tolerationSeconds` configured as `300`; and the driver node tolerates all taints. If you don't want to deploy the driver node on all nodes, please set Helm `Value.node.tolerateAllTaints` to false before deployment. Add policies to `Value.node.tolerations` to configure customized toleration for nodes.