Installing the AWS Load Balancer Controller add-on
The AWS Load Balancer Controller manages AWS Elastic Load Balancers for a Kubernetes cluster. The controller provisions the following resources:
-
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 type
LoadBalancer
. In the past, the Kubernetes network load balancer was used for instance targets, but the AWS Load balancer Controller was used for IP targets. With the AWS Load Balancer Controller version2.3.0
or later, you can create NLBs using either target type. For more information about NLB target types, see Target type in the User Guide for Network Load Balancers.
The AWS Load Balancer Controller controller was formerly named the AWS ALB Ingress Controller. It's an open-source
project
Prerequisites
-
An existing Amazon EKS cluster. To deploy one, see Getting started with Amazon EKS. To use version
2.4.2
of the controller, which is the version used in this topic, your cluster must be1.19
or later. If your cluster is earlier than1.19
, then we recommend using version2.3.1
. -
An existing AWS Identity and Access Management (IAM) OpenID Connect (OIDC) provider for your cluster. To determine whether you already have one, or to create one, see Create an IAM OIDC provider for your cluster.
-
If your cluster is
1.21
or later, make sure that your Amazon VPC CNI plugin for Kubernetes,kube-proxy
, and CoreDNS add-ons are at the minimum versions listed in Service account tokens.
To deploy the AWS Load Balancer Controller to an Amazon EKS cluster
In the following steps, replace the
with your own values. If your cluster is earlier than
example
values
1.19
, then change all instances of 2.4.2
to 2.3.1
and all instances of
v2_4_2_full.yaml
to
v2_3_1_full.yaml
.
-
Create an IAM policy.
-
Download an IAM policy for the AWS Load Balancer Controller that allows it to make calls to AWS APIs on your behalf.
-
AWS GovCloud (US-East) or AWS GovCloud (US-East) AWS Regions
curl -o iam_policy_us-gov.json https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.4.2/docs/install/iam_policy_us-gov.json
-
All other AWS Regions
curl -o iam_policy.json https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.4.2/docs/install/iam_policy.json
-
-
Create an IAM policy using the policy downloaded in the previous step. If you downloaded
iam_policy_us-gov.json
, changeiam_policy.json
toiam_policy_us-gov.json
before running the command.aws iam create-policy \ --policy-name
AWSLoadBalancerControllerIAMPolicy
\ --policy-document file://iam_policy.jsonNote If you view the policy in the AWS Management Console, you may see warnings for ELB. These can be safely ignored because some of the actions only exist for ELB v2. You do not see warnings for ELB v2.
-
-
Create an IAM role. Create a Kubernetes service account named
aws-load-balancer-controller
in thekube-system
namespace for the AWS Load Balancer Controller and annotate the Kubernetes service account with the name of the IAM role.You can use
eksctl
or the AWS CLI andkubectl
to create the IAM role and Kubernetes service account. (Optional) Configure the AWS Security Token Service endpoint type used by your Kubernetes service account. For more information, see Configure the AWS Security Token Service endpoint for a service account.
If you don't currently have the AWS ALB Ingress Controller for Kubernetes installed, or don't currently have the
0.1.x
version of the AWS Load Balancer Controller installed with Helm, then skip to the next step.Uninstall the AWS ALB Ingress Controller or
0.1.x
version of the AWS Load Balancer Controller (only if installed with Helm). Complete the procedure using the tool that you originally installed it with. The AWS Load Balancer Controller replaces the functionality of the AWS ALB Ingress Controller for Kubernetes.-
Install the AWS Load Balancer Controller using Helm V3 or later or by applying a Kubernetes manifest. If you want to deploy the controller on Fargate, use the Helm procedure because it doesn't depend on
cert-manager
. -
Verify that the controller is installed.
kubectl get deployment -n kube-system aws-load-balancer-controller
The example output is as follows.
NAME READY UP-TO-DATE AVAILABLE AGE aws-load-balancer-controller 2/2 2 2 84s
You receive the previous output if you deployed using Helm. If you deployed using the Kubernetes manifest, you only have one replica.
-
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.