Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update example policy and documentation #2287

Merged
merged 1 commit into from
Jan 13, 2025
+189 −56
Merged

Update example policy and documentation #2287

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 71 additions & 24 deletions docs/example-iam-policy.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand All @@ -55,7 +85,7 @@
"Action": [
"ec2:CreateVolume"
],
"Resource": "arn:*:ec2:*:*:volume/*",
"Resource": "arn:aws:ec2:*:*:volume/*",
"Condition": {
"StringLike": {
"aws:RequestTag/CSIVolumeName": "*"
Expand All @@ -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": "*"
}
}
},
Expand All @@ -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"
}
}
},
Expand All @@ -110,7 +157,7 @@
"Action": [
"ec2:DeleteSnapshot"
],
"Resource": "*",
"Resource": "arn:aws:ec2:*:*:snapshot/*",
"Condition": {
"StringLike": {
"ec2:ResourceTag/CSIVolumeSnapshotName": "*"
Expand All @@ -122,7 +169,7 @@
"Action": [
"ec2:DeleteSnapshot"
],
"Resource": "*",
"Resource": "arn:aws:ec2:*:*:snapshot/*",
"Condition": {
"StringLike": {
"ec2:ResourceTag/ebs.csi.aws.com/cluster": "true"
Expand Down
44 changes: 36 additions & 8 deletions docs/install.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
Loading
Loading