Build NGINX Ingress Controller with NGINX App Protect WAF v5
This document explains how to build a F5 NGINX Ingress Controller image with F5 NGINX App Protect WAF v5 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 WAF 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 WAF v5.
-
Sign in to your private registry. Replace
<my-docker-registry>
with the path to your own private registry.docker login <my-docker-registry>
-
Pull the WAF Config Manager image:
docker pull private-registry.nginx.com/nap/waf-config-mgr:<image-tag>
-
Pull the WAF Enforcer Docker image
docker pull private-registry.nginx.com/nap/waf-enforcer:<image-tag>
-
Clone the NGINX Ingress Controller repository:
git clone https://github.com/nginxinc/kubernetes-ingress.git --branch v3.7.2 cd kubernetes-ingress
Build the image
Follow these steps to build the NGINX Controller Image with NGINX App Protect WAF v5.
-
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 WAF v5, run:
make debian-image-nap-v5-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 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
Create Docker image for NGINX Ingress Controller (Alpine with NGINX Plus, NGINX App Protect WAF v5 and FIPS)
Makefile Target | Description | Compatible Systems |
---|---|---|
alpine-image-nap-v5-plus-fips | Builds a Alpine-based image with NGINX Plus and the NGINX App Protect WAF v5 module with FIPS. | Alpine |
debian-image-nap-v5-plus | Builds a Debian-based image with NGINX Plus and the NGINX App Protect WAF v5 module. | Debian |
ubi-image-nap-v5-plus | Builds a UBI-based image with NGINX Plus and the NGINX App Protect WAF v5 module. | OpenShift |
ubi-image-nap-dos-v5-plus | Builds a UBI-based image with NGINX Plus, NGINX App Protect WAF v5, and NGINX App Protect DoS. | OpenShift |
See Also:
For the complete list of Makefile targets and customizable variables, see the Build NGINX Ingress Controller guide.
If you intend to use external references in NGINX App Protect WAF policies, you may want to provide a custom CA certificate to authenticate with the hosting server.
To do so, place the *.crt
file in the build folder and uncomment the lines following this comment:
#Uncomment the lines below if you want to install a custom CA certificate
Warning:
External references are deprecated in NGINX Ingress Controller and will not be supported in future releases.
Push the images to your private registry
Once you’ve successfully pulled the WAF v5 manager and enforcer images and built the NGINX Ingress Controller image with NGINX App Protect WAF v5, the next step is to upload them 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
To upload the WAF config manager and enforcer images run the following commands:
docker push <my-docker-registry>/waf-config-mgr:<your-tag>
docker push <my-docker-registry>/waf-enforcer:<your-tag>
To make sure your NGINX Ingress Controller pods reach the Ready
state, you’ll need to create custom resource definitions (CRDs) for various components.
Alternatively, you can disable this requirement by setting the -enable-custom-resources
command-line argument to false
.
There are two ways you can install the custom resource definitions:
- Using a URL to apply a single CRD yaml file, which we recommend.
- Applying your local copy of the CRD yaml files, which requires you to clone the repository.
The core custom CRDs are the following:
kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.7.2/deploy/crds.yaml
Note:
If you are installing the CRDs this way, ensure you have first cloned the repository.
kubectl apply -f config/crd/bases/k8s.nginx.org_virtualservers.yaml
kubectl apply -f config/crd/bases/k8s.nginx.org_virtualserverroutes.yaml
kubectl apply -f config/crd/bases/k8s.nginx.org_transportservers.yaml
kubectl apply -f config/crd/bases/k8s.nginx.org_policies.yaml
kubectl apply -f config/crd/bases/k8s.nginx.org_globalconfigurations.yaml
Deploy NGINX Ingress Controller
Important:
NGINX Ingress Controller with the AppProtect WAF v5 module works only with policy bundles. You need to modify the Deployment or DaemonSet file to include volumes, volume mounts and two WAF 5 docker images:
waf-config-mgr
andwaf-enforcer
.NGINX Ingress Controller requires the volume mount path to be
/etc/app_protect/bundles
.
Below are examples of a PersistentVolume
and PersistentVolumeClaim
that you can reference in your Helm values:
...
volumes:
- name: <volume_name>
persistentVolumeClaim:
claimName: <claim_name>
...
Add volume mounts to the containers
section:
...
volumeMounts:
- name: <volume_mount_name>
mountPath: /etc/app_protect/bundles
...
Enabling WAF v5
Start by setting controller.appprotect.enable
to true
in your Helm values. This will the standard App Protect WAF fetatures.
Afterwords, set controller.approtect.v5
to true
.
This ensures that both the waf-enforcer
and waf-config-mgr
containers are deployed alongside the NGINX Ingress Controller containers.
These two additional containers are required when using App Protect WAF v5.
Your Helm values should look something like this:
controller:
...
## Support for App Protect WAF
appprotect:
## Enable the App Protect WAF module in the Ingress Controller.
enable: true
## Enables App Protect WAF v5.
v5: true
Configuring volumes
Whether you have created a new PersistentVolume
and PersistentVolumeClaim
, or you are referencing an existing PersistentVolumeClaim
, update the app-protect-bundles
volume to reference your PersistentVolumeClaim
.
Example helm values:
...
controller:
...
appprotect:
...
volumes:
- name: app-protect-bundles
persistentVolumeClaim:
claimName: <my_claim_name>
...
Note:
By default,
emptyDir
mounts are used. Bundles that are added to these kind of volume mounts will NOT persist across pod restarts.Example default volumes:
... controller: ... appprotect: ... volumes: - name: app-protect-bundles emptyDir: {} ...
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.
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 deployments/common/ns-and-sa.yaml
-
Create a cluster role and binding for the service account:
kubectl apply -f deployments/rbac/rbac.yaml
Volumes and VolumeMounts
Add a volumes
section to deployment template spec:
...
volumes:
- name: <volume_name>
persistentVolumeClaim:
claimName: <claim_name>
...
Add volume mounts to the containers
section:
...
volumeMounts:
- name: <volume_mount_name>
mountPath: /etc/app_protect/bundles
...
WAF Config Manager and WAF Enforcer
Add waf-config-mgr
image to the containers
section:
...
- name: waf-config-mgr
image: private-registry.nginx.com/nap/waf-config-mgr:<version-tag>
imagePullPolicy: IfNotPresent
securityContext:
allowPrivilegeEscalation: false
capabilities:
drop:
- all
volumeMounts:
- name: app-protect-bd-config
mountPath: /opt/app_protect/bd_config
- name: app-protect-config
mountPath: /opt/app_protect/config
- name: app-protect-bundles
mountPath: /etc/app_protect/bundles
...
Add waf-enforcer
image to the containers
section:
...
- name: waf-enforcer
image: private-registry.nginx.com/nap/waf-enforcer:<version-tag>
imagePullPolicy: IfNotPresent
env:
- name: ENFORCER_PORT
value: "50000"
volumeMounts:
- name: app-protect-bd-config
mountPath: /opt/app_protect/bd_config
...
Update NIC container in deployment or daemonset
Add volumeMounts
as below:
...
- image: <my_docker_registery>:<version_tag>
imagePullPolicy: IfNotPresent
name: nginx-plus-ingress
volumeMounts:
- name: app-protect-bd-config
mountPath: /opt/app_protect/bd_config
- name: app-protect-config
mountPath: /opt/app_protect/config
- name: app-protect-bundles
mountPath: /etc/app_protect/bundles
...
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 deployments/deployment/nginx-ingress.yaml
-
For NGINX Plus, run:
kubectl apply -f deployments/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 deployments/daemon-set/nginx-ingress.yaml
-
For NGINX Plus, run:
kubectl apply -f deployments/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.
Enable NGINX App Protect WAF module
To enable the NGINX App Protect DoS Module:
- Add the
enable-app-protect
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 and the NGINX Ingress Controller with App Protect version 5 example resources on GitHub for VirtualServer resources.
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. View the Get NGINX Ingress Controller from the F5 Registry topic.
- The Get the NGINX Ingress Controller image with JWT topic describes how to use your subscription JWT token to get the image.
NGINX App Protect WAF v5 version
NIC Version | App Protect WAFv5 Version | Config Manager | Enforcer |
---|---|---|---|
3.7.2 | 32_5.144 | 5.3.0 | 5.3.0 |
3.6.2 | 32_5.48 | 5.2.0 | 5.2.0 |
Note:
F5 recommends to re-compile your NGINX AppProtect WAF Policy Bundles with each release of NGINX Ingress Controller. This will ensure your Policies remain compatible and are compiled with the latest Attack Signatures, Bot Signatures, and Threat Campaigns.