AWS Load Balancer Controller Upgrade Guide: v2.x to v3.3

AWS Load Balancer Controller Upgrade Guide: v2.x to v3.3



What is AWS Load Balancer Controller?

AWS Load Balancer Controller is a Kubernetes controller that integrates Amazon EKS with AWS Elastic Load Balancing services. It watches Kubernetes resources and automatically creates or updates AWS load balancing resources based on the desired state defined inside the cluster.

Instead of manually creating load balancers, listeners, target groups, and security group rules in AWS, teams can define Kubernetes resources such as Ingresses and Services. The controller then reconciles those resources with AWS.

What Does It Manage?

AWS Load Balancer Controller commonly manages:

  • Application Load Balancers (ALB)
  • Network Load Balancers (NLB)
  • Listeners and listener rules
  • Target groups
  • Target registration and deregistration
  • Security group rules
  • Ingress resources
  • TargetGroupBinding resources

Because the controller interacts with both Kubernetes APIs and AWS APIs, upgrading it should be treated as a platform change, not just a simple image version update.

Why Review the Upgrade Carefully?

A major version upgrade, such as moving from AWS Load Balancer Controller v2.x to v3.3, can introduce changes in multiple areas:

  • Custom Resource Definitions (CRDs)
  • IAM permissions
  • Kubernetes RBAC
  • Controller flags
  • Admission webhooks
  • Ingress annotations
  • Gateway API support
  • AWS API integrations

How AWS load balancer controller works

Reviewing these areas before upgrading helps reduce the chance of runtime issues such as reconciliation failures, webhook errors, or missing IAM permissions.

1. Review CRD Changes

AWS Load Balancer Controller uses CRDs to extend Kubernetes with additional AWS-specific resources. Before upgrading, compare the CRDs between the current version and the target version.

Common CRDs include:

  • TargetGroupBinding
  • IngressClassParams

Useful commands:

kubectl get crd | grep elbv2.k8s.aws

kubectl get crd targetgroupbindings.elbv2.k8s.aws \
  -o jsonpath='{range .spec.versions[*]}{.name}{" served="}{.served}{" storage="}{.storage}{"\n"}{end}'

kubectl get crd ingressclassparams.elbv2.k8s.aws \
  -o jsonpath='{range .spec.versions[*]}{.name}{" served="}{.served}{" storage="}{.storage}{"\n"}{end}'

Questions to ask:

  • Are new CRDs introduced?
  • Are any CRDs removed?
  • Did the storage version change?
  • Are existing resources still using supported API versions?

2. Understand New CRDs in v3.3

In v3.3, new capabilities may introduce additional CRDs such as:

  • ALBTargetControlConfig
  • GlobalAccelerator

New CRDs are not automatically a breaking change. They often represent optional new features. The important question is whether your cluster already uses those resources or plans to adopt them.

Check whether resources exist:

kubectl get albtargetcontrolconfigs -A
kubectl get globalaccelerators -A

If no resources exist, these CRDs are usually low risk for existing Ingress and TargetGroupBinding workloads.

3. Review IAM Policy Changes

AWS Load Balancer Controller needs IAM permissions to create, update, and delete AWS resources. Each controller version may require a slightly different IAM policy.

Compare the IAM policy between versions:

curl -L -o iam-v2.json \
https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.11.0/docs/install/iam_policy.json

curl -L -o iam-v3.json \
https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v3.3.0/docs/install/iam_policy.json

diff iam-v2.json iam-v3.json

Look for:

  • New AWS permissions
  • Removed permissions
  • Changes in resource scope

Missing IAM permissions may not always prevent the controller from starting. Instead, they may appear later as reconciliation failures when an Ingress, Service, listener rule, or target group needs to be updated.

4. Review Controller Flags

Controller startup arguments should be reviewed during upgrades. A removed or renamed flag can prevent the controller pod from starting.

Check current controller arguments:

kubectl -n kube-system get deploy aws-load-balancer-controller \
  -o jsonpath='{.spec.template.spec.containers[0].args}'

Common flags include:

  • --cluster-name
  • --ingress-class
  • --watch-namespace

Compare your current flags with the target version manifest or Helm chart values.

5. Review Kubernetes RBAC Changes

AWS Load Balancer Controller uses Kubernetes RBAC permissions to watch and update Kubernetes resources. During an upgrade, compare the ClusterRole between versions.

Look for:

  • New API groups
  • New resources
  • New verbs such as patch, update, or watch
  • Removed permissions

Additive RBAC changes are common when new features are introduced. Removed permissions should be reviewed more carefully.

6. Review Ingress and Service Annotations

Many ALB and NLB behaviors are controlled through annotations. Before upgrading, collect the annotations currently used by workloads. 

kubectl get ingress -A -o yaml \
  | grep "alb.ingress.kubernetes.io" \
  | sed 's/.*alb\.ingress\.kubernetes\.io\///' \
  | cut -d: -f1 \
  | sort -u

Common ALB annotations include:

  • alb.ingress.kubernetes.io/scheme
  • alb.ingress.kubernetes.io/target-type
  • alb.ingress.kubernetes.io/listen-ports
  • alb.ingress.kubernetes.io/ssl-redirect
  • alb.ingress.kubernetes.io/healthcheck-path
  • alb.ingress.kubernetes.io/group.name

Check whether any annotations are deprecated, replaced, or have changed behavior in the target version.

7. Understand the Deployment Method

The upgrade process depends on how AWS Load Balancer Controller is installed.

Helm

With Helm, CRDs often need to be applied separately before upgrading the release because Helm does not always upgrade existing CRDs. 

kubectl apply -f crds.yaml
helm upgrade aws-load-balancer-controller ...

Raw Manifests

With raw manifests, the versioned full manifest can include CRDs, RBAC, webhooks, and the controller deployment. 

kubectl apply -f https://github.com/kubernetes-sigs/aws-load-balancer-controller/releases/download/v3.3.0/v3_3_0_full.yaml

Always inspect the manifest before applying it so you understand exactly what will change.

8. Apply the Upgrade in a Lower Environment First

Before upgrading production, test in a lower environment such as sandbox, development, or QA.

After applying the upgrade, verify the controller image:

kubectl -n kube-system get deploy aws-load-balancer-controller \
  -o jsonpath='{.spec.template.spec.containers[0].image}'

Verify controller rollout:

kubectl rollout status deployment/aws-load-balancer-controller -n kube-system

9. Post-Upgrade Validation

After the upgrade, validate the following:

  • Controller pods are running and ready.
  • The controller image is the expected version.
  • CRDs are present.
  • Ingress resources still exist.
  • TargetGroupBinding resources still exist.
  • Controller logs do not show IAM or reconciliation errors.

Useful commands:

kubectl get pods -n kube-system -l app.kubernetes.io/name=aws-load-balancer-controller

kubectl get ingress -A

kubectl get targetgroupbindings -A

kubectl logs -n kube-system deploy/aws-load-balancer-controller --tail=200

Look for errors such as:

AccessDenied
UnauthorizedOperation
failed to reconcile
webhook error
panic

10. Final Checklist

  • Release notes reviewed
  • CRD changes reviewed
  • IAM policy changes reviewed
  • RBAC changes reviewed
  • Controller flags reviewed
  • Ingress and Service annotations reviewed
  • Deployment method understood
  • Upgrade tested in a lower environment
  • Post-upgrade logs checked
  • Existing Ingress and TargetGroupBinding resources verified

Conclusion

Upgrading AWS Load Balancer Controller from v2.x to v3.3 should be approached as a platform upgrade. The controller manages critical networking resources and depends on Kubernetes APIs, AWS IAM permissions, RBAC, CRDs, and webhooks.

A structured review process helps identify potential issues before they affect workloads. By reviewing CRDs, IAM, RBAC, controller flags, annotations, and deployment strategy, teams can make ALBC upgrades safer, more predictable, and easier to repeat in the future.