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

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.

You can set up AWS Load Balancer Controller without any existing Application Load Balancer ingress controller deployments.

Prerequisites:

• Uninstall the existing AWS ALB Ingress Controller for Kubernetes. The AWS Load Balancer Controller replaces its functionality.
• Use eksctl version 0.109.0 or later. For more information, see Installation on the eksctl website.
• Install Helm on your workstation.

Create an Amazon EKS cluster, service AWS account policy, and role-based access control policies

Complete the following steps:

1. To use eksctl to create an Amazon EKS cluster, run the following command:

   eksctl create cluster \
     --name YOUR_CLUSTER_NAME \
     --version 1.28 \
     --fargate

   Note: Replace YOUR_CLUSTER_NAME with your cluster name. You don't need to create a Fargate pod execution role for clusters that use only Fargate pods (--fargate).

2. To allow the cluster to use AWS Identity and Access Management (IAM) for service accounts, run the following command:

   eksctl utils associate-iam-oidc-provider \
     --cluster YOUR_CLUSTER_NAME \
     --approve

   Note: Replace YOUR_CLUSTER_NAME with your cluster name. The kubelet and kube-proxy use FargateExecutionRole to run your Fargate pod. However, FargateExecutionRole isn't the Fargate pod's IAM role. For Fargate pods, you must use the IAM role for the service account.

3. To download an IAM policy that allows the AWS Load Balancer Controller to make calls to AWS APIs on your behalf, run the following command:

4.  curl -o iam_policy.json https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.11.0/docs/install/iam_policy.json

5. To create an IAM policy with the downloaded policy, run the following create-policy AWS CLI command:

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

6. To create a service account for the AWS Load Balancer Controller, run the following command:

   eksctl create iamserviceaccount \
     --cluster=YOUR_CLUSTER_NAME \
     --namespace=kube-system \
     --name=aws-load-balancer-controller \
     --attach-policy-arn=arn:aws:iam::AWS_ACCOUNT_ID:policy/AWSLoadBalancerControllerIAMPolicy \
     --override-existing-serviceaccounts \
     --approve

   Note: Replace YOUR_CLUSTER_NAME with your cluster name and AWS_ACCOUNT_ID with your account ID. The preceding command creates a service account named aws-load-balancer-controller in the kube-system namespace.

7. To verify that the new service role is created, run one of the following commands:

   eksctl get iamserviceaccount \
     --cluster=YOUR_CLUSTER_NAME \
     --name=aws-load-balancer-controller \
     --namespace=kube-system

   Note: Replace YOUR_CLUSTER_NAME with your cluster name.
   -or-

   kubectl get serviceaccount aws-load-balancer-controller \
     --namespace kube-system \
     -o yaml

Install the AWS Load Balancer Controller with Helm

Complete the following steps:

1. To add the Amazon EKS chart to Helm, run the following command:

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

2. To update the repository and pull the latest chart, run the following command:

   helm repo update eks 

3. To install the Helm chart, run the following command:

   helm install aws-load-balancer-controller eks/aws-load-balancer-controller \
     --set clusterName=YOUR_CLUSTER_NAME \
     --set serviceAccount.create=false \
     --set region=YOUR_REGION_CODE \
     --set vpcId=EKS_CLUSTER_VPC_ID \
     --set serviceAccount.name=aws-load-balancer-controller \
     --version 1.11.0 \
     -n kube-system

   Note: Replace YOUR_CLUSTER_NAME with name of your cluster, and YOUR_REGION_CODE with your cluster's AWS Region. Also, replace EKS_CLUSTER_VPC_ID with the cluster's virtual private cloud (VPC) ID.

4. To verify that the controller installed correctly, run the following command:

   kubectl get deployment -n kube-system aws-load-balancer-controller

   Example output:

   NAME                           READY   UP-TO-DATE   AVAILABLE   AGE
   aws-load-balancer-controller   2/2     2            2           84s

Test the AWS Load Balancer Controller

To test your implementation, use the AWS Load Balancer Controller to create one of the following resources:

• An Application Load Balancer for ingress
• A Network Load Balancer where for Service, the Type is LoadBalancer

An ingress resource routes the traffic to different services based on web concepts such as URIs, hostnames, and paths. It's a best practice to use an ingress resource to share a load balancer with multiple services or to control the service routing. Use a Service LoadBalancer to assign a dedicated load balancer to your service.

Note: The following test steps deploy an example game application called 2048.

Create an Application Load Balancer

To create an Application Load Balancer for ingress, complete the following steps:

1. To create the Fargate profile that's required for the game deployment, run the following command:

   eksctl create fargateprofile \
     --cluster YOUR_CLUSTER_NAME \
     --region YOUR_REGION_CODE \
     --name your-alb-sample-app \
     --namespace game-2048

   Note: Replace YOUR_CLUSTER_NAME with name of your cluster and, YOUR_REGION_CODE with your Region.

2. To deploy the application, run the following command:

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

3. Wait a few minutes. Then, run the following command to verify that the AWS Load Balancer Controller created an ingress resource:

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

   Example output:

   NAME         CLASS HOSTS ADDRESS                                                                PORTS AGE
   ingress-2048 alb   *     k8s-game2048-ingress2-xxxxxxxxxx-yyyyyyyyyy.region.elb.amazonaws.com   80    3d4h

   If you don't see an ingress resource 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

   Check the logs for error messages that help you diagnose issues with your deployment.

4. To view the application, open a browser, and then navigate to URL in the ingress resource command output.
   Note: If you don't see the application, then wait a few minutes and refresh your browser.

Create a Network Load Balancer

To deploy an application with the Network Load Balancer IP address mode service, complete the following steps:

1. To create a Fargate profile, run the following command:

   eksctl create fargateprofile --cluster your-cluster --region your-region-code --name your-alb-sample-app --namespace game-2048

   Note: Replace your-cluster with name of your cluster and your-region-code with your cluster's Region.

2. To get the manifest to deploy the 2048 game, run the following command:

   curl -o 2048-game.yaml https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.11.0/docs/examples/2048/2048_full.yaml

3. In the manifest, delete the following Ingress section:

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     namespace: game-2048
     name: ingress-2048
     annotations:
       alb.ingress.kubernetes.io/scheme: internet-facing
       alb.ingress.kubernetes.io/target-type: ip
   spec:
     ingressClassName: alb
     rules:
       - http:
           paths:
             - path: /
               pathType: Prefix
               backend:
                 service:
                   name: service-2048           
                   port:
                     number: 80

4. Modify the Service object to use the following values:

   apiVersion: v1
   kind: Service
   metadata:
     namespace: game-2048
     name: service-2048
     annotations:
       service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: "ip"
       service.beta.kubernetes.io/aws-load-balancer-type: external
       service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing
   spec:
     ports:
       - port: 80
         targetPort: 80
         protocol: TCP
     type: LoadBalancer
     selector:
       app.kubernetes.io/name: app-2048

5. To create the service and deployment manifest, run the following command:

   kubectl apply -f 2048-game.yaml

6. To check for service creation and the DNS name of the Network Load Balancer, run the following command:

   kubectl get svc -n game-2048

   Example output:

   NAME           TYPE           CLUSTER-IP       EXTERNAL-IP                                                               PORT(S)        AGE
   service-2048   LoadBalancer   10.100.114.197   k8s-game2048-service2-xxxxxxxxxx-yyyyyyyyyy.us-east-2.elb.amazonaws.com   80:xxxxx/TCP   23m

7. Wait a few minutes until the load balancer is active. To verify that you can access the deployment, open a web browser. Then, open the fully qualified domain name (FQDN) in the command's output under EXTERNAL-IP.

Troubleshoot the AWS Load Balancer Controller

If you encounter issues when you set up the AWS Load Balancer Controller, then run the following commands:

kubectl logs -n kube-system deployment.apps/aws-load-balancer-controller
kubectl get endpoints -n game-2048
kubectl get ingress/ingress-2048 -n game-2048

Check the output of the logs command for error messages, such as issues with tags or subnets. For troubleshooting steps for common errors, see Issues on the GitHub website. Also, see How can I troubleshoot issues when I use the AWS Load Balancer Controller to create a load balancer?

The get endpoints command shows you whether you correctly registered the backed deployment pods. The get ingress commands shows you whether the ingress resources are deployed.

For more information, see AWS Load Balancer Controller on the Kubernetes website.