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

Short description

The following steps show you how to deploy the Application Load Balancer using the AWS Load Balancer Controller on an Amazon EC2 node group with Amazon EKS. To create a Network Load Balancer, see AWS Load Balancer Controller.

The AWS Load Balancer Controller must be connected to an AWS service endpoint, such as AWS Identity and Access Management (IAM), EC2, AWS Certificate Manager (ACM), Elastic Load Balancing, Amazon Cognito, AWS WAF, or AWS Shield. This means that you must have an outbound internet connection for AWS Load Balancer Controller to work. For more information, see How do I configure my subnets for an Amazon EKS cluster?

To deploy the 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 and deploy the 2048 game?

Resolution

Tag your subnets to allow auto discovery

Tag the Amazon VPC subnets in your Amazon EKS cluster to allow your AWS Load Balancer Controller to autodiscover subnets when the Application Load Balancer resource is created.

For public Application Load Balancers, you must have at least two public subnets in your cluster's VPC with the following tags:

kubernetes.io/role/elb

For internal Application Load Balancers, you must have at least two private subnets in your cluster's VPC with the following tags:

kubernetes.io/role/internal-elb

Note: If you receive errors when running AWS Command Line Interface (AWS CLI) commands, be sure that you’re using the most recent version of the AWS CLI.

Create an OIDC identity provider for your cluster

To create an OpenID Connect (OIDC) identity provider for your cluster to use with AWS Identity and Access Management (IAM) roles for service accounts, use either eksctl or the AWS Management Console.

You can also use the AWSL CLI to create an OIDC identity provider for your cluster. For example:

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. You can get the thumbprint of the root CA certificate that your cluster uses with oidc.eks.region-name.amazonaws.com.

Create an IAM policy for the AWS Load Balancer Controller

The Amazon EKS policy that you create allows the AWS Load Balancer Controller to make calls to AWS APIs on your behalf. It's a best practice to use AWS IAM roles for service accounts when you grant access to AWS APIs.

1.    To download an IAM policy document for the AWS Load Balancer Controller from AWS GitHub, run one of the following commands based on your Region.

All Regions other than China Regions:

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

-or-

Beijing and Ningxia China Regions:

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

2.    To create an IAM policy named AWSLoadBalancerControllerIAMPolicy for your worker node instance profile, run the following command:

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

3.    Note the Amazon Resource Name (ARN) of the policy that's returned in the output from step 2.

4.    Use the existing IAM role or create a new IAM role for the AWS Load Balancer Controller.

Tip: To create an IAM role with eksctl, use the --attach-policy-arn parameter with the ARN of the IAM policy AWSLoadBalancerControllerIAMPolicy.

5.    To attach AWSLoadBalancerControllerIAMPolicy to IAM roles that you identified earlier, run the following command:

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

1.    Verify that you have the required tags for the load balancer associated with your subnets.

2.    Install cert-manager so that you can inject the certificate configuration into the webhooks.

For Kubernetes 1.16 or later:

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

For Kubernetes 1.15 or earlier:

kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/$VERSION/cert-manager-legacy.yaml

Note: Replace $VERSION with the version (from the Jetstack GitHub site, for example 'v1.6.0') of the cert-manager that you want to deploy.

3.    In the downloaded manifest file for the AWS Load Balancer Controller from AWS GitHub, run the following command:

curl -Lo ingress-controller.yaml https://github.com/kubernetes-sigs/aws-load-balancer-controller/releases/download/$VERSION/v2_4_1_full.yaml

Note: Replace $VERSION with the version (from the Kubernetes SIGs GitHub site for example 'v2.4.1') of the AWS Load Balancer Controller that you want to deploy.

4.    Edit the cluster-name for your cluster. For example:

spec:
    containers:
    - args:
        - --cluster-name=your-cluster-name # edit the cluster name
        - --ingress-class=alb

5.    Update only the ServiceAccount section of the file only. For example:

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

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

6.    To deploy the AWS Load Balancer Controller, run the following command:

kubectl apply -f ingress-controller.yaml

Deploy a sample application to test the AWS Load Balancer Controller

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

1.    To deploy a game called 2048 as a sample application, run the following command:

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

Note: Replace $VERSION with the version (from the Kubernetes SIGs GitHub site for example 'v2.3.0') of the AWS Load Balancer Controller that you want to deploy.

2.    To verify that the Ingress resource was created, wait a few minutes, and then run the following command:

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

You receive output similar to the following:

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

If your Ingress isn't created after several minutes, then run the following command to view the AWS Load Balancer Controller logs:

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

Note: AWS Load Balancer Controller logs can show error messages to help you troubleshoot issues with your deployment.

3.    To see the sample application, open a web browser, and then go to the URL address from the output in step 2.

4.    To clean up the sample application, run the following command:

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

Note: Replace $VERSION with the version (from the Kubernetes SIGs GitHub site for example 'v2.3.0') of the AWS Load Balancer Controller that you want to deploy.