Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions,
see Getting Started with Amazon Web Services in China
(PDF).
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 driver 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. To see the required platform
version, run the following command.
aws eks describe-addon-versions --addon-name aws-ebs-csi-driver
-
An existing Amazon Identity and Access Management (IAM) OpenID Connect (OIDC) provider for your cluster. To determine whether you already have one, or to create one, see Creating an IAM OIDC provider
for your cluster.
-
An Amazon EBS CSI driver IAM role. If you don't satisfy this prerequisite, attempting
to install the add-on and running kubectl describe pvc
will show
failed to provision volume with StorageClass
along with a
could not create volume in EC2: UnauthorizedOperation
error. For
more information, see Creating the Amazon EBS CSI driver IAM role.
-
If you're using a cluster wide restricted PodSecurityPolicy, make sure that the add-on is granted
sufficient permissions to be deployed. For the permissions required by each add-on
Pod, see the relevant add-on manifest definition on GitHub.
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:
For more information, see CSI
Snapshotter on GitHub.
Adding the Amazon EBS CSI driver add-on
You can use eksctl
, the Amazon Web Services Management Console, or the Amazon CLI to add the Amazon EBS CSI add-on to your
cluster.
- eksctl
-
To add the Amazon EBS CSI add-on using eksctl
Run the following command. Replace
my-cluster
with the name
of your cluster,
111122223333
with your account ID, and
AmazonEKS_EBS_CSI_DriverRole
with the name of the IAM role created
earlier.
eksctl create addon --name aws-ebs-csi-driver --cluster my-cluster
--service-account-role-arn arn:aws-cn:iam::111122223333
:role/AmazonEKS_EBS_CSI_DriverRole
--force
If you remove the --force
option and any of the Amazon EKS add-on settings conflict with your existing settings, then updating the Amazon EKS add-on fails, and you receive 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 manage, because those settings are overwritten with this option.
For more information about other options for this setting,
see Addons in
the eksctl
documentation. For more information about Amazon EKS Kubernetes field management, see Kubernetes field management.
- Amazon Web Services Management Console
-
To add the Amazon EBS CSI add-on using the Amazon Web Services Management Console
Open the Amazon EKS console at https://console.amazonaws.cn/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 Get more add-ons.
-
On the Select add-ons page, do the
following:
-
In the Amazon EKS-addons section, select
the Amazon EBS CSI Driver check box.
-
Choose Next.
-
On the Configure selected add-ons settings
page, do the following:
-
Select the Version you'd like to
use.
-
For Select IAM role, select the
name of an IAM role that you attached the Amazon EBS CSI driver
IAM policy to.
-
(Optional) You can expand the Optional
configuration settings. If you select
Override for the Conflict
resolution method, 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.
-
Choose Next.
-
On the Review and add page, choose
Create. After the add-on installation is
complete, you see your installed add-on.
- Amazon CLI
-
To add the Amazon EBS CSI add-on using the Amazon CLI
Run the following command. 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.
aws eks create-addon --cluster-name my-cluster
--addon-name aws-ebs-csi-driver
\
--service-account-role-arn arn:aws-cn:iam::111122223333
:role/AmazonEKS_EBS_CSI_DriverRole
Now that you have added the Amazon EBS CSI driver as an Amazon EKS add-on, you can continue to
Deploy a sample application and verify that the CSI
driver is working. That procedure
includes setting up the storage class.
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.
- 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
An example output is as follows.
NAME VERSION STATUS ISSUES IAMROLE UPDATE AVAILABLE
aws-ebs-csi-driver v1.11.2-eksbuild.1
ACTIVE 0 v1.11.4-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.11.4-eksbuild.1
--cluster my-cluster
--force
If you remove the --force
option and any of the Amazon EKS add-on settings conflict with your existing settings, then updating the Amazon EKS add-on fails, and you receive 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 manage, because those settings are overwritten with this option.
For more information about other options for this setting,
see Addons in
the eksctl
documentation. For more information about Amazon EKS Kubernetes field management, see Kubernetes field management.
- Amazon Web Services Management Console
-
To update the Amazon EBS CSI add-on using the Amazon Web Services Management Console
Open the Amazon EKS console at https://console.amazonaws.cn/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.
-
Choose Amazon EBS CSI Driver.
-
Choose Edit.
-
On the Configure Amazon EBS CSI Driver page, do
the following:
-
Select the Version you'd like to
use.
-
For Select IAM role, select the
name of an IAM role that you attached the Amazon EBS CSI driver
IAM policy to.
-
(Optional) You can expand the Optional
configuration settings and modify as
needed.
-
Choose Save changes.
- Amazon CLI
-
To update the Amazon EBS CSI add-on using the Amazon 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
An example output is as follows.
v1.11.2-eksbuild.1
-
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.23
\
--query "addons[].addonVersions[].[addonVersion, compatibilities[].defaultVersion]" --output text
An example output is as follows.
v1.11.4-eksbuild.1
True
v1.11.2-eksbuild.1
False
The version with True
underneath is the default version deployed when the add-on is created. The version deployed when the add-on is created might not be the latest available version.
In the previous output, the latest version is deployed when the add-on is created.
-
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.11.4-eksbuild.1
\
--resolve-conflicts PRESERVE
The PRESERVE
option preserves any custom settings that you've set for the add-on. For more information about other options for this setting, see update-addon in the Amazon EKS Command Line Reference. For more information about Amazon EKS add-on configuration management, see Kubernetes field management.
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
installation, 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 Amazon Web Services Management Console, or the Amazon 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
- Amazon Web Services Management Console
-
To remove the Amazon EBS CSI add-on using the Amazon Web Services Management Console
Open the Amazon EKS console at https://console.amazonaws.cn/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.
-
Choose Amazon EBS CSI Driver.
-
Choose Remove.
-
In the Remove: aws-ebs-csi-driver
confirmation dialog box, do the following:
-
If you want Amazon EKS to stop managing settings for the
add-on, select Preserve on cluster. 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.
- Amazon CLI
-
To remove the Amazon EBS CSI add-on using the Amazon 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