Adding the Amazon EKS add-on Updating the Amazon EKS add-on Removing the Amazon EKS add-on

Managing the Amazon EBS CSI driver as an Amazon EKS add-on

To improve security and reduce the amount of work, you can manage the Amazon EBS CSI driver as an Amazon EKS add-on. For information about Amazon EKS add-ons, see Amazon EKS add-ons. You can add the Amazon EBS CSI add-on by following the steps in Adding the Amazon EBS CSI add-on.

If you added the Amazon EBS CSI add-on, you can manage it by following the steps in the Updating the Amazon EBS CSI driver as an Amazon EKS add-on and Removing the Amazon EBS CSI add-on sections.

Prerequisites

An existing cluster that's version 1.18 or later. To see the required platform version, run the following command.
```
aws eks describe-addon-versions --addon-name aws-ebs-csi-driver
```
An existing AWS Identity and Access Management (IAM) OpenID Connect (OIDC) provider for your cluster. To determine whether you already have one, or to create one, see Create an IAM OIDC provider for your cluster.
An Amazon EBS CSI driver IAM role. For more information, see Creating the Amazon EBS CSI driver IAM role for service accounts.

Important

To use the snapshot functionality of the Amazon EBS CSI driver, you must install the external snapshotter before the installation of the add-on. The external snapshotter components must be installed in the following order:

CustomResourceDefinition (CRD) for volumesnapshotclasses, volumesnapshots, and volumesnapshotcontents
RBAC (ClusterRole, ClusterRoleBinding, and so on)
controller deployment

For more information, see CSI Snapshotter on GitHub.

Adding the Amazon EBS CSI add-on

Important

Before adding the Amazon EBS CSI add-on, confirm that you don't self-manage any settings that Amazon EKS will start managing. To determine which settings Amazon EKS manages, see Amazon EKS add-on configuration.

You can use eksctl, the AWS Management Console, or the AWS CLI to add the Amazon EBS CSI add-on to your cluster .

eksctl

To add the Amazon EBS CSI add-on using eksctl

Replace my-cluster with the name of your cluster, 111122223333 with your account ID, and AmazonEKS_EBS_CSI_DriverRole with the name of the role created earlier. If your cluster is in the AWS GovCloud (US-East) or AWS GovCloud (US-East) AWS Regions, then replace arn:aws: with arn:aws-us-gov: before running the following command.


eksctl create addon --name aws-ebs-csi-driver --cluster my-cluster --service-account-role-arn arn:aws:iam::111122223333:role/AmazonEKS_EBS_CSI_DriverRole --force

If you remove the --force option and there's a conflict with your existing settings, the command fails. You can use the resulting error message to troubleshoot the conflict. Before specifying this option, make sure that the Amazon EKS add-on doesn't manage settings that you need to self-manage. This is because those settings are overwritten with this option. For more information about managing Amazon EKS add-ons, see Amazon EKS add-on configuration.

AWS Management Console

To add the Amazon EBS CSI add-on using the AWS Management Console

Open the Amazon EKS console at https://console.aws.amazon.com/eks/home#/clusters.
In the left navigation pane, choose Clusters.
Choose the name of the cluster that you want to configure the Amazon EBS CSI add-on for.
Choose the Add-ons tab.
Choose Add new.
1. Select Amazon EBS CSI Driver for Name.
2. Select the Version you'd like to use.
3. For Service account role, select the name of an IAM role that you attached the IAM policy to.
4. If you select Override existing configuration for this add-on on the cluster., one or more of the settings for the existing add-on can be overwritten with the Amazon EKS add-on settings. If you don't enable this option and there's a conflict with your existing settings, the operation fails. You can use the resulting error message to troubleshoot the conflict. Before selecting this option, make sure that the Amazon EKS add-on doesn't manage settings that you need to self-manage. For more information about managing Amazon EKS add-ons, see Amazon EKS add-on configuration.
5. Choose Add.

AWS CLI

To add the Amazon EBS CSI add-on using the AWS CLI

Replace my-cluster with the name of your cluster, 111122223333 with your account ID, and AmazonEKS_EBS_CSI_DriverRole with the name of the role that was created earlier. If your cluster is in the AWS GovCloud (US-East) or AWS GovCloud (US-East) AWS Regions, then replace arn:aws: with arn:aws-us-gov: before running the following command.


aws eks create-addon \
  --cluster-name my-cluster \
  --addon-name aws-ebs-csi-driver \
  --service-account-role-arn arn:aws:iam::111122223333:role/AmazonEKS_EBS_CSI_DriverRole

Updating the Amazon EBS CSI driver as an Amazon EKS add-on

Amazon EKS doesn't automatically update Amazon EBS CSI for your cluster when new versions are released or after you update your cluster to a new Kubernetes minor version. To update Amazon EBS CSI on an existing cluster, you must initiate the update and then Amazon EKS updates the add-on for you.

Important

Update your cluster and nodes to a new Kubernetes minor version before you update Amazon EBS CSI to the same minor version.

eksctl

To update the Amazon EBS CSI add-on using eksctl

Check the current version of your Amazon EBS CSI add-on. Replace my-cluster with your cluster name.


eksctl get addon --name aws-ebs-csi-driver --cluster my-cluster

The example output is as follows.


NAME                    VERSION                      STATUS  ISSUES  IAMROLE UPDATE AVAILABLE
aws-ebs-csi-driver      v1.4.0-eksbuild.preview      ACTIVE  0               v1.5.1-eksbuild.1

Update the add-on to the version returned under UPDATE AVAILABLE in the output of the previous step.
```
eksctl update addon \
  --name aws-ebs-csi-driver \
  --version v1.5.1-eksbuild.1 \
  --cluster my-cluster \
  --force
```
If you remove the --force option and there's a conflict with your existing settings, the command fails. You can use the resulting error message to troubleshoot the conflict. Before specifying this option, make sure that the Amazon EKS add-on doesn't manage settings that you need to self-manage. This is because those settings are overwritten with this option. For more information about managing Amazon EKS add-ons, see Amazon EKS add-on configuration.

AWS Management Console

To update the Amazon EBS CSI add-on using the AWS Management Console

Open the Amazon EKS console at https://console.aws.amazon.com/eks/home#/clusters.
In the left navigation pane, choose Clusters.
Choose the name of the cluster that you want to update the Amazon EBS CSI add-on for.
Choose the Add-ons tab.
Select the radio button in the upper right of the aws-ebs-csi-driver box.
Choose Edit.
1. Select the Version of the Amazon EKS add-on that you want to use.
2. For Service account role, select the name of the IAM role that you've attached the Amazon EBS CSI driver IAM policy to.
3. If you select Override existing configuration for this add-on on the cluster., then one or more of the settings for the existing add-on can be overwritten with the Amazon EKS add-on settings. If you don't enable this option and there's a conflict with your existing settings, the operation fails with an error message to help you resolve the conflict. Before selecting this option, make sure that the Amazon EKS add-on doesn't manage settings that you need to self-manage. For more information about managing Amazon EKS add-ons, see Amazon EKS add-on configuration.
4. Select Update.

AWS CLI

To update the Amazon EBS CSI add-on using the AWS CLI

Check the current version of your Amazon EBS CSI add-on. Replace my-cluster with your cluster name.


aws eks describe-addon \
  --cluster-name my-cluster \
  --addon-name aws-ebs-csi-driver \
  --query "addon.addonVersion" \
  --output text

The example output is as follows.


v1.4.0-eksbuild.preview

Determine which versions of the Amazon EBS CSI add-on are available for your cluster version.
```
aws eks describe-addon-versions \
  --addon-name aws-ebs-csi-driver \
  --kubernetes-version 1.20 \
  --query "addons[].addonVersions[].[addonVersion, compatibilities[].defaultVersion]" \
  --output text
```
The example output is as follows.
```
v1.5.1-eksbuild.1
False
v1.4.0-eksbuild.preview
True
```
The version with True underneath is the default version deployed with new clusters with the version that you specified.
Update the add-on to the version with True that was returned in the output of the previous step. If it was returned in the output, you can also update to a later version.
```
aws eks update-addon \
  --cluster-name my-cluster \
  --addon-name aws-ebs-csi-driver \
  --addon-version v1.4.0-eksbuild.preview \
  --resolve-conflicts OVERWRITE
```
If you remove the --resolve-conflicts OVERWRITE option and there's a conflict with your existing settings, then the command fails with an error message to help you resolve the conflict. Before specifying this option, make sure that the Amazon EKS add-on doesn't manage settings that you need to self-manage. This is because those settings are overwritten with this option. For more information about managing Amazon EKS add-ons, see Amazon EKS add-on configuration.

Removing the Amazon EBS CSI add-on

You have two options for removing an Amazon EKS add-on.

Preserve add-on software on your cluster – This option removes Amazon EKS management of any settings. It also removes the ability for Amazon EKS to notify you of updates and automatically update the Amazon EKS add-on after you initiate an update. However, it preserves the add-on software on your cluster. This option makes the add-on a self-managed add-on, rather than an Amazon EKS add-on. With this option, there's no downtime for the add-on. The commands in this procedure use this option.
Remove add-on software entirely from your cluster – We recommend that you remove the Amazon EKS add-on from your cluster only if there are no resources on your cluster that are dependent on it. To do this option, delete --preserve from the command you use in this procedure.

If the add-on has an IAM account associated with it, the IAM account isn't removed.

You can use eksctl, the AWS Management Console, or the AWS CLI to remove the Amazon EBS CSI add-on.

eksctl

To remove the Amazon EBS CSI add-on using eksctl

Replace my-cluster with the name of your cluster, and then run the following command.


eksctl delete addon --cluster my-cluster --name aws-ebs-csi-driver --preserve

AWS Management Console

To remove the Amazon EBS CSI add-on using the AWS Management Console

Open the Amazon EKS console at https://console.aws.amazon.com/eks/home#/clusters.
In the left navigation pane, choose Clusters.
Choose the name of the cluster that you want to remove the Amazon EBS CSI add-on for.
Choose the Add-ons tab.
Select the radio button in the upper right of the aws-ebs-csi-driver box.
Choose Remove.
Select Preserve on cluster if you want Amazon EKS to stop managing settings for the add-on. Do this if you want to retain the add-on software on your cluster. This is so that you can manage all of the settings of the add-on on your own.
Enter aws-ebs-csi-driver.
Select Remove.

AWS CLI

To remove the Amazon EBS CSI add-on using the AWS CLI

Replace my-cluster with the name of your cluster, and then run the following command.


aws eks delete-addon --cluster-name my-cluster --addon-name aws-ebs-csi-driver --preserve

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Create an IAM policy and role

Deploy a sample application