Creating an Amazon EKS add-on - Amazon EKS
PrerequisitesProcedure
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).

Help improve this page

Want to contribute to this user guide? Scroll to the bottom of this page and select Edit this page on GitHub. Your contributions will help make our user guide better for everyone.

Creating an Amazon EKS add-on

Amazon EKS add-ons are add-on software for Amazon EKS clusters. All Amazon EKS add-ons:

  • Include the latest security patches and bug fixes.

  • Are validated by Amazon to work with Amazon EKS.

  • Reduce the amount of work required to manage the add-on software.

You can create an Amazon EKS add-on using eksctl, the Amazon Web Services Management Console, or the Amazon CLI. If the add-on requires an IAM role, see the details for the specific add-on in Amazon EKS add-ons for details about creating the role.

Prerequisites

Complete the following before you create an add-on:

Procedure

You can create an Amazon EKS add-on using eksctl, the Amazon Web Services Management Console, or the Amazon CLI. If the add-on requires an IAM role, see the details for the specific add-on in Available Amazon EKS add-ons from Amazon for details about creating the role.

eksctl
To create an Amazon EKS add-on using eksctl

  1. View the names of add-ons available for a cluster version. Replace 1.30 with the version of your cluster.

    eksctl utils describe-addon-versions --kubernetes-version 1.30 | grep AddonName

    An example output is as follows. 

    "AddonName": "aws-ebs-csi-driver",
                        "AddonName": "coredns",
                        "AddonName": "kube-proxy",
                        "AddonName": "vpc-cni",
                        "AddonName": "adot",
                        "AddonName": "dynatrace_dynatrace-operator",
                        "AddonName": "upbound_universal-crossplane",
                        "AddonName": "teleport_teleport",
                        "AddonName": "factorhouse_kpow",
                        [...]

  2. View the versions available for the add-on that you would like to create. Replace 1.30 with the version of your cluster. Replace name-of-addon with the name of the add-on you want to view the versions for. The name must be one of the names returned in the previous step.

    eksctl utils describe-addon-versions --kubernetes-version 1.30 --name name-of-addon | grep AddonVersion

    The following output is an example of what is returned for the add-on named vpc-cni. You can see that the add-on has several available versions.

    "AddonVersions": [
    "AddonVersion": "v1.12.0-eksbuild.1",
    "AddonVersion": "v1.11.4-eksbuild.1",
    "AddonVersion": "v1.10.4-eksbuild.1",
    "AddonVersion": "v1.9.3-eksbuild.1",

  3. Create an Amazon EKS add-on. Copy the command and replace the user-data as follows:

    • Replace my-cluster with the name of your cluster.

    • Replace name-of-addon with the name of the add-on that you want to create.

    • If you want a version of the add-on that's earlier than the latest version, then replace latest with the version number returned in the output of a previous step that you want to use.

    • If the add-on uses a service account role, replace 111122223333 with your account ID and replace role-name with the name of the role. For instructions on creating a role for your service account, see the documentation for the add-on that you're creating. Specifying a service account role requires that you have an IAM OpenID Connect (OIDC) provider for your cluster. To determine whether you have one for your cluster, or to create one, see Create an IAM OIDC provider for your cluster.

      If the add-on doesn't use a service account role, delete --service-account-role-arn arn:aws-cn:iam::111122223333:role/role-name.

    • This example command overwrites the configuration of any existing self-managed version of the add-on, if there is one. If you don't want to overwrite the configuration of an existing self-managed add-on, remove the --force option. If you remove the option, and the Amazon EKS add-on needs to overwrite the configuration of an existing self-managed add-on, then creation of the Amazon EKS add-on 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 manage, because those settings are overwritten with this option.

      eksctl create addon --cluster my-cluster --name name-of-addon --version latest \
    --service-account-role-arn arn:aws-cn:iam::111122223333:role/role-name --force

You can see a list of all available options for the command.

eksctl create addon --help

For more information about available options see Addons in the eksctl documentation.

Amazon Web Services Management Console
To create an Amazon EKS add-on using the Amazon Web Services Management Console

  1. Open the Amazon EKS console at https://console.amazonaws.cn/eks/home#/clusters.

  2. In the left navigation pane, select Clusters, and then select the name of the cluster that you want to create the add-on for.

  3. Choose the Add-ons tab.

  4. Choose Get more add-ons.

  5. On the Configure selected add-ons settings page:

    • Choose View subscription options to open the Subscription options form. Review the Pricing details and Legal sections, then choose the Subscribe button to continue.

    • For Version, select the version that you want to install. We recommend the version marked latest, unless the individual add-on that you're creating recommends a different version. To determine whether an add-on has a recommended version, see the documentation for the add-on that you're creating.

  6. On the Review and add page, choose Create. After the add-on installation is complete, you see your installed add-ons.

Amazon CLI
Prerequisite

Version 2.12.3 or later or version 1.27.160 or later of the Amazon Command Line Interface (Amazon CLI) installed and configured on your device or Amazon CloudShell. To check your current version, use aws --version | cut -d / -f2 | cut -d ' ' -f1. Package managers such yum, apt-get, or Homebrew for macOS are often several versions behind the latest version of the Amazon CLI. To install the latest version, see Installing, updating, and uninstalling the Amazon CLI and Quick configuration with aws configure in the Amazon Command Line Interface User Guide. The Amazon CLI version that is installed in Amazon CloudShell might also be several versions behind the latest version. To update it, see Installing Amazon CLI to your home directory in the Amazon CloudShell User Guide.

To create an Amazon EKS add-on using the Amazon CLI

  1. Determine which add-ons are available. You can see all available add-ons, their type, and their publisher. Replace 1.30 with the version of your cluster.

    aws eks describe-addon-versions --kubernetes-version 1.30 \
    --query 'addons[].{Name: addonName, Type: type}' --output table

    An example output is as follows.

    -------------------------------------------------------
|                DescribeAddonVersions                |
+-------------------------------+---------------------+
|             Name              |        Type         |
+-------------------------------+---------------------+
|  aws-ebs-csi-driver           |  storage            |
|  coredns                      |  networking         |
|  kube-proxy                   |  networking         |
|  vpc-cni                      |  networking         |
|  adot                         |  observability      |
|  [...]                        |  [...]              |
+-------------------------------+---------------------+

    Your output might be different. In this example output, there are three different add-ons available of type networking and five add-ons with a publisher of type eks.

  2. You can see which versions are available for each add-on. Replace 1.30 with the version of your cluster and replace vpc-cni with the name of an add-on returned in the previous step.

    aws eks describe-addon-versions --kubernetes-version 1.30 --addon-name vpc-cni \
    --query 'addons[].addonVersions[].{Version: addonVersion, Defaultversion: compatibilities[0].defaultVersion}' --output table

    An example output is as follows.

    ------------------------------------------
|          DescribeAddonVersions         |
+-----------------+----------------------+
| Defaultversion  |       Version        |
+-----------------+----------------------+
|  False          |  v1.12.0-eksbuild.1  |
|  True           |  v1.11.4-eksbuild.1  |
|  False          |  v1.10.4-eksbuild.1  |
|  False          |  v1.9.3-eksbuild.1   |
+-----------------+----------------------+

    The version with True in the Defaultversion column is the version that the add-on is created with, by default.

  3. (Optional) Find the configuration options for your chosen add-on by running the following command: 

    aws eks describe-addon-configuration --addon-name vpc-cni --addon-version v1.12.0-eksbuild.1

    {
    "addonName": "vpc-cni",
    "addonVersion": "v1.12.0-eksbuild.1",
    "configurationSchema": "{\"$ref\":\"#/definitions/VpcCni\",\"$schema\":\"http://json-schema.org/draft-06/schema#\",\"definitions\":{\"Cri\":{\"additionalProperties\":false,\"properties\":{\"hostPath\":{\"$ref\":\"#/definitions/HostPath\"}},\"title\":\"Cri\",\"type\":\"object\"},\"Env\":{\"additionalProperties\":false,\"properties\":{\"ADDITIONAL_ENI_TAGS\":{\"type\":\"string\"},\"AWS_VPC_CNI_NODE_PORT_SUPPORT\":{\"format\":\"boolean\",\"type\":\"string\"},\"AWS_VPC_ENI_MTU\":{\"format\":\"integer\",\"type\":\"string\"},\"AWS_VPC_K8S_CNI_CONFIGURE_RPFILTER\":{\"format\":\"boolean\",\"type\":\"string\"},\"AWS_VPC_K8S_CNI_CUSTOM_NETWORK_CFG\":{\"format\":\"boolean\",\"type\":\"string\"},\"AWS_VPC_K8S_CNI_EXTERNALSNAT\":{\"format\":\"boolean\",\"type\":\"string\"},\"AWS_VPC_K8S_CNI_LOGLEVEL\":{\"type\":\"string\"},\"AWS_VPC_K8S_CNI_LOG_FILE\":{\"type\":\"string\"},\"AWS_VPC_K8S_CNI_RANDOMIZESNAT\":{\"type\":\"string\"},\"AWS_VPC_K8S_CNI_VETHPREFIX\":{\"type\":\"string\"},\"AWS_VPC_K8S_PLUGIN_LOG_FILE\":{\"type\":\"string\"},\"AWS_VPC_K8S_PLUGIN_LOG_LEVEL\":{\"type\":\"string\"},\"DISABLE_INTROSPECTION\":{\"format\":\"boolean\",\"type\":\"string\"},\"DISABLE_METRICS\":{\"format\":\"boolean\",\"type\":\"string\"},\"DISABLE_NETWORK_RESOURCE_PROVISIONING\":{\"format\":\"boolean\",\"type\":\"string\"},\"ENABLE_POD_ENI\":{\"format\":\"boolean\",\"type\":\"string\"},\"ENABLE_PREFIX_DELEGATION\":{\"format\":\"boolean\",\"type\":\"string\"},\"WARM_ENI_TARGET\":{\"format\":\"integer\",\"type\":\"string\"},\"WARM_PREFIX_TARGET\":{\"format\":\"integer\",\"type\":\"string\"}},\"title\":\"Env\",\"type\":\"object\"},\"HostPath\":{\"additionalProperties\":false,\"properties\":{\"path\":{\"type\":\"string\"}},\"title\":\"HostPath\",\"type\":\"object\"},\"Limits\":{\"additionalProperties\":false,\"properties\":{\"cpu\":{\"type\":\"string\"},\"memory\":{\"type\":\"string\"}},\"title\":\"Limits\",\"type\":\"object\"},\"Resources\":{\"additionalProperties\":false,\"properties\":{\"limits\":{\"$ref\":\"#/definitions/Limits\"},\"requests\":{\"$ref\":\"#/definitions/Limits\"}},\"title\":\"Resources\",\"type\":\"object\"},\"VpcCni\":{\"additionalProperties\":false,\"properties\":{\"cri\":{\"$ref\":\"#/definitions/Cri\"},\"env\":{\"$ref\":\"#/definitions/Env\"},\"resources\":{\"$ref\":\"#/definitions/Resources\"}},\"title\":\"VpcCni\",\"type\":\"object\"}}}"
}

    The output is a standard JSON schema.

    Here is an example of valid configuration values, in JSON format, that works with the schema above.

    {
  "resources": {
    "limits": {
      "cpu": "100m"
    }
  }
}

    Here is an example of valid configuration values, in YAML format, that works with the schema above.

      resources: 
    limits: 
      cpu: 100m

  4. Determine if the add-on requires IAM permissions. If so, you need to (1) determine if you want to use EKS Pod Identities or IAM Roles for Service Accounts (IRSA), (2) determine the ARN of the IAM role to use with the add-on, and (3) determine the name of the Kubernetes service account used by the add-on. You can find this information in the documentation or using the Amazon API, see Retrieve IAM info about an Add-on.

  5. Create an Amazon EKS add-on. Copy the command that follows to your device. Make the following modifications to the command as needed and then run the modified command:

    • Replace my-cluster with the name of your cluster.

    • Replace vpc-cni with an add-on name returned in the output of the previous step that you want to create.

    • Replace version-number with the version returned in the output of the previous step that you want to use.

    • If the add-on doesn't require IAM permissions, delete <service-account-configuration>.

    • If the add-on (1) requires IAM permissions, and (2) your cluster uses EKS Pod Identities, replace <service-account-configuration> with the following pod identity assocation. Replace <service-account-name> with the service account name used by the add-on. Replace <role-arn> with the ARN of an IAM role. The role must have the trust policy required by EKS Pod Identities. 

      • --pod-identity-associations 'serviceAccount=<service-account-name>,roleArn=<role-arn>'

    • If the add-on (1) requires IAM permissions, and (2) your cluster uses IRSA, replace <service-account-configuration> with the following IRSA configuration. Replace 111122223333 with your account ID and role-name with the name of an existing IAM role that you've created. For instructions on creating the role, see the documentation for the add-on that you're creating. Specifying a service account role requires that you have an IAM OpenID Connect (OIDC) provider for your cluster. To determine whether you have one for your cluster, or to create one, see Create an IAM OIDC provider for your cluster. 

      • --service-account-role-arn arn:aws:iam::111122223333:role/role-name

    • These example commands overwrites the --configuration-values option of any existing self-managed version of the add-on, if there is one. Replace this with the desired configuration values, such as a string or a file input. If you don't want to provide configuration values, then delete the --configuration-values option. If you don't want the Amazon CLI to overwrite the configuration of an existing self-managed add-on, remove the --resolve-conflicts OVERWRITE option. If you remove the option, and the Amazon EKS add-on needs to overwrite the configuration of an existing self-managed add-on, then creation of the Amazon EKS add-on 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 manage, because those settings are overwritten with this option.

    aws eks create-addon --cluster-name my-cluster --addon-name vpc-cni --addon-version version-number \
     <service-account-configuration> --configuration-values '{"resources":{"limits":{"cpu":"100m"}}}' --resolve-conflicts OVERWRITE

    aws eks create-addon --cluster-name my-cluster --addon-name vpc-cni --addon-version version-number \
    <service-account-configuration> --configuration-values 'file://example.yaml' --resolve-conflicts OVERWRITE

    For a full list of available options, see create-addon in the Amazon EKS Command Line Reference.