AWS Load Balancer Controller
The AWS Load Balancer Controller manages AWS Elastic Load Balancers for a Kubernetes cluster. The controller provisions:
-
An AWS Application Load Balancer (ALB) when you create a Kubernetes
Ingress
. -
An AWS Network Load Balancer (NLB) when you create a Kubernetes
Service
of typeLoadBalancer
using IP targets on 1.18 or later Amazon EKS clusters. If you're load balancing network traffic to instance targets, then you use the in-tree Kubernetes load balancer controller and don't need to install this controller. For more information about NLB target types, see Target typein the User Guide for Network Load Balancers.
The controller was formerly named the AWS ALB Ingress
Controller. It is an open source
project
Prerequisite
An existing cluster. If you don't have an existing cluster, see Getting started with Amazon EKS.
To deploy the AWS Load Balancer Controller to an Amazon EKS cluster
In the following steps, replace the <example values>
(including
<>
) with your own values.
-
Determine whether you have an existing IAM OIDC provider for your cluster.
View your cluster's OIDC provider URL.
aws eks describe-cluster --name
<cluster_name>
--query "cluster.identity.oidc.issuer" --output textExample output:
https://oidc.eks.
us-west-2
.amazonaws.com/id/EXAMPLED539D4633E53DE1B716D3041E
List the IAM OIDC providers in your account. Replace
(including<EXAMPLED539D4633E53DE1B716D3041E>
) with the value returned from the previous command.<>
aws iam list-open-id-connect-providers | grep
<EXAMPLED539D4633E53DE1B716D3041E>
Example output
"Arn": "arn:aws:iam::
111122223333
:oidc-provider/oidc.eks.us-west-2
.amazonaws.com/id/EXAMPLED539D4633E53DE1B716D3041E
"If output is returned from the previous command, then you already have a provider for your cluster. If no output is returned, then you must create an IAM OIDC provider.
To create an IAM OIDC provider, see Create an IAM OIDC provider for your cluster.
-
Download an IAM policy for the AWS Load Balancer Controller that allows it to make calls to AWS APIs on your behalf. You can view the policy document
on GitHub. curl -o iam_policy_cn.json https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.1.3/docs/install/iam_policy_cn.json
-
Create an IAM policy using the policy downloaded in the previous step.
Take note of the policy ARN that is returned.
-
Create an IAM role and annotate the Kubernetes service account named
aws-load-balancer-controller
in thekube-system
namespace for the AWS Load Balancer Controller usingeksctl
or the AWS Management Console andkubectl
. -
If you currently have the AWS ALB Ingress Controller for Kubernetes installed, uninstall it. The AWS Load Balancer Controller replaces the functionality of the AWS ALB Ingress Controller for Kubernetes.
-
Check to see if the controller is currently installed.
kubectl get deployment -n kube-system alb-ingress-controller
Output (if it is installed). Skip to step 5b.
NAME READY UP-TO-DATE AVAILABLE AGE alb-ingress-controller 1/1 1 1 122d
Output (if it isn't installed). If it isn't installed, skip to step 6.
Error from server (NotFound): deployments.apps "alb-ingress-controller" not found
-
If the controller is installed, enter the following commands to remove it.
kubectl delete -f https://raw.githubusercontent.com/kubernetes-sigs/aws-alb-ingress-controller/v1.1.8/docs/examples/alb-ingress-controller.yaml kubectl delete -f https://raw.githubusercontent.com/kubernetes-sigs/aws-alb-ingress-controller/v1.1.8/docs/examples/rbac-role.yaml
-
If you removed the AWS ALB Ingress Controller for Kubernetes, add the following IAM policy to the IAM role created in step 4. The policy allows the AWS Load Balancer Controller access to the resources that were created by the ALB Ingress Controller for Kubernetes.
-
Download the IAM policy. You can also view the policy
. curl -o iam_policy_v1_to_v2_additional.json https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.1.3/docs/install/iam_policy_v1_to_v2_additional.json
-
Create the IAM policy and note the ARN returned.
aws iam create-policy \ --policy-name
AWSLoadBalancerControllerAdditionalIAMPolicy
\ --policy-document file://iam_policy_v1_to_v2_additional.json -
Attach the IAM policy to the IAM role that you created in step 4. Replace
<your-role-name>
(including<>
) with the name of the role. If you created the role usingeksctl
, then to find the role name that was created, open the AWS CloudFormation consoleand select the eksctl- <your-cluster-name>
-addon-iamserviceaccount-kube-system-aws-load-balancer-controller stack. Select the Resources tab. The role name is in the Physical ID column. If you used the AWS Management Console to create the role, then the role name is whatever you named it, such asAmazonEKSLoadBalancerControllerRole
.aws iam attach-role-policy \ --role-name eksctl-
<your-role name>
\ --policy-arn arn:aws:iam::111122223333
:policy/AWSLoadBalancerControllerAdditionalIAMPolicy
-
-
-
Install the AWS Load Balancer Controller using Helm V3 or later or by applying a Kubernetes manifest.
-
Verify that the controller is installed.
kubectl get deployment -n kube-system aws-load-balancer-controller
Output
NAME READY UP-TO-DATE AVAILABLE AGE aws-load-balancer-controller 1/1 1 1 84s
-
Before using the controller to provision AWS resources, your cluster must meet specific requirements. For more information, see Application load balancing on Amazon EKS and Network load balancing on Amazon EKS.