Using NGINX or NGINX Plus as the Ingress Controller for Amazon Elastic Kubernetes Services (original) (raw)

Home
F5 NGINX Plus
Deployment Guides
Amazon Web Services Using NGINX or NGINX Plus as the Ingress Controller for Amazon Elastic Kubernetes Services

This guide explains how to use NGINX Open Source or F5 NGINX Plus with NGINX Ingress Controller for Amazon Elastic Kubernetes Services (EKS).

Note: These instructions apply to NGINX Ingress Controller with NGINX Open Source or NGINX Plus. For ease of reading, the document refers to NGINX Plus only.

These instructions apply to NGINX Ingress Controller with NGINX Open Source or NGINX Plus. For ease of reading, the document refers to NGINX Plus only.

An AWS account.
A prebuilt image of the NGINX or NGINX Plus Ingress Controller for Kubernetes.
- For NGINX Open Source you can use the pre-built image on DockerHub. You can also build your own image.
- For NGINX Plus, you must build an image.

Note: Never upload your NGINX Plus Ingress Controller images to a public repository such as Docker Hub. Doing so violates your license agreement. Run the make container command below.

Never upload your NGINX Plus Ingress Controller images to a public repository such as Docker Hub. Doing so violates your license agreement. Run the make container command below.

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

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

The PREFIX argument specifies the repo name in your private container registry. In this example, we set it to nginx/nginx-plus-ingress. You can later use that name to reference the image instead of its numerical ID.

Create an Amazon EKS Cluster

You can create an Amazon EKS cluster with:

the AWS Management Console
the AWS CLI
the eksctl command line utility.

This guide covers the eksctl command as it is the simplest option.

Follow the instructions in the eksctl.io documentation to install or update the eksctl command.
Create an Amazon EKS cluster by following the instructions in the AWS documentation. Select the Managed nodes – Linux option for each step. Note that the eksctl create cluster command in the first step can take ten minutes or more.

Push the NGINX Plus Ingress Controller Image to AWS ECR

This step is only required if you do not plan to use the prebuilt NGINX Open Source image.

Use the AWS documentation to create a repository in the Amazon Elastic Container Registry (ECR). In Step 4 of the AWS instructions, name the repository nginx-plus-ic as that is what we use in this guide.
Run the following AWS CLI command. It generates an auth token for your AWS ECR registry, then pipes it into the docker login command. This lets AWS ECR authenticate and authorize the upcoming Docker requests. For details about the command, see the AWS documentation.

aws ecr get-login-password --region <aws_region_code> | docker login --username AWS --password-stdin <aws_account_id>.dkr.ecr.<aws_region_code>.amazonaws.com

aws ecr get-login-password --region <aws_region_code> | docker login --username AWS --password-stdin <aws_account_id>.dkr.ecr.<aws_region_code>.amazonaws.com

<aws_region_code> is the same region name you specified in Step 2 above.
<aws_account_id> is your AWS account number. For instructions on retrieving the ID, see the AWS documentation.

Run the following command to apply the tag edge to your NGINX Ingress Controller image:

docker tag <registry/image>:edge <aws_account_id>.dkr.ecr.<aws-region-code>.amazonaws.com/<ecr_repo>:edge

docker tag <registry/image>:edge <aws_account_id>.dkr.ecr.<aws-region-code>.amazonaws.com/<ecr_repo>:edge

<registry/image> is the repo name you set with the PREFIX parameter to the make container command (see Prerequisites). In this guide it is nginx/nginx-plus-ingress.
<ecr_repo> is the AWS ECR repository you created in Step 1 above. In this guide it is called nginx-plus-ic.
The final command is:

docker tag nginx/nginx-plus-ingress:edge <aws_account_id>.dkr.ecr.<aws_region_code>.amazonaws.com/nginx-plus-ic:edge

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

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

Install the NGINX Plus Ingress Controller

Use our documentation to install the NGINX Plus Ingress Controller in your Amazon EKS cluster.

Complete the steps up to and including Confirm NGINX Ingress Controller is running. Next, follow the instructions below to create a Network Load Balancer to route traffic to NGINX Plus Ingress Controller.

Use a Network Load Balancer in front of NGINX Ingress Controller

These steps assume you’ve cloned the kubernetes-ingress repository in the previous step.

You need a Kubernetes LoadBalancer service to route traffic to the NGINX Ingress Controller. By default, Amazon EKS will create a Classic Load Balancer for Kubernetes services of type LoadBalancer. However, we recommend that you create a Network Load Balancer (NLB). It operates at the transport layer and is optimized for high performance and low latency.

We also recommend enabling the PROXY Protocol for both the NGINX Plus Ingress Controller and your NLB target groups. This is used to forward client connection information. If you choose not to enable the PROXY protocol, see the Appendix.

Configure a LoadBalancer Service to Use NLB

Apply the manifest deployments/service/loadbalancer-aws-elb.yaml to create a LoadBalancer of type NLB:

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

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

Enable the PROXY Protocol

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

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

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. This will enable the PROXY protocol for the NGINX Plus Ingress Controller:

kubectl apply -f deployments/common/nginx-config.yaml

kubectl apply -f deployments/common/nginx-config.yaml

Enable the PROXY Protocol for the target groups linked to the NLB. Follow the steps in the Enable proxy protocol section of the AWS documentation to do this.

Get the DNS name of NGINX Ingress Controller with the command below. Find the value of the “LoadBalancer Ingress” in the output.

kubectl describe svc nginx-ingress --namespace=nginx-ingress

kubectl describe svc nginx-ingress --namespace=nginx-ingress

Resolve the DNS name into an IP address using nslookup:
Follow the instructions to deploy the Cafe demo app into the EKS cluster. It will be load balanced by NGINX Ingress Controller.
- In Step 1 of deploying the demo app, save the public IP address into the IC_IP shell variable. Set IC_HTTPS_PORT to 443.
- The kubectl commands are relative to the deployment/examples/ingress-resources/complete-example directory of the kubernetes-ingress repository.
- Run the curl command listed in the instructions. It will access the demo app and populate the NGINX Plus Ingress Controller logs.
Run the following commands to check if the PROXY Protocol is enabled:
1. Display the pod of NGINX Ingress Controller:
```
kubectl get pods -n nginx-ingress  
```
```
kubectl get pods -n nginx-ingress  
```
1. Display the logs from NGINX Ingress Controller. Replace <pod_name> with the name from the previous step. If the logged IP address matches the one you used to access the demo app, then the PROXY Protocol is enabled.
```
kubectl logs <pod_name> -n nginx-ingress  
```
```
kubectl logs <pod_name> -n nginx-ingress  
```

Appendix: Disable the PROXY Protocol

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

Disable the PROXY Protocol for the target groups linked to the NLB. Undo the steps in the Enable proxy protocol section of the AWS documentation.
Remove the following keys from deployments/common/nginx-config.yaml the config map file:
yaml

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

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 deployments/common/nginx-config.yaml

kubectl apply -f deployments/common/nginx-config.yaml

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

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

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 deployments/service/loadbalancer-aws-elb.yaml

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

Version 2 (February 2025) – Initial version (NGINX Plus Release 20)