Add-ons Management via SDK

Every EKS cluster runs core software just to function: a CNI plugin for pod networking, CoreDNS for service discovery, kube-proxy for routing. Historically you installed and upgraded these by applying YAML by hand and tracking versions yourself. EKS-managed add-ons hand that job to AWS, and you drive it from the EKS SDK.

This page covers discovering versions, installing, updating, and wiring an add-on to an IRSA role - the everyday add-on lifecycle in both SDKs.

Recipe

Before installing, ask which versions are compatible with your cluster's Kubernetes version. DescribeAddonVersions answers that, so you never guess a version string.

# --- Python (boto3) ---
import boto3
 
eks = boto3.client("eks", region_name="us-east-1")
resp = eks.describe_addon_versions(
    addonName="vpc-cni",
    kubernetesVersion="1.30",
)
for addon in resp["addons"]:
    for v in addon["addonVersions"]:
        print(v["addonVersion"])   # e.g. v1.18.1-eksbuild.3

// --- TypeScript (AWS SDK v3) ---
import { EKSClient, DescribeAddonVersionsCommand } from "@aws-sdk/client-eks";
 
const eks = new EKSClient({ region: "us-east-1" });
const resp = await eks.send(new DescribeAddonVersionsCommand({
  addonName: "vpc-cni",
  kubernetesVersion: "1.30",
}));
for (const addon of resp.addons ?? []) {
  for (const v of addon.addonVersions ?? []) {
    console.log(v.addonVersion);   // e.g. v1.18.1-eksbuild.3
  }
}

The add-on names are stable strings: vpc-cni, coredns, kube-proxy, and aws-ebs-csi-driver, among others. Each version entry also reports the Kubernetes versions it supports and whether it is the default, so you can pick the newest compatible build deliberately.

Working Example

With a version chosen, CreateAddon installs it. EKS deploys the add-on's manifests into the cluster and takes over managing them. For an add-on that calls AWS APIs - like the VPC CNI or EBS CSI driver - pass a serviceAccountRoleArn so it uses an IRSA role rather than the node role.

# --- Python (boto3) ---
import boto3
 
eks = boto3.client("eks", region_name="us-east-1")
eks.create_addon(
    clusterName="platform",
    addonName="aws-ebs-csi-driver",
    addonVersion="v1.31.0-eksbuild.1",
    serviceAccountRoleArn="arn:aws:iam::111122223333:role/ebs-csi-irsa",
    resolveConflicts="OVERWRITE",
)
eks.get_waiter("addon_active").wait(
    clusterName="platform", addonName="aws-ebs-csi-driver",
)

// --- TypeScript (AWS SDK v3) ---
import { EKSClient, CreateAddonCommand, waitUntilAddonActive } from "@aws-sdk/client-eks";
 
const eks = new EKSClient({ region: "us-east-1" });
await eks.send(new CreateAddonCommand({
  clusterName: "platform",
  addonName: "aws-ebs-csi-driver",
  addonVersion: "v1.31.0-eksbuild.1",
  serviceAccountRoleArn: "arn:aws:iam::111122223333:role/ebs-csi-irsa",
  resolveConflicts: "OVERWRITE",
}));
await waitUntilAddonActive(
  { client: eks, maxWaitTime: 300 },
  { clusterName: "platform", addonName: "aws-ebs-csi-driver" },
);

The add-on starts in CREATING and becomes ACTIVE, so wait on addon_active before depending on it. resolveConflicts: "OVERWRITE" tells EKS to take ownership even if a self-managed version of the add-on already exists in the cluster - which is exactly what you want when adopting an add-on that was previously applied by hand.

Deep Dive

Updating and the resolveConflicts Setting

UpdateAddon changes the version or configuration of an existing add-on. The resolveConflicts field is the important nuance: it decides what happens to fields you (or another tool) modified directly on the add-on's Kubernetes objects.

• NONE - fail the update if it would overwrite a field you changed. Safest for detecting drift.
• OVERWRITE - replace your changes with the add-on's managed defaults. Use when EKS should be the source of truth.
• PRESERVE - keep your field-level changes and apply the rest. Use when you intentionally customized the add-on.

# --- Python (boto3) ---
import boto3
 
eks = boto3.client("eks", region_name="us-east-1")
eks.update_addon(
    clusterName="platform",
    addonName="coredns",
    addonVersion="v1.11.1-eksbuild.9",
    resolveConflicts="PRESERVE",
)

// --- TypeScript (AWS SDK v3) ---
import { EKSClient, UpdateAddonCommand } from "@aws-sdk/client-eks";
 
const eks = new EKSClient({ region: "us-east-1" });
await eks.send(new UpdateAddonCommand({
  clusterName: "platform",
  addonName: "coredns",
  addonVersion: "v1.11.1-eksbuild.9",
  resolveConflicts: "PRESERVE",
}));

Custom Configuration

Add-ons accept a JSON configurationValues blob that maps to the underlying chart's settings - replica counts, resource requests, CNI environment variables, and so on. Since this is add-on-specific JSON, it goes as a plain string; here is the shape of a CoreDNS tuning payload:

{
  "replicaCount": 3,
  "resources": {
    "limits": { "cpu": "200m", "memory": "256Mi" },
    "requests": { "cpu": "100m", "memory": "128Mi" }
  }
}

You pass that as configurationValues on CreateAddon or UpdateAddon. Validate the accepted keys per add-on with DescribeAddonConfiguration, which returns the JSON schema the add-on supports so you do not send a field it will reject.

Listing and Removing

ListAddons shows which add-ons EKS manages on a cluster, and DescribeAddon gives the status, version, and health of one. DeleteAddon stops EKS from managing an add-on. By default that removes the add-on's workloads too; pass preserve: true if you want the Kubernetes objects to stay but be self-managed again - handy when moving management to another tool without disrupting running pods.

Gotchas

• Guessing a version string. Add-on versions like v1.18.1-eksbuild.3 are specific and Kubernetes-version-gated. Always call DescribeAddonVersions first.
• Missing IRSA role for AWS-calling add-ons. The VPC CNI and EBS CSI driver need AWS permissions. Without serviceAccountRoleArn they fall back to the node role, which is broader than it should be.
• Wrong resolveConflicts choice. OVERWRITE silently wipes intentional customizations; NONE blocks a needed upgrade. Pick PRESERVE when you have deliberately tuned an add-on.
• Deleting an add-on and its pods by accident. DeleteAddon removes workloads by default. Use preserve: true if you only want to stop managing it, not remove it.
• Not waiting for ACTIVE. An add-on install is asynchronous; depending on it before addon_active returns can race against a not-yet-ready DaemonSet.
• Editing a managed add-on by hand. Direct kubectl edits fight EKS management and get reverted on the next update unless you use PRESERVE. Prefer configurationValues.

Alternatives

• Self-managed add-ons (applying the upstream manifests or Helm charts yourself) when you need a version or configuration EKS does not offer as a managed add-on.
• Helm for community or third-party components that are not available as EKS-managed add-ons at all.
• GitOps (Argo CD, Flux) to declare add-on versions and config in Git and reconcile them, layered over or instead of managed add-ons.
• IaC (eksctl, Terraform, CDK) to declare managed add-ons and their IRSA roles as versioned infrastructure, with the SDK for runtime updates.

Use EKS-managed add-ons for the core AWS-owned components; reach for Helm or GitOps when you need software or knobs the managed add-on catalog does not expose.

FAQs

Related

• IAM Roles for Service Accounts (IRSA) - the role you pass as serviceAccountRoleArn for AWS-calling add-ons.
• What the EKS SDK Actually Manages - why add-ons straddle the AWS and Kubernetes planes.
• EKS via SDK Basics - the cluster these add-ons install into.
• EKS via SDK Best Practices - keeping add-ons current as part of upgrade cadence.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).