How do I use AWS Load Balancer Controller to set up an Application Load Balancer on an Amazon EC2 node group in Amazon EKS?

Resolution

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

Prerequisite: Configure your subnets to allow outbound internet access from your worker nodes. AWS Load Balancer Controller requires an outbound internet connection.

To deploy AWS Load Balancer Controller on AWS Fargate, see How do I set up the AWS Load Balancer Controller on an Amazon EKS cluster for Fargate?

Tag your subnets

Tag the Amazon Virtual Private Cloud (Amazon VPC) subnets in your Amazon EKS cluster. After you tag your subnets, your AWS Load Balancer Controller automatically discovers subnets when you create the Application Load Balancer resource.

For public Application Load Balancers, you must have at least two public subnets in your cluster's VPC with the kubernetes.io/role/elb tag.

For private Application Load Balancers, you must have at least two private subnets in your cluster's VPC with the kubernetes.io/role/internal-elb tag.

Create an OIDC identity provider

Use the Amazon EKS console, the AWSL CLI, or eksctl to create an OIDC identity provider to use with AWS Identity and Access Management (IAM) roles for service accounts (IRSA).

Amazon EKS console

To use the console, see Create an OIDC identity provider (AWS Console).

AWSL CLI

Locate the thumbprint of the root certificate authority (CA) that your cluster uses. Then, run the following create-open-id-connect-provider command:

ISSUER_URL=$(aws eks describe-cluster --name cluster-name \  --query "cluster.identity.oidc.issuer" --region region-name --output text)aws iam create-open-id-connect-provider \  
  --url ${ISSUER_URL} \  
  --thumbprint-list ca-thumbprint \  
  --client-id-list sts.amazonaws.com \  
  --region region-name

Note: Replace cluster-name with your cluster name, region-name with your AWS Region and ca-thumbprint with the thumbprint of your root CA certificate.

eksctl

To use the eksctl command line tool, see create an OIDC identity provider (eksctl).

Create an IAM policy

Create an IAM policy that allows AWS Load Balancer Controller to make calls to AWS APIs.

Important: It's a best practice to use IRSA when you grant access to AWS APIs.

Complete the following steps:

1. Run one of the following commands based on your Region to download an IAM policy for the AWS Load Balancer Controller from GitHub.
   For all Regions except Beijing and Ningxia China Regions, run the following describe-cluster command:

   ISSUER_URL= aws eks describe-cluster --name example-cluster-name \  --query "cluster.identity.oidc.issuer" --region example-region-name --output text  
   aws iam create-open-id-connect-provider \  
     --url example-issuer-url \  
     --thumbprint-list ca-thumbprint \  
     --client-id-list sts.amazonaws.com \  --region example-region-name

   Note: Replace example-cluster-name with your cluster's name, example-region-name with your Region, and example-issuer-url with your issuer's URL.
   For Beijing and Ningxia China Regions, run the following curl command:

   curl -o iam-policy.json https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/main/docs/install/iam_policy_cn.json

2. Run the following create-policy command to create an IAM policy that's named AWSLoadBalancerControllerIAMPolicy for your worker node instance profile:

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

3. Note the Amazon Resource Name (ARN) of the policy that the command returns.

4. Use the existing IAM role, or create a new IAM role for AWS Load Balancer Controller.
   Note: To use eksctl to create an IAM role, use the --attach-policy-arn parameter with the AWSLoadBalancerControllerIAMPolicy IAM policy's ARN.

5. Run the following attach-role-policy command to attach AWSLoadBalancerControllerIAMPolicy to your IAM role:

   aws iam attach-role-policy \--policy-arn arn:aws:iam::111122223333:policy/AWSLoadBalancerControllerIAMPolicy \--role-name role-name  
   

   Note: Replace 111122223333 with your AWS account ID and role-name with your IAM role name.

Deploy the AWS Load Balancer Controller

Complete the following steps:

1. Verify that you have the required tag for the load balancer that's associated with your subnets.

2. Run the following command with Kubernetes 1.16 or later to install cert-manager:

   kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/example-version/cert-manager.yaml

3. In the manifest file that you downloaded from GitHub, run the following command:

   curl -Lo ingress-controller.yaml https://github.com/kubernetes-sigs/aws-load-balancer-controller/releases/download/example-version/v2_13_3_full.yaml  
   

   Note: Replace example-version with the version of AWS Load Balancer Controller that you want to deploy. To verify the AWS Load Balancer Controller version, see Kubernetes SIGs on the GitHub website. Be sure to modify the file name to match your version. In the preceding code example, v2_13_3_full.yaml matches AWS Load Balancer Controller v2.13.3. For more information, see aws-load-balancer-controller on the GitHub website.

4. Make the following updates in the ServiceAccount section of the .yaml file:

   spec:        containers:  
       - args:  
           - --cluster-name=example-cluster-name  
           - --ingress-class=alb

   Note: Replace example-cluster-name with your cluster's name.
   In the following example, 111122223333 is the account ID and example-role-name is the IAM role name:

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

5. Run the following command to deploy AWS Load Balancer Controller:

   kubectl apply -f ingress-controller.yaml

Deploy a sample application

Deploy a sample application to verify that the AWS Load Balancer Controller creates a public Application Load Balancer because of the inbound object.

Complete the following steps:

1. Run the following command to deploy a game that's called 2048:

   kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/example-version/docs/examples/2048/2048_full.yaml

   Note: Replace example-version with the version of the AWS Load Balancer Controller that you want to deploy. To verify your AWS Load Balancer Controller version, see Kubernetes SIGs at the GitHub website.

2. After a few minutes, run the following command to verify that Kubernetes created the inbound resource:

   kubectl get ingress/ingress-2048 -n game-2048

   Example output:

   NAME           CLASS    HOSTS   ADDRESS                                                                   PORTS   AGEingress-2048   <none>   *       k8s-game2048-ingress2-xxxxxxxxxx-yyyyyyyyyy.us-west-2.elb.amazonaws.com   80      2m32s

3. If Kubernetes doesn't create your inbound resource, then run the following command to review the AWS Load Balancer Controller logs for deployment error messages:

   kubectl logs -n kube-system   deployment.apps/aws-load-balancer-controller

4. To see the game, open a web browser, and then enter the URL address from the output in step 2.

5. Run the following command to delete the game: 

   kubectl delete -f https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/example-version/docs/examples/2048/2048_full.yaml

   Note: Replace example-version with the version of the AWS Load Balancer Controller that you want to deploy.