Skip to content

installation.md

Latest commit

 

History

History
210 lines (134 loc) · 9.34 KB

installation.md

File metadata and controls

210 lines (134 loc) · 9.34 KB
Raw
title Build NGINX Ingress Controller with F5 WAF for NGINX
weight 100
toc true
nd-content-type how-to
nd-product INGRESS
nd-docs DOCS-579

This document explains how to build a F5 NGINX Ingress Controller image with F5 WAF for NGINX from source code.

{{< call-out "tip" "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. {{< /call-out >}}

Before you start

  • To use F5 WAF for NGINX with NGINX Ingress Controller, you must have NGINX Plus.
  • F5 WAF for NGINX package based installation (previously NGINX App Protect WAF v4) is not supported when readOnlyRootFilesystem is enabled.

Prepare the environment

Get your system ready for building and pushing the NGINX Ingress Controller image with F5 WAF for NGINX.

  1. Sign in to your private registry. Replace <my-docker-registry> with the path to your own private registry.

    docker login <my-docker-registry>

  2. Clone the NGINX Ingress Controller repository:

    git clone https://github.com/nginx/kubernetes-ingress.git --branch v{{< nic-version >}}
cd kubernetes-ingress

Build the image

Follow these steps to build the NGINX Controller Image with F5 WAF for NGINX.

  1. 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

  2. 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 F5 DoS for NGINX, 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]({{< ref "/nic/install/build.md#makefile-details" >}}). This version number is used for tracking and deployment purposes.

{{< call-out "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, add DOCKER_BUILD_OPTIONS="--pull --no-cache" to the make command. {{< /call-out >}}

Makefile targets {#makefile-targets}

Makefile Target Description Compatible Systems
debian-image-nap-plus Builds a Debian-based image with NGINX Plus and the F5 WAF for NGINX module. Debian
debian-image-nap-dos-plus Builds a Debian-based image with NGINX Plus, F5 WAF for NGINX, and F5 DoS for NGINX Debian
ubi-image-nap-plus Builds a UBI-based image with NGINX Plus and the F5 WAF for NGINX module. OpenShift
ubi-image-nap-dos-plus Builds a UBNI-based image with NGINX Plus, F5 WAF for NGINX, and F5 DoS for NGINX. OpenShift

{{< call-out "note" >}} For the complete list of Makefile targets and customizable variables, see the [Build NGINX Ingress Controller]({{< ref "/nic/install/build.md#makefile-details" >}}) topic. {{< /call-out>}}

Push the image to your private registry

Once you've successfully built the NGINX Ingress Controller image with F5 WAF for NGINX, 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) {#set-up-rbac}

{{< include "/nic/rbac/set-up-rbac.md" >}}

Create common resources {#create-common-resources}

{{< include "/nic/installation/create-common-resources.md" >}}

Create core custom resources {#create-custom-resources}

{{< include "/nic/installation/create-custom-resources.md" >}}

Create F5 WAF for NGINX custom resources

{{< call-out "note" >}} If you're using NGINX Ingress Controller with the F5 WAF for NGINX module and policy bundles, you can skip this section. You will need to create and configure Persistent Volume and Persistent Volume Claim in your Kubernetes cluster. {{< /call-out >}}

{{}}

{{%tab name="Install CRDs from single YAML"%}}

This single YAML file creates CRDs for the following resources:

  • APPolicy
  • APLogConf
  • APUserSig
kubectl apply -f https://raw.githubusercontent.com/nginx/kubernetes-ingress/v{{< nic-version >}}/deploy/crds-nap-waf.yaml

{{%/tab%}}

{{%tab name="Install CRDs after cloning the repo"%}}

{{< call-out "note" >}} If you are installing the CRDs this way, ensure you have first cloned the repository. {{< /call-out >}}

These YAML files create CRDs for the following resources:

  • APPolicy
  • APLogConf
  • APUserSig
kubectl apply -f config/crd/bases/appprotect.f5.com_appolicies.yaml
kubectl apply -f config/crd/bases/appprotect.f5.com_aplogconfs.yaml
kubectl apply -f config/crd/bases/appprotect.f5.com_apusersigs.yaml

{{%/tab%}}

{{}}

Deploy NGINX Ingress Controller {#deploy-ingress-controller}

{{< include "/nic/installation/deploy-controller.md" >}}

{{< call-out "note" >}} If you're using NGINX Ingress Controller with the AppProtect WAF module and policy bundles, you will need to modify the Deployment, DaemonSet, or StatefulSet file to include volumes and volume mounts.

NGINX Ingress Controller requires the volume mount path to be /etc/nginx/waf/bundles. {{< /call-out >}}

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/nginx/waf/bundles
...

{{< call-out "note" >}} 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. {{< /call-out >}}

Using a Deployment

{{< include "/nic/installation/manifests/deployment.md" >}}

Using a DaemonSet

{{< include "/nic/installation/manifests/daemonset.md" >}}

Using a StatefulSet

{{< include "/nic/installation/manifests/statefulset.md" >}}

Enable F5 WAF for NGINX module (requires NGINX Plus)

To enable the F5 WAF for NGINX Module:

  • Add the --enable-app-protect [command-line argument]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md#cmdoption-enable-app-protect" >}}) to your Deployment, DaemonSet, or StatefulSet file.

Additional WAF modules can be enabled by adding the appropriate command-line arguments:

  • To enable F5 WAF DoS Protection, add the --enable-app-protect-dos [command-line argument]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md#cmdoption-enable-app-protect-dos" >}}).
  • To enable F5 WAF IP Intelligence, add the --enable-app-protect-ip-intelligence [command-line argument]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md#cmdoption-enable-app-protect-ip-intelligence" >}}).

Confirm NGINX Ingress Controller is running

{{< include "/nic/installation/manifests/verify-pods-are-running.md" >}}

For more information, see the [Configuration guide]({{< ref "/nic/integrations/app-protect-waf/configuration.md" >}}) and the NGINX Ingress Controller with App Protect example resources on GitHub [for VirtualServer resources](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/custom-resources/app-protect-waf) and [for Ingress resources](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/app-protect-waf).

Alternatives to building your own image {#pre-built-images}

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 [Download NGINX Ingress Controller from the F5 Registry]({{< ref "/nic/install/images/registry-download.md" >}}) topic.
  • The [Add an NGINX Ingress Controller image to your cluster]({{< ref "/nic/install/images/add-image-to-cluster.md" >}}) topic describes how to use your subscription JWT token to get the image.