Building NGINX Ingress Controller with NGINX App Protect DoS
This document explains how to build an image for NGINX Ingress Controller with the NGINX App Protect DoS from source code.
Pre-built image alternatives
If you’d rather not build your own NGINX Ingress Controller image, see the pre-built image options at the end of this guide.
Before you start
- To use NGINX App Protect DoS with NGINX Ingress Controller, you must have NGINX Plus.
Prepare the environment
Get your system ready for building and pushing the NGINX Ingress Controller image with NGINX App Protect DoS.
-
Sign in to your private registry. Replace
<my-docker-registry>
with the path to your own private registry.docker login <my-docker-registry>
-
Clone the NGINX Ingress Controller GitHub repository. Replace
<version_number>
with the version of NGINX Ingress Controller you want.git clone https://github.com/nginxinc/kubernetes-ingress.git --branch <version_number> cd kubernetes-ingress
For instance if you want to clone version v3.3.2, the commands to run would be:
git clone https://github.com/nginxinc/kubernetes-ingress.git --branch v3.3.2 cd kubernetes-ingress/deployments
Build the image
Follow these steps to build the NGINX Controller Image with NGINX App Protect DoS.
-
Place your NGINX Plus license files (nginx-repo.crt and nginx-repo.key) in the project’s root folder. To verify they’re in place, run:
ls nginx-repo.*
You should see:
nginx-repo.crt nginx-repo.key
-
Build the image. Replace
<makefile target>
with your chosen build option and<my-docker-registry>
with your private registry’s path. Refer to the Makefile targets table below for the list of build options.make <makefile target> PREFIX=<my-docker-registry>/nginx-plus-ingress TARGET=download
For example, to build a Debian-based image with NGINX Plus and NGINX App Protect DoS, run:
make debian-image-dos-plus PREFIX=<my-docker-registry>/nginx-plus-ingress TARGET=download
What to expect: The image is built and tagged with a version number, which is derived from the
VERSION
variable in the Makefile. This version number is used for tracking and deployment purposes.
Note:
In the event a patch version of NGINX Plus is released, make sure to rebuild your image to get the latest version. If your system is caching the Docker layers and not updating the packages, addDOCKER_BUILD_OPTIONS="--pull --no-cache"
to the make command.
Makefile targets
Makefile Target | Description | Compatible Systems |
---|---|---|
debian-image-dos-plus | Builds a Debian-based image with NGINX Plus and the NGINX App Protect DoS module. | Debian |
debian-image-nap-dos-plus | Builds a Debian-based image with NGINX Plus, NGINX App Protect DoS, and NGINX App Protect WAF. | Debian |
ubi-image-dos-plus | Builds a UBI-based image with NGINX Plus and the NGINX App Protect DoS module. | OpenShift |
ubi-image-nap-dos-plus | Builds a UBI-based image with NGINX Plus, NGINX App Protect DoS, and NGINX App Protect WAF. | OpenShift |
See Also:
For the complete list of Makefile targets and customizable variables, see the Building NGINX Ingress Controller guide
Push the image to your private registry
Once you’ve successfully built the NGINX Ingress Controller image with NGINX App Protect DoS, the next step is to upload it to your private Docker registry. This makes the image available for deployment to your Kubernetes cluster.
To upload the image, run the following command. If you’re using a custom tag, add TAG=your-tag
to the end of the command. Replace <my-docker-registry>
with your private registry’s path.
make push PREFIX=<my-docker-registry>/nginx-plus-ingress
Set up role-based access control (RBAC)
Admin access required
To complete these steps you need admin access to your cluster. Refer to to your Kubernetes platform’s documentation to set up admin access. For Google Kubernetes Engine (GKE), you can refer to their Role-Based Access Control guide.
-
Create a namespace and a service account:
kubectl apply -f common/ns-and-sa.yaml
-
Create a cluster role and binding for the service account:
kubectl apply -f rbac/rbac.yaml
If you’re planning to use NGINX App Protect or NGINX App Protect DoS, additional roles and bindings are needed.
-
(NGINX App Protect only) Create the App Protect role and binding:
kubectl apply -f rbac/ap-rbac.yaml
-
(NGINX App Protect DoS only) Create the App Protect DoS role and binding:
kubectl apply -f rbac/apdos-rbac.yaml
Create common resources
In this section, you’ll create resources that most NGINX Ingress Controller installations require:
-
(Optional) Create a secret for the default NGINX server’s TLS certificate and key. Complete this step only if you’re using the default server TLS secret command-line argument. If you’re not, feel free to skip this step.
By default, the server returns a 404 Not Found page for all requests when no ingress rules are set up. Although we provide a self-signed certificate and key for testing purposes, we recommend using your own certificate.
To begin, make sure you’re in the
kubernetes-ingress/deployment
directory, and then run:kubectl apply -f ../examples/shared-examples/default-server-secret/default-server-secret.yaml
-
Create a ConfigMap to customize your NGINX settings:
kubectl apply -f common/nginx-config.yaml
-
Create an
IngressClass
resource. NGINX Ingress Controller won’t start without anIngressClass
resource.kubectl apply -f common/ingress-class.yaml
If you want to make this NGINX Ingress Controller instance your cluster’s default, uncomment the
ingressclass.kubernetes.io/is-default-class
annotation. This action will auto-assignIngressClass
to new ingresses that don’t specify aningressClassName
.
Deploy NGINX Ingress Controller
You have two options for deploying NGINX Ingress Controller:
- Deployment. Choose this method for the flexibility to dynamically change the number of NGINX Ingress Controller replicas.
- DaemonSet. Choose this method if you want NGINX Ingress Controller to run on all nodes or a subset of nodes.
Before you start, update the command-line arguments for the NGINX Ingress Controller container in the relevant manifest file to meet your specific requirements.
Using a Deployment
For additional context on managing containers using Kubernetes Deployments, refer to the official Kubernetes Deployments documentation.
When you deploy NGINX Ingress Controller as a Deployment, Kubernetes automatically sets up a single NGINX Ingress Controller pod.
-
For NGINX, run:
kubectl apply -f deployment/nginx-ingress.yaml
-
For NGINX Plus, run:
kubectl apply -f deployment/nginx-plus-ingress.yaml
Update the
nginx-plus-ingress.yaml
file to include your chosen image from the F5 Container registry or your custom container image.
Using a DaemonSet
For additional context on managing containers using Kubernetes DaemonSets, refer to the official Kubernetes DaemonSets documentation.
When you deploy NGINX Ingress Controller as a DaemonSet, Kubernetes creates an Ingress Controller pod on every node in the cluster.
-
For NGINX, run:
kubectl apply -f daemon-set/nginx-ingress.yaml
-
For NGINX Plus, run:
kubectl apply -f daemon-set/nginx-plus-ingress.yaml
Update the
nginx-plus-ingress.yaml
file to include your chosen image from the F5 Container registry or your custom container image.
Install the App Protect DoS Arbitrator
Helm Chart
The App Protect DoS Arbitrator can be installed using the NGINX App Protect DoS Helm Chart. If you have the NGINX Helm Repository already added, you can install the App Protect DoS Arbitrator by running the following command:
helm install my-release-dos nginx-stable/nginx-appprotect-dos-arbitrator
YAML Manifests
Alternatively, you can install the App Protect DoS Arbitrator using the YAML manifests provided in the NGINX Ingress Controller repo.
-
Create the namespace and service account:
kubectl apply -f common/ns-and-sa.yaml
-
Deploy the NGINX App Protect Arbitrator as a Deployment and service:
kubectl apply -f deployment/appprotect-dos-arb.yaml kubectl apply -f service/appprotect-dos-arb-svc.yaml
Enable NGINX App Protect DoS module
To enable the NGINX App Protect DoS Module:
- Add the
enable-app-protect-dos
command-line argument to your Deployment or DaemonSet file.
Confirm NGINX Ingress Controller is running
To confirm the NGINX Ingress Controller pods are operational, run:
kubectl get pods --namespace=nginx-ingress
For more information, see the Configuration guide,the NGINX Ingress Controller with App Protect DoS example for VirtualServer and the NGINX Ingress Controller with App Protect DoS example for Ingress.
Alternatives to building your own image
If you prefer not to build your own NGINX Ingress Controller image, you can use pre-built images. Here are your options:
- Download the image using your NGINX Ingress Controller subscription certificate and key. See the Getting the F5 Registry NGINX Ingress Controller Image guide.
- Use your NGINX Ingress Controller subscription JWT token to get the image: Instructions are in Getting the NGINX Ingress Controller Image with JWT.