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

Managing the Amazon VPC CNI add-on

Amazon EKS supports native VPC networking with the Amazon VPC Container Network Interface (CNI) plugin for Kubernetes. Using this plugin allows Kubernetes pods to have the same IP address inside the pod as they do on the VPC network. For more information, see Pod networking (CNI).

If you have a 1.18 or later cluster that you've not added the Amazon VPC CNI Amazon EKS add-on to, you can add it using the procedure in Adding the Amazon VPC CNI Amazon EKS add-on. If you have a cluster that you've already added the Amazon VPC CNI Amazon EKS add-on to, you can manage it using the procedures in the Updating the Amazon VPC CNI Amazon EKS add-on and Removing the Amazon VPC CNI Amazon EKS add-on sections. For more information about Amazon EKS add-ons, see Amazon EKS add-ons.

If you have not added the Amazon VPC CNI Amazon EKS add-on, the Amazon VPC CNI self-managed add-on is running on your cluster, by default. You can update the add-on using the procedure in Updating the Amazon VPC CNI self-managed add-on.

Version 1.7.5-eksbuild.1 is deployed for the self-managed add-on for all Kubernetes versions. Version 1.7.5-eksbuild.2 is deployed for the Amazon EKS add-on for Kubernetes version 1.18 and later.

Prerequisites

An existing cluster. If you want to use the Amazon VPC CNI Amazon EKS add-on, your cluster needs to be version 1.18 or later. If you're using the self-managed add-on, your cluster can be any Amazon EKS supported version.
An IAM OpenID Connect (OIDC) provider for your cluster. To determine whether you already have one, or how to create one, see Create an IAM OIDC provider for your cluster.
An IAM role with the AmazonEKS_CNI_Policy IAM policy attached to it. For more information, see Configuring the Amazon VPC CNI plugin to use IAM roles for service accounts.

Adding the Amazon VPC CNI Amazon EKS add-on

Select the tab with the name of the tool that you want to use to add the Amazon VPC CNI Amazon EKS add-on to your 1.18 or later cluster with.

Important

Before adding the Amazon VPC CNI Amazon EKS add-on, confirm that you do not self-manage any settings that Amazon EKS will start managing. To determine which settings Amazon EKS manages, see Amazon EKS add-on configuration.

eksctl

To add the latest minor, patch, and build version of the Amazon EKS add-on using eksctl

Replace <my-cluster> (including <>) with the name of your cluster and arn:aws:iam::<111122223333>:role/<eksctl-my-cluster-addon-iamserviceaccount-kube-sys-Role1-UK9MQSLXK0MW> with your existing IAM role (see Prerequisites).


eksctl create addon \
    --name vpc-cni \
    --version latest \
    --cluster <my-cluster> \
    --service-account-role-arn arn:aws:iam::<111122223333>:role/<eksctl-my-cluster-addon-iamserviceaccount-kube-sys-Role1-UK9MQSLXK0MW> \
    --force

If any of the Amazon EKS add-on settings conflict with the existing settings for the self-managed add-on, then adding the Amazon EKS add-on fails, and you receive an error message to help you resolve the conflict.

AWS Management Console

To add the latest minor, patch, and build version of the Amazon EKS 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, select Clusters, and then select the name of the cluster that you want to configure the Amazon VPC CNI Amazon EKS add-on for.
Choose the Configuration tab and then choose the Add-ons tab.
Select Add new.
- Select vpc-cni for Name.
- Select the Version you'd like to use. We recommend the version marked Latest.
- For Service account role, select the name of an IAM role that you've attached the AmazonEKS_CNI_Policy IAM policy to (see Prerequisites).
- Select Override existing configuration for this add-on on the cluster. If any of the Amazon EKS add-on settings conflict with the existing settings for the self-managed add-on, then adding the Amazon EKS add-on fails, and you receive an error message to help you resolve the conflict.
- Select Add.

AWS CLI

To add the latest minor, patch, and build version of the Amazon EKS add-on using the AWS CLI

Determine which versions of the Amazon VPC CNI Amazon EKS add-on are available for your cluster's version. In the following command, replace <my-cluster> (including <>) with the name of your cluster.
```
aws eks describe-addon-versions \
    --addon-name vpc-cni \
    --kubernetes-version <1.21> \
    --query "addons[].addonVersions[].[addonVersion, compatibilities[].defaultVersion]" \
    --output text
```
Output
```
v1.9.0-eksbuild.1
False
...
v1.7.5-eksbuild.2
True
...
```
The version with True underneath is the default version deployed with new clusters. In the previous output, v1.9.0-eksbuild.1 is the latest available version.
In the following command, replace <my-cluster> (including <>) with the name of your cluster, <v1.9.0-eksbuild.1> with the latest available version, arn:aws:iam::<AWS_ACCOUNT_ID>:role/<AmazonEKSCNIRole> with the ARN of an IAM role that you've attached the AmazonEKS_CNI_Policy IAM policy to (see Prerequisites), and then run the command.
```
aws eks create-addon \
    --cluster-name <my-cluster> \
    --addon-name vpc-cni \
    --addon-version <v1.9.0-eksbuild.1> \
    --service-account-role-arn arn:aws:iam::<AWS_ACCOUNT_ID>:role/<AmazonEKSCNIRole> \
    --resolve-conflicts OVERWRITE
```
If any of the Amazon EKS add-on settings conflict with the existing settings for the self-managed add-on, then adding the Amazon EKS add-on fails, and you receive an error message to help you resolve the conflict.

Updating the Amazon VPC CNI Amazon EKS add-on

Important

Before updating the Amazon VPC CNI Amazon EKS add-on, confirm that you do not self-manage any settings that Amazon EKS manages. To determine which settings Amazon EKS manages, see Amazon EKS add-on configuration.

This procedure is for updating the Amazon VPC CNI Amazon EKS add-on. If you haven't added the Amazon VPC CNI Amazon EKS add-on, complete the procedure in Updating the Amazon VPC CNI self-managed add-on instead. Amazon EKS does not automatically update the Amazon VPC CNI add-on when new versions are released or after you update your cluster to a new Kubernetes minor version. To update the Amazon VPC CNI add-on for an existing cluster, you must initiate the update and then Amazon EKS updates the add-on for you.

We recommend that you update to the latest build and patch version for the latest minor version, but that you only update one minor version at a time. For example, if your current minor version is 1.7 and you want to update to 1.9, you should update to the latest patch and build version of 1.8 first, then update to the latest patch and build version of 1.9.

Select the tab with the name of the tool that you want to use to update the Amazon VPC CNI Amazon EKS add-on on your 1.18 or later cluster with.

eksctl

To update the Amazon EKS add-on to the latest minor, patch, and build version using eksctl

Check the current version of your vpc-cni Amazon EKS add-on. Replace <my-cluster> (including <>) with your cluster name.


eksctl get addon --name vpc-cni --cluster <my-cluster>

Output


NAME    VERSION                 STATUS  ISSUES  IAMROLE                                                                                                   UPDATE AVAILABLE
vpc-cni v1.8.0-eksbuild.1      ACTIVE  0       arn:aws:iam::<111122223333>:role/<eksctl-my-cluster-addon-iamserviceaccount-kube-sys-Role1-UK9MQSLXK0MW>  v1.9.0-eksbuild.1

Update the add-on to the latest minor, patch, and build version.
```
eksctl update addon \
    --name vpc-cni \
    --version latest \
    --cluster <my-cluster> \
    --force
```

AWS Management Console

To update the Amazon EKS add-on to the latest minor, patch, and build version using the AWS Management Console

Open the Amazon EKS console at https://console.aws.amazon.com/eks/home#/clusters.
In the left navigation, select Clusters, and then select the name of the cluster that you want to update the Amazon VPC CNI add-on for.
Choose the Configuration tab and then choose the Add-ons tab.
Select the box in the top right of the vpc-cni box and then choose Edit.
- Select the Version of the Amazon EKS add-on that you want to use. We recommend the version marked Latest.
- For Service account role, select the name of an IAM role that you've attached the AmazonEKS_CNI_Policy IAM policy to (see Prerequisites), if one isn't already selected.
- Select Override existing configuration for this add-on on the cluster.
- Select Update.

AWS CLI

To update the Amazon EKS add-on to the latest minor, patch, and build version using the AWS CLI

Check the current version of your Amazon VPC CNI Amazon EKS add-on. Replace <my-cluster> with your cluster name.
```
aws eks describe-addon \
    --cluster-name <my-cluster> \
    --addon-name vpc-cni \
    --query "addon.addonVersion" \
    --output text
```
Output:
```
v1.8.0-eksbuild.1
```
Determine which versions of the Amazon VPC CNI Amazon EKS add-on are available for your cluster's version. Replace <1.21> with your cluster's version.
```
aws eks describe-addon-versions \
    --addon-name vpc-cni \
    --kubernetes-version <1.21> \
    --query "addons[].addonVersions[].[addonVersion, compatibilities[].defaultVersion]" \
    --output text
```
Output
```
v1.9.0-eksbuild.1
False
...
v1.7.5-eksbuild.2
True
...
```
The version with True underneath is the default version deployed with new clusters. In the previous output, v1.9.0-eksbuild.1 is the latest available version.
Update the add-on to the latest build version of the latest patch version of the latest minor version returned in the previous output. Replace <my-cluster> (including <>) with your cluster name and <v1.9.0-eksbuild.1> with the version of the add-on that you want to update to.
```
aws eks update-addon \
    --cluster-name <my-cluster> \
    --addon-name vpc-cni \
    --addon-version <v1.9.0-eksbuild.1> \
    --resolve-conflicts OVERWRITE
```

Removing the Amazon VPC CNI Amazon EKS add-on

You have two options when removing an Amazon EKS add-on:

Preserve the add-on's software on your cluster – This option removes Amazon EKS management of any settings and the ability for Amazon EKS to notify you of updates and automatically update the Amazon EKS add-on after you initiate an update, but preserves the add-on's software on your cluster. This option makes the add-on a self-managed add-on, rather than an Amazon EKS add-on. There is no downtime for the add-on.
Removing the add-on software entirely from your cluster – You should only remove the Amazon EKS add-on from your cluster if there are no resources on your cluster are dependent on the functionality that the add-on provides. After removing the Amazon EKS add-on, you can add it again if you want to.

If the add-on has an IAM account associated with it, the IAM account is not removed.

Select the tab with the name of the tool that you want to use to remove the Amazon VPC CNI Amazon EKS add-on from your 1.18 or later cluster with.

eksctl

To remove the Amazon EKS add-on using eksctl

Replace my-cluster (including <>) with the name of your cluster and then run the following command. Removing --preserve removes the add-on software from your cluster.


eksctl delete addon --cluster <my-cluster> --name vpc-cni --preserve

AWS Management Console

To remove the Amazon EKS 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, select Clusters, and then select the name of the cluster that you want to remove the Amazon VPC CNI Amazon EKS add-on for.
Choose the Configuration tab and then choose the Add-ons tab.
Select the checkbox in the top right of the vpc-cni box and then choose Remove. Select Preserve on cluster if you want Amazon EKS to stop managing settings for the add-on, but want to retain the add-on software on your cluster so that you can self-managed all of the add-on's settings. Type vpc-cni and then select Remove.

AWS CLI

To remove the Amazon EKS add-on using the AWS CLI

Replace my-cluster with the name of your cluster and then run the following command. Removing --preserve removes the add-on software from your cluster.


aws eks delete-addon --cluster-name my-cluster --addon-name vpc-cni --preserve

Updating the Amazon VPC CNI self-managed add-on

If you have a 1.17 or earlier cluster, or a 1.18 or later cluster that you have not added the Amazon VPC CNI Amazon EKS add-on to, complete the following steps to update the add-on. If you've added the Amazon VPC CNI Amazon EKS add-on, complete the procedure in Updating the Amazon VPC CNI Amazon EKS add-on instead.

To update the self-managed add-on to the latest minor and patch version using kubectl

Determine the latest available minor version by viewing the Changelog on GitHub.
Use the following command to determine your cluster's Amazon VPC CNI add-on version:
```
kubectl describe daemonset aws-node --namespace kube-system | grep Image | cut -d "/" -f 2
```
Output:
```
amazon-k8s-cni:v1.8.0
```
In this example output, the Amazon VPC CNI add-on version is 1.8.0, which is earlier than the latest version listed in the Changelog on GitHub.
Use the appropriate command below to update your Amazon VPC CNI add-on to the latest minor and patch version available. Replace 1.9 with the latest minor version from the Changelog on GitHub. The manifest installs the latest patch version (for example, .0) for the minor version that you specify.

Important

Any changes you've made to the add-on's default settings on your cluster can be overwritten with default settings when applying the new version of the manifest. To prevent loss of your custom settings, download the manifest, change the default settings as necessary, and then apply the modified manifest to your cluster. You should only update one minor version at a time. For example, if your current minor version is 1.7 and you want to update to 1.9, you should update to 1.8 first, then update to 1.9.
- China (Beijing) (cn-north-1) or China (Ningxia) (cn-northwest-1)
```
kubectl apply -f https://raw.githubusercontent.com/aws/amazon-vpc-cni-k8s/release-1.9/config/v1.9/aws-k8s-cni-cn.yaml
```
- AWS GovCloud (US-East) (us-gov-east-1)
```
kubectl apply -f https://raw.githubusercontent.com/aws/amazon-vpc-cni-k8s/release-1.9/config/v1.9/aws-k8s-cni-us-gov-east-1.yaml
```
- AWS GovCloud (US-West) (us-gov-west-1)
```
kubectl apply -f https://raw.githubusercontent.com/aws/amazon-vpc-cni-k8s/release-1.9/config/v1.9/aws-k8s-cni-us-gov-west-1.yaml
```
- For all other Regions
  - Download the manifest file.
    
    curl -o aws-k8s-cni.yaml https://raw.githubusercontent.com/aws/amazon-vpc-cni-k8s/release-1.9/config/v1.9/aws-k8s-cni.yaml
  - If necessary, replace <region-code> in the following command with the Region that your cluster is in and then run the modified command to replace the Region code in the file (currently us-west-2).
    
    sed -i.bak -e 's/us-west-2/<region-code>/' aws-k8s-cni.yaml
  - If necessary, replace <account> in the following command with the account from Amazon EKS add-on container image addresses for the Region that your cluster is in and then run the modified command to replace the account in the file (currently 602401143452).
    
    sed -i.bak -e 's/602401143452/<account>/' aws-k8s-cni.yaml
  - Apply the manifest file to your cluster.
    
    kubectl apply -f aws-k8s-cni.yaml

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

CNI metrics helper

Alternate compatible CNI plugins