Merge pull request #2287 from ConnorJC3/iam-policy-new

Update example policy and documentation

Author: k8s-ci-robot

docs/example-iam-policy.json

@@ -4,46 +4,76 @@
     {
       "Effect": "Allow",
       "Action": [
-        "ec2:CreateSnapshot",
-        "ec2:AttachVolume",
-        "ec2:DetachVolume",
-        "ec2:ModifyVolume",
         "ec2:DescribeAvailabilityZones",
         "ec2:DescribeInstances",
         "ec2:DescribeSnapshots",
         "ec2:DescribeTags",
         "ec2:DescribeVolumes",
-        "ec2:DescribeVolumesModifications",
-        "ec2:EnableFastSnapshotRestores"
+        "ec2:DescribeVolumesModifications"
       ],
       "Resource": "*"
     },
     {
       "Effect": "Allow",
       "Action": [
-        "ec2:CreateTags"
+        "ec2:CreateSnapshot",
+        "ec2:ModifyVolume"
+      ],
+      "Resource": "arn:aws:ec2:*:*:volume/*"
+    },
+    {
+      "Effect": "Allow",
+      "Action": [
+        "ec2:AttachVolume",
+        "ec2:DetachVolume"
       ],
       "Resource": [
-        "arn:*:ec2:*:*:volume/*",
-        "arn:*:ec2:*:*:snapshot/*"
+        "arn:aws:ec2:*:*:volume/*",
+        "arn:aws:ec2:*:*:instance/*"
       ]
     },
+    {
+      "Effect": "Allow",
+      "Action": [
+        "ec2:CreateVolume",
+        "ec2:EnableFastSnapshotRestores"
+      ],
+      "Resource": "arn:aws:ec2:*:*:snapshot/*"
+    },
+    {
+      "Effect": "Allow",
+      "Action": [
+        "ec2:CreateTags"
+      ],
+      "Resource": [
+        "arn:aws:ec2:*:*:volume/*",
+        "arn:aws:ec2:*:*:snapshot/*"
+      ],
+      "Condition": {
+        "StringEquals": {
+          "ec2:CreateAction": [
+            "CreateVolume",
+            "CreateSnapshot"
+          ]
+        }
+      }
+    },
     {
       "Effect": "Allow",
       "Action": [
         "ec2:DeleteTags"
       ],
       "Resource": [
-        "arn:*:ec2:*:*:volume/*",
-        "arn:*:ec2:*:*:snapshot/*"
+        "arn:aws:ec2:*:*:volume/*",
+        "arn:aws:ec2:*:*:snapshot/*"
       ]
     },
     {
       "Effect": "Allow",
       "Action": [
         "ec2:CreateVolume"
       ],
-      "Resource": "arn:*:ec2:*:*:volume/*",
+      "Resource": "arn:aws:ec2:*:*:volume/*",
       "Condition": {
         "StringLike": {
           "aws:RequestTag/ebs.csi.aws.com/cluster": "true"
@@ -55,7 +85,7 @@
       "Action": [
         "ec2:CreateVolume"
       ],
-      "Resource": "arn:*:ec2:*:*:volume/*",
+      "Resource": "arn:aws:ec2:*:*:volume/*",
       "Condition": {
         "StringLike": {
           "aws:RequestTag/CSIVolumeName": "*"
@@ -65,19 +95,24 @@
     {
       "Effect": "Allow",
       "Action": [
-        "ec2:CreateVolume"
+        "ec2:DeleteVolume"
       ],
-      "Resource": "arn:*:ec2:*:*:snapshot/*"
+      "Resource": "arn:aws:ec2:*:*:volume/*",
+      "Condition": {
+        "StringLike": {
+          "ec2:ResourceTag/ebs.csi.aws.com/cluster": "true"
+        }
+      }
     },
     {
       "Effect": "Allow",
       "Action": [
         "ec2:DeleteVolume"
       ],
-      "Resource": "*",
+      "Resource": "arn:aws:ec2:*:*:volume/*",
       "Condition": {
         "StringLike": {
-          "ec2:ResourceTag/ebs.csi.aws.com/cluster": "true"
+          "ec2:ResourceTag/CSIVolumeName": "*"
         }
       }
     },
@@ -86,22 +121,34 @@
       "Action": [
         "ec2:DeleteVolume"
       ],
-      "Resource": "*",
+      "Resource": "arn:aws:ec2:*:*:volume/*",
       "Condition": {
         "StringLike": {
-          "ec2:ResourceTag/CSIVolumeName": "*"
+          "ec2:ResourceTag/kubernetes.io/created-for/pvc/name": "*"
         }
       }
     },
     {
       "Effect": "Allow",
       "Action": [
-        "ec2:DeleteVolume"
+        "ec2:CreateSnapshot"
       ],
-      "Resource": "*",
+      "Resource": "arn:aws:ec2:*:*:snapshot/*",
       "Condition": {
         "StringLike": {
-          "ec2:ResourceTag/kubernetes.io/created-for/pvc/name": "*"
+          "aws:RequestTag/CSIVolumeSnapshotName": "*"
+        }
+      }
+    },
+    {
+      "Effect": "Allow",
+      "Action": [
+        "ec2:CreateSnapshot"
+      ],
+      "Resource": "arn:aws:ec2:*:*:snapshot/*",
+      "Condition": {
+        "StringLike": {
+          "aws:RequestTag/ebs.csi.aws.com/cluster": "true"
         }
       }
     },
@@ -110,7 +157,7 @@
       "Action": [
         "ec2:DeleteSnapshot"
       ],
-      "Resource": "*",
+      "Resource": "arn:aws:ec2:*:*:snapshot/*",
       "Condition": {
         "StringLike": {
           "ec2:ResourceTag/CSIVolumeSnapshotName": "*"
@@ -122,7 +169,7 @@
       "Action": [
         "ec2:DeleteSnapshot"
       ],
-      "Resource": "*",
+      "Resource": "arn:aws:ec2:*:*:snapshot/*",
       "Condition": {
         "StringLike": {
           "ec2:ResourceTag/ebs.csi.aws.com/cluster": "true"

docs/install.md

@@ -35,20 +35,48 @@ Kubernetes metadata does not provide information about the number of ENIs or EBS
 
 ## Installation
 ### Set up driver permissions
-The driver requires IAM permissions to talk to Amazon EBS to manage the volume on user's behalf. [The example policy here](./example-iam-policy.json) defines these permissions. AWS maintains a managed policy, available at ARN `arn:aws:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicy`. 
 
-The baseline example policy does not give the EBS CSI Driver access to KMS keys to use to encrypt volumes. If you wish to encrypt volumes, add an additional statement to the role granting these permissions, for example the below statement would grant the driver access to all KMS keys in the account:
-```
+> [!NOTE]  
+> The example policy and documentation below use the [`aws` partition in ARNs](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html). When installing the EBS CSI Driver on other partitions, replace instances of `arn:aws:` with the local partition, such as `arn:aws-us-gov:` for AWS GovCloud.
+
+The driver requires IAM permissions to talk to Amazon EBS to manage the volume on user's behalf. [The example policy here](./example-iam-policy.json) defines these permissions. AWS maintains a [managed policy version of the example policy](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonEBSCSIDriverPolicy.html), available at ARN `arn:aws:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicy`.
+
+The baseline example policy excludes permissions for some rarer and potentially dangerous usecases. For these usecases, additional statements are necessary:
+
+<details>
+<summary>Encrypted EBS Volumes via KMS</summary>
+<br>
+To create and manage encrypted EBS volumes, the EBS CSI Driver requires access to the KMS key(s) used for encryption/decryption of the volume(s). The below example grants the EBS CSI Driver access to all KMS keys in the account, but it is best practice to restrict the resource to only the keys the EBS CSI Driver needs access to.
+<pre>
 {
   "Effect": "Allow",
   "Action": [
-      "kms:Decrypt",
-      "kms:GenerateDataKeyWithoutPlaintext",
-      "kms:CreateGrant"
+    "kms:Decrypt",
+    "kms:GenerateDataKeyWithoutPlaintext",
+    "kms:CreateGrant"
   ],
-  "Resource": "*"
+  "Resource": "arn:aws:kms:*:*:key/*"
 }
-```
+</pre>
+</details>
+
+<details>
+<summary>Modifying tags of existing volumes</summary>
+<br>
+Modification of tags of existing volumes can, in some configurations, allow the driver to bypass tag-based policies and restrictions, so it is not included in the default policy. Below is an example statement that will grant the EBS CSI Driver the ability to modify tags of any volume or snapshot:
+<pre>
+{ 
+  "Effect": "Allow",
+  "Action": [
+    "ec2:CreateTags"
+  ],
+  "Resource": [
+    "arn:aws:ec2:*:*:volume/*",
+    "arn:aws:ec2:*:*:snapshot/*"
+  ]
+}
+</pre>
+</details>
 
 There are several options to pass credentials to the EBS CSI Driver, each documented below: