Amazon EKS — Control Plane Upgrade

The EKS control plane upgrade is an in-place operation managed by AWS. The API server is updated with a rolling deployment — no downtime for running workloads.

---

How It Works

1. AWS deploys new API server instances running the target Kubernetes version
2. Old API server instances are drained
3. etcd is upgraded
4. All control plane components are updated (scheduler, controller manager)
5. You retain the same cluster endpoint, OIDC issuer, and certificates

---

Trigger the Upgrade

AWS CLI

aws eks update-cluster-version \
  --name my-cluster \
  --kubernetes-version 1.30

eksctl

eksctl upgrade cluster --name my-cluster --version 1.30 --approve

Terraform

module "eks" {
  source  = "terraform-aws-modules/eks/aws"
  version = "~> 20.0"

  cluster_name    = "my-cluster"
  cluster_version = "1.30"    # Change this
  # ...
}

terraform plan
terraform apply

---

Monitor Progress

# Check upgrade status
aws eks describe-update \
  --name my-cluster \
  --update-id <update-id>

# Watch until status is "Successful"
aws eks describe-cluster --name my-cluster --query "cluster.{Version:version,Status:status}"

The update status cycles through:

• InProgress → Successful (or Failed)

---

What Happens During Upgrade

Component	Behavior
API server	Rolling update — brief API latency spikes possible
Running pods	Not affected — continue running
New deployments	May have brief delays during API server swap
Webhooks	Re-validated against new API server
kubectl	Works throughout (same endpoint)

---

Upgrade Duration

Cluster Size	Typical Duration
Small (<10 nodes)	15-25 minutes
Medium (10-100 nodes)	20-35 minutes
Large (100+ nodes)	25-45 minutes

Note: Custom configurations (many add-ons, webhooks, CRDs) can increase upgrade time.

---

Rollback

EKS control plane upgrades cannot be rolled back. If the upgrade fails:

1. AWS will attempt to restore the previous version automatically
2. If automatic rollback fails, contact AWS support
3. Prevention is better than cure — test in non-production first

---

Version Skew Policy

After upgrading the control plane, you have a compatibility window:

Component	Max Version Behind Control Plane
kubelet (nodes)	2 minor versions (K8s policy), EKS recommends 1
kubectl (client)	1 minor version
kube-proxy	Same as kubelet

Upgrade nodes promptly after the control plane — don’t leave them at N-2.

---

Best Practices

1. Always upgrade one minor version at a time — don’t skip versions (1.28 → 1.29 → 1.30)
2. Upgrade during low-traffic periods — API latency spikes are possible
3. Verify health after upgrade — kubectl get nodes, kubectl get pods --all-namespaces
4. Proceed to add-on upgrades immediately — keep add-ons compatible
5. Monitor CloudWatch for API server metrics during upgrade

---