How do I set up the ALB Ingress Controller on an Amazon EC2 node group in Amazon EKS?

Last updated: 2021-01-08

I want to set up the Application Load Balancer (ALB) Ingress Controller on an Amazon Elastic Compute Cloud (Amazon EC2) node group in Amazon Elastic Kubernetes Service (Amazon EKS).

Short description

The following steps show you how to deploy the AWS Load Balancer Controller on an Amazon EC2 node group in Amazon EKS.

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

Resolution

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: If you're using eksctl to create an IAM role, 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) 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 -o ingress-controller.yaml https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/$VERSION/docs/install/v2_1_0_full.yaml

Note: Replace $VERSION with the version (from the Kubernetes SIGs GitHub site) 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 an 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) 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, 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) of the AWS Load Balancer Controller that you want to deploy.


Did this article help?


Do you need billing or technical support?