Using NGINX or NGINX Plus as the Ingress Controller for Amazon Elastic Kubernetes Services

This guide explains how to use the NGINX Open Source or F5 NGINX Plus Ingress Controller for Kubernetes as the Ingress controller for a Kubernetes cluster hosted in the Amazon Elastic Kubernetes Service (EKS).

Note: The instructions in this document apply to both the NGINX and NGINX Plus Ingress Controllers for Kubernetes. For ease of reading, the document refers to NGINX Plus only.

Prerequisites

An AWS account.
A prebuilt image of the NGINX or NGINX Plus Ingress Controller for Kubernetes. For NGINX Open Source, NGINX provides a prebuilt image on DockerHub, or you can build your own with our instructions. For NGINX Plus, you must build an image.

Note: If you build the image, do not push it to a public registry. Run the following make container command. Include the PREFIX argument to specify the repo in your private registry where the container is created; this also sets the name that you can later use to reference the image, instead of its numerical ID. In this example we set it to nginx/nginx-plus-ingress.

make container DOCKERFILE=DockerfileForPlus PREFIX=nginx/nginx-plus-ingress

Creating an Amazon EKS Cluster

In this guide we’re using the eksctl command to create an Amazon EKS cluster (you can also use the AWS Management Console or AWS CLI).

If the eksctl command is not already installed, or to make sure you have the latest version, follow the instructions in the AWS documentation.
Create an Amazon EKS cluster by following the instructions on the eksctl tab in the AWS documentation. In Step 1 of those instructions, use the eksctl create cluster command shown in the Cluster with Linux‑only workloads section.

Pushing the NGINX Plus Ingress Controller Image to AWS ECR

Create a repository in the Amazon Elastic Container Registry (ECR) using the instructions in the AWS documentation. In this guide, we name the repository nginx-plus-ic in Step 5 of the AWS instructions.
Run the following AWS CLI command. It generates an authorization token for your AWS ECR registry and outputs the docker login command for logging into the registry. For details about the command, see the AWS documentation.
```
aws ecr get-login --no-include-email --region <aws_region_code>
```
Run the docker login command generated in Step 2.
Run the following command to apply the tag edge to your NGINX Plus Ingress Controller image, where:
- <registry/image> is the value you specified with the PREFIX parameter to the make container command you ran to create the NGINX Plus Ingress Controller image (see Prerequisites). In this guide it is nginx/nginx-plus-ingress.
- <aws_account_id> is your AWS account number. For instructions on retrieving the ID, see the AWS documentation.
- <aws_region_code> is the same region name you specified in Step 2 above.
- <ecr_repo> is the AWS ECR repository you created in Step 1 above. In this guide it is called nginx-plus-ic.
```
docker tag <registry/image>:edge <aws_account_id>.dkr.ecr.<aws-region-code>.amazonaws.com/<ecr_repo>:edge
```
So in this guide, the command is
```
docker tag nginx/nginx-plus-ingress:edge <aws_account_id>.dkr.ecr.<aws_region_code>.amazonaws.com/nginx-plus-ic:edge
```

Push the NGINX Plus Ingress Controller image to AWS ECR:

docker push <aws_account_id>.dkr.ecr.<aws_region_code>.amazonaws.com/<ecr_repo>:edge

Installing the NGINX Plus Ingress Controller

Install your NGINX Plus Ingress Controller image in the Amazon EKS cluster you created in Creating an Amazon EKS Cluster, using the instructions in our documentation.

Using NLB in Front of the NGINX Plus Ingress Controller

By default, Amazon EKS uses Classic Load Balancer for Kubernetes services of type LoadBalancer. We recommend that you use Network Load Balancer (NLB) instead, and this section provides instructions for configuring it. We also recommend that you enable the PROXY Protocol for both the NGINX Plus Ingress Controller and your NLB target groups. If you choose not to enable the PROXY protocol, see the Appendix.

We assume you performed all the steps in the instructions referenced in Installing the NGINX Plus Ingress Controller, and built a service for your NGINX Plus Ingress Controller. If you created a LoadBalancer service, you can either edit its configuration or add a new LoadBalancer service. If you created a NodePort service, you must add a new LoadBalancer service now.

Configuring a `LoadBalancer` Service to Use NLB

In service/loadbalancer-aws-elb.yaml, add the following annotation to the existing or new LoadBalancer service:
```
service.beta.kubernetes.io/aws-load-balancer-type: nlb
```

Run the following command:

kubectl apply -f service/loadbalancer-aws-elb.yaml

Enabling the PROXY Protocol

Add the following keys to the common/nginx-config.yaml config map file:

proxy-protocol: "True"
real-ip-header: "proxy_protocol"
set-real-ip-from: "0.0.0.0/0"

Run the following command to update the config map:
```
kubectl apply -f common/nginx-config.yaml
```
Enable the PROXY Protocol on the target group associated with the NLB created for your LoadBalancer service, by performing the steps in the Enable Proxy Protocol section of the AWS documentation.

Testing

Follow the instructions for setting up our sample deployment of a demo app load balanced by the NGINX Plus Ingress controller.
Navigate in a browser to http://cafe.example.com/coffee (or issue the curl command against that URL).
Run the following command to display the name of the running Ingress pod:
```
kubectl get pods -namespace=nginx-ingress
```
Run the following command to display the logs from the NGINX Plus Ingress Controller, where <pod_name> is the name you learned in the previous step. If the logged IP address matches the IP address from which you accessed http://cafe .example.com/coffee, the PROXY Protocol is enabled.
```
kubectl logs nginx-ingress-<pod_name> -n nginx-ingress
```

Appendix: Disabling the PROXY Protocol

If you choose to disable the PROXY Protocol, perform these steps.

If the common/nginx-config.yaml config map file includes these keys, remove them:

proxy-protocol: "True"
real-ip-header: "proxy_protocol"
set-real-ip-from: "0.0.0.0/0"

Run the following command to update the config map:
```
kubectl apply -f common/nginx-config.yaml
```

In the service/loadbalancer-aws-elb.yaml service file, add the externalTrafficPolicy key in the spec section and set it to Local, as in this example:

apiVersion: v1
kind: Service
metadata:
 name: nginx-ingress-nlb
 namespace: nginx-ingress
 annotations:
   service.beta.kubernetes.io/aws-load-balancer-backend-protocol: "tcp"
   service.beta.kubernetes.io/aws-load-balancer-proxy-protocol: "*"
   service.beta.kubernetes.io/aws-load-balancer-type: nlb
spec:
   externalTrafficPolicy: Local
   type: LoadBalancer
   ports:
   - port: 80
     targetPort: 80
     protocol: TCP
     name: http
   - port: 443
     targetPort: 443
     protocol: TCP
     name: https
   selector:
     app: nginx-ingress

Run the following command to update the service:

kubectl apply -f service/loadbalancer-aws-elb.yaml

Revision History

Version 1 (March 2020) – Initial version (NGINX Plus Release 20)

Last modified August 22, 2024