Build NGINX Ingress Controller with F5 WAF for NGINX

Read the steps outlined in Upgrade from 3.x to 4.x before running the CRD upgrade and perform the steps if applicable.

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

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 F5 WAF for NGINX features. 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 F5 WAF for NGINX v5.

Your Helm values should look something like this:

controller:
  ...
  ## Support for F5 WAF for NGINX
  appprotect:
    ## Enable the F5 WAF for NGINX module in the Ingress Controller.
    enable: true
    ## Enables F5 WAF for NGINX 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>
...

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:

Copy

...
controller:
  ...
  appprotect:
  ...
   volumes:
   - name: app-protect-bundles
     emptyDir: {}
...

Configuring readOnlyRootFilesystem

Create required volumes:

volumes:
  - name: nginx-etc
    emptyDir: {}
  - name: nginx-cache # do not set this value in statefulset if volumeclaimtemplate is set
    emptyDir: {}      # do not set this value in statefulset if volumeclaimtemplate is set
  - name: nginx-lib
    emptyDir: {}
  - name: nginx-log
    emptyDir: {}
  - name: app-protect-bd-config
    emptyDir: {}
  - name: app-protect-config
    emptyDir: {}
  - name: app-protect-bundles
    emptyDir: {}

Set controller.securityContext.readOnlyRootFilesystem to true.

Example Helm values:

controller:
  ...
  securityContext:
    readOnlyRootFilesystem: true
  ...

Set controller.appprotect.enforcer.securityContext.readOnlyRootFilesystem to true.

Example Helm values:

controller:
  ...
  appprotect:
    ...
    enforcer:
      securityContext:
        readOnlyRootFilesystem: true
  ...

Set controller.appprotect.configManager.securityContext.readOnlyRootFilesystem to true.

Example Helm values:

controller:
  ...
  appprotect:
    ...
    configManager:
      securityContext:
        readOnlyRootFilesystem: true
  ...

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.
• StatefulSet. Choose this method when you need stable, persistent storage and ordered deployment/scaling for your NGINX Ingress Controller pods.

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.

1. Create a namespace and a service account:

   Copy

   kubectl apply -f deployments/common/ns-and-sa.yaml

2. Create a cluster role and binding for the service account:

   Copy

   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"
    - name: ENFORCER_CONFIG_TIMEOUT
      value: "0"
  volumeMounts:
    - name: app-protect-bd-config
      mountPath: /opt/app_protect/bd_config
...

Update NIC container in deployment, daemonset, or statefulset

Add volumeMounts as below:

...
- image: <my_docker_registry>:<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
...

Configure readOnlyRootFilesystem

Add readOnlyRootFilesystem to the NIC container and set valut to true as below:

...
- image: <my_docker_registry>:<version_tag>
  imagePullPolicy: IfNotPresent
  name: nginx-plus-ingress
  ...
  securityContext:
    allowPrivilegeEscalation: false
      capabilities:
        add:
        - NET_BIND_SERVICE
        drop:
        - ALL
      readOnlyRootFilesystem: true
      runAsNonRoot: true
      runAsUser: 101
    readOnlyRootFilesystem: true
  ...
  volumeMounts:
    - mountPath: /etc/nginx
      name: nginx-etc
    - mountPath: /var/cache/nginx
      name: nginx-cache
    - mountPath: /var/lib/nginx
      name: nginx-lib
    - mountPath: /var/log/nginx
      name: nginx-log
    - mountPath: /opt/app_protect/bd_config
      name: app-protect-bd-config
    - mountPath: /opt/app_protect/config
      name: app-protect-config
    - mountPath: /etc/app_protect/bundles
      name: app-protect-bundles
...

Add readOnlyRootFilesystem to the waf-config-mgr container and set value to true as below:

...
- name: waf-config-mgr
  image: private-registry.nginx.com/nap/waf-config-mgr:<version-tag>
  imagePullPolicy: IfNotPresent
  ...
  securityContext:
    readOnlyRootFilesystem: true
    ...
...

Add readOnlyRootFilesystem to the waf-enforcer container and set value to true as below:

...
- name: waf-enforcer
  image: private-registry.nginx.com/nap/waf-enforcer:<version-tag>
  imagePullPolicy: IfNotPresent
  ...
  securityContext:
    readOnlyRootFilesystem: true
    ...
...

StatefulSet Volume Configuration: When using StatefulSet deployments, the nginx-cache volume is automatically provided via volumeClaimTemplates for persistent storage. F5 WAF for NGINX v5 volumes (like app-protect-config, app-protect-bundles) are still configured as regular volumes in the volumes section. Use emptyDir for temporary data or PersistentVolumeClaims if you need persistence for App Protect configurations across pod restarts.

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:

  Copy

  kubectl apply -f deployments/deployment/nginx-ingress.yaml

• For NGINX Plus, run:

  Copy

  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:

  Copy

  kubectl apply -f deployments/daemon-set/nginx-ingress.yaml

• For NGINX Plus, run:

  Copy

  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.

Using a StatefulSet

For additional context on managing containers using Kubernetes StatefulSets, refer to the official Kubernetes StatefulSets documentation.

When you deploy NGINX Ingress Controller as a StatefulSet, Kubernetes creates pods with stable network identities and persistent storage.

• For NGINX, run:

  Copy

  kubectl apply -f deployments/stateful-set/nginx-ingress.yaml

• For NGINX Plus, run:

  Copy

  kubectl apply -f deployments/stateful-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.

StatefulSets include persistent volume claims for nginx cache storage via volumeClaimTemplates. You may need to configure a StorageClass in your cluster or modify the volumeClaimTemplates section in the manifest to match your storage requirements. Other volumes (like those needed for App Protect modules) are configured in the regular volumes section, not in volumeClaimTemplates.

Enable F5 WAF for NGINX module

To enable the F5 DoS for NGINX Module:

• Add the enable-app-protect command-line argument to your Deployment, DaemonSet, or StatefulSet file.