Amazon Load Balancer Controller - Amazon EKS
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

Amazon Load Balancer Controller

The Amazon Load Balancer Controller manages Amazon Elastic Load Balancers for a Kubernetes cluster. The controller provisions the following resources.

  • An Amazon Application Load Balancer (ALB) when you create a Kubernetes Ingress.

  • An Amazon Network Load Balancer (NLB) when you create a Kubernetes service of type LoadBalancer. In the past, the Kubernetes in-tree load balancer was used for instance targets, but the Amazon Load balancer Controller was used for IP targets. With the Amazon Load Balancer Controller version 2.3.0 or later, you can create Network Load Balancers using either target type. For more information about NLB target types, see Target type in the User Guide for Network Load Balancers.

The controller was formerly named the Amazon ALB Ingress Controller. It's an open-source project managed on GitHub. This topic describes how to install the controller using default options. You can view the full documentation for the controller on GitHub. Before deploying the controller, we recommend that you review the prerequisites and considerations in Application load balancing on Amazon EKS and Network load balancing on Amazon EKS. Those topics also include steps on how to deploy a sample application that require the controller to provision Amazon resources.

Prerequisites

To deploy the Amazon Load Balancer Controller to an Amazon EKS cluster

In the following steps, replace the example values with your own values.

  1. Download an IAM policy for the Amazon Load Balancer Controller that allows it to make calls to Amazon 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.3.1/docs/install/iam_policy_cn.json

  2. Create an IAM policy using the policy downloaded in the previous step.

    aws iam create-policy \
    --policy-name AWSLoadBalancerControllerIAMPolicy \
    --policy-document file://iam_policy_cn.json
    Note

    If you view the policy in the Amazon Web Services 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.

  3. Create an IAM role and annotate the Kubernetes service account that's named aws-load-balancer-controller in the kube-system namespace for the Amazon Load Balancer Controller using eksctl or the Amazon Web Services Management Console and kubectl.

    eksctl

    Replace my-cluster with the name of your cluster and 111122223333 with your account ID and then run the command. The cluster name can contain only alphanumeric characters (case-sensitive) and hyphens. It must start with an alphabetic character and can't be longer than 128 characters.

    eksctl create iamserviceaccount \
  --cluster=my-cluster \
  --namespace=kube-system \
  --name=aws-load-balancer-controller \
  --attach-policy-arn=arn:aws-cn:iam::111122223333:policy/AWSLoadBalancerControllerIAMPolicy \
  --override-existing-serviceaccounts \
  --approve
    Amazon Web Services Management Console and kubectl

    Using the Amazon Web Services Management Console and kubectl

    1. Open the IAM console at https://console.amazonaws.cn/iam/.

    2. In the navigation panel, choose Roles, Create Role.

    3. In the Select type of trusted entity section, choose Web identity.

    4. In the Choose a web identity provider section:

      1. For Identity provider, choose the URL for your cluster. If you don't see a URL, confirm that you met the prerequisites for this topic.

      2. For Audience, choose sts.amazonaws.com.

    5. Choose Next: Permissions.

    6. In the Attach Policy section, select the AWSLoadBalancerControllerIAMPolicy policy that you created in a previous step to use for your service account.

    7. Choose Next: Tags.

    8. On the Add tags (optional) screen, you can add tags for the account. Choose Next: Review.

    9. For Role Name, enter a name for your role, such as AmazonEKSLoadBalancerControllerRole, and then choose Create Role.

    10. After the role is created, choose the role in the console to open it for editing.

    11. Choose the Trust relationships tab, and then choose Edit trust relationship.

    12. Find the line that looks similar to the following line:

      "oidc.eks.cn-north-1.amazonaws.com.cn/id/EXAMPLED539D4633E53DE1B716D3041E:aud": "sts.amazonaws.com"

      Change the line to look like the following line. Replace EXAMPLED539D4633E53DE1B716D3041E with your cluster's OIDC provider ID and if necessary, replace region-code with the Region code that your cluster is in. Change aud to sub and replace sts.amazonaws.com with the value in the following text.

      "oidc.eks.region-code.amazonaws.com.cn/id/EXAMPLED539D4633E53DE1B716D3041E:sub": "system:serviceaccount:kube-system:aws-load-balancer-controller"

    13. Choose Update Trust Policy to finish.

    14. Note the ARN of the role for use in a later step.

    15. Save the following contents to a file that's named aws-load-balancer-controller-service-account.yaml, replacing 111122223333 with your account ID.

      apiVersion: v1
kind: ServiceAccount
metadata:
  labels:
    app.kubernetes.io/component: controller
    app.kubernetes.io/name: aws-load-balancer-controller
  name: aws-load-balancer-controller
  namespace: kube-system
  annotations:
      eks.amazonaws.com/role-arn: arn:aws-cn:iam::111122223333:role/AmazonEKSLoadBalancerControllerRole

    16. Create the service account on your cluster.

      kubectl apply -f aws-load-balancer-controller-service-account.yaml

  4. If you currently have the Amazon ALB Ingress Controller for Kubernetes installed, uninstall it. The Amazon Load Balancer Controller replaces the functionality of the Amazon ALB Ingress Controller for Kubernetes.

    1. Check to see if the controller is currently installed.

      kubectl get deployment -n kube-system alb-ingress-controller

      This is the output if the controller isn't installed. Skip to the install controller step.

      Error from server (NotFound): deployments.apps "alb-ingress-controller" not found

      This is the output if the controller is installed.

      NAME                   READY UP-TO-DATE AVAILABLE AGE
alb-ingress-controller 1/1   1          1         122d

    2. Enter the following commands to remove the controller.

      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

    3. Add the following IAM policy to the IAM role created in a previous step. The policy allows the Amazon Load Balancer Controller access to the resources that were created by the ALB Ingress Controller for Kubernetes.

      1. 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.3.1/docs/install/iam_policy_v1_to_v2_additional.json

      2. Create the IAM policy and note the ARN that is returned.

        aws iam create-policy \
  --policy-name AWSLoadBalancerControllerAdditionalIAMPolicy \
  --policy-document file://iam_policy_v1_to_v2_additional.json

      3. Attach the IAM policy to the IAM role that you created in a previous step. Replace your-role-name with the name of the role. If you created the role using eksctl, then to find the role name that was created, open the Amazon CloudFormation console and 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 Amazon Web Services Management Console to create the role, then the role name is whatever you named it, such as AmazonEKSLoadBalancerControllerRole.

        aws iam attach-role-policy \
  --role-name your-role name \
  --policy-arn arn:aws-cn:iam::111122223333:policy/AWSLoadBalancerControllerAdditionalIAMPolicy

  5. Install the Amazon 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 chart. It doesn't depend on cert-manager.

    Helm V3 or later

    1. Add the eks-charts repository.

      helm repo add eks https://aws.github.io/eks-charts

    2. Update your local repo to make sure that you have the most recent charts.

      helm repo update

    3. Install the Amazon Load Balancer Controller. If you're deploying the controller to Amazon EC2 nodes that have restricted access to the Amazon EC2 instance metadata service (IMDS), or if you're deploying to Fargate, then add the following flags to the following command:

      • --set region=region-code

      • --set vpcId=vpc-xxxxxxxx

      If you're deploying to any Region other than us-west-2, then add the following flag to the following command, replacing account and region-code with the values for your region listed in Amazon EKS add-on container image addresses. The cluster name can contain only alphanumeric characters (case-sensitive) and hyphens. It must start with an alphabetic character and can't be longer than 128 characters.

      --set image.repository=account.dkr.ecr.region-code.amazonaws.com.cn/amazon/aws-load-balancer-controller

      helm install aws-load-balancer-controller eks/aws-load-balancer-controller \
  -n kube-system \
  --set clusterName=cluster-name \
  --set serviceAccount.create=false \
  --set serviceAccount.name=aws-load-balancer-controller \
  --set enableShield=false \
  --set enableWaf=false \
  --set enableWafv2=false \
  --set image.repository=918309763551.dkr.ecr.cn-north-1.amazonaws.com.cn/amazon/aws-load-balancer-controller
      Important

      The deployed chart doesn't receive security updates automatically. You need to manually upgrade to a newer chart when it becomes available. When upgrading, change install to upgrade in the previous command, but run the following command to install the TargetGroupBinding custom resource definitions before running the previous command.

      kubectl apply -k "github.com/aws/eks-charts/stable/aws-load-balancer-controller/crds?ref=master"
    Kubernetes manifest

    1. Install cert-manager to inject certificate configuration into the webhooks.

      kubectl apply \
    --validate=false \
    -f https://github.com/jetstack/cert-manager/releases/download/v1.5.4/cert-manager.yaml

    2. Install the controller.

      1. Download the controller specification. For more information about the controller, see the documentation on GitHub.

        curl -Lo v2_3_1_full.yaml https://github.com/kubernetes-sigs/aws-load-balancer-controller/releases/download/v2.3.1/v2_3_1_full.yaml

      2. Make the following edits to the v2_3_1_full.yaml file:

        • Delete the ServiceAccount section of the file. Deleting this section prevents the annotation with the IAM role from being overwritten when the controller is deployed and preserves the service account that you created in step 3 if you delete the controller.

        • Replace your-cluster-name in the Deployment spec section of the file with the name of your cluster and add the following parameters under --ingress-class=alb.

          ...
spec:
      containers:
        - args:
            - --cluster-name=your-cluster-name
            - --ingress-class=alb
              --enable-shield=false
              --enable-waf=false
              --enable-wafv2=false
...

        • If you're deploying the controller to Amazon EC2 nodes that have restricted access to the Amazon EC2 instance metadata service (IMDS), or if you're deploying to Fargate, then add the following parameters under - args:.

          ...
spec:
      containers:
        - args:
            - --cluster-name=your-cluster-name
            - --ingress-class=alb
              --enable-shield=false
              --enable-waf=false
              --enable-wafv2=false
            - --aws-vpc-id=vpc-xxxxxxxx
            - --aws-region=region-code
...

      3. Apply the file.

        kubectl apply -f v2_3_1_full.yaml

  6. 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   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.

  7. Before using the controller to provision Amazon resources, your cluster must meet specific requirements. For more information, see Application load balancing on Amazon EKS and Network load balancing on Amazon EKS.