nginx · ADubhlaoich · Dec 13, 2023 · Nov 30, 2023 · Nov 30, 2023 · Nov 30, 2023
@@ -0,0 +1,10 @@
+---
+docs:
+---
+
+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]({{< relref "configuration/global-configuration/command-line-arguments.md" >}}) for the NGINX Ingress Controller container in the relevant manifest file to meet your specific requirements.
@@ -118,12 +118,7 @@ make push PREFIX=<my-docker-registry>/nginx-plus-ingress
 
 ## Deploy NGINX Ingress Controller {#deploy-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]({{< relref "configuration/global-configuration/command-line-arguments.md" >}}) for the NGINX Ingress Controller container in the relevant manifest file to meet your specific requirements.
+{{< include "installation/deploy-controller.md" >}}
 
 ### Using a Deployment
 

@@ -1,68 +1,153 @@
 ---
-title: Installation with NGINX App Protect WAF
-description: "This document provides an overview of the steps required to use NGINX App Protect WAF with your NGINX Ingress Controller deployment."
+title: Building NGINX Ingress Controller with NGINX App Protect WAF
+description: "This document explains how to build a F5 NGINX Ingress Controller image with F5 NGINX App Protect WAF from source code."
 weight: 1800
 doctypes: [""]
 toc: true
 docs: "DOCS-579"
 aliases: ["/app-protect/installation/"]
 ---
 
-> **Note**: The NGINX Kubernetes Ingress Controller integration with NGINX App Protect WAF requires the use of NGINX Plus.
+{{< custom-styles >}}
 
-This document provides an overview of the steps required to use NGINX App Protect WAF with your NGINX Ingress Controller deployment. You can visit the linked documents to find additional information and instructions.
+{{<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](#pre-built-images) at the end of this guide.{{</call-out>}}
 
-You can also [install the Ingress Controller with App Protect WAF by using Helm]({{< relref "installation/installing-nic/installation-with-helm.md" >}}). Use the `controller.appprotect.*` parameters of the chart.
+## Before you start
 
-## Prerequisites
+- To use NGINX App Protect WAF with NGINX Ingress Controller, you must have NGINX Plus.
 
-1. Make sure you have access to the Ingress Controller image:
-    - For NGINX Plus Ingress Controller, see [here]({{< relref "installation/nic-images/pulling-ingress-controller-image" >}}) for details on how to pull the image from the F5 Docker registry.
-    - To pull from the F5 Container registry in your Kubernetes cluster, configure a docker registry secret using your JWT token from the MyF5 portal by following the instructions from [here]({{< relref "installation/nic-images/using-the-jwt-token-docker-secret" >}}).
-    - It is also possible to build your own image and push it to your private Docker registry by following the instructions from [here]({{< relref "installation/building-nginx-ingress-controller.md" >}})).
-2. Clone the Ingress Controller repo:
+## Prepare the environment
 
-    ```console
+Get your system ready for building and pushing the NGINX Ingress Controller image with NGINX App Protect WAF.
+
+1. Sign in to your private registry. Replace `<my-docker-registry>` with the path to your own private registry.
+
+    ```shell
+    docker login <my-docker-registry>
+    ```
+
+1. Clone the NGINX Ingress Controller repository:
+
+    ```shell
     git clone https://github.com/nginxinc/kubernetes-ingress.git --branch v3.3.2
     cd kubernetes-ingress
     ```
 
-## Build the Docker Image
+---
 
-Take the steps below to create the Docker image that you'll use to deploy NGINX Ingress Controller with App Protect in Kubernetes.
+## Build the image
 
-- [Build the NGINX Ingress Controller image]({{< relref "installation/building-nginx-ingress-controller.md" >}})).
+Follow these steps to build the NGINX Controller Image with NGINX App Protect WAF.
 
-    When running the `make` command to build the image, be sure to use the `debian-image-nap-plus` target. For example:
+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:
 
-    ```console
-    make debian-image-nap-plus PREFIX=<your Docker registry domain>/nginx-plus-ingress
+    ```shell
+    ls nginx-repo.*
     ```
 
-    Alternatively, if you want to run on an [OpenShift](https://www.openshift.com/) cluster, you can use the `ubi-image-nap-plus` target.
+    You should see:
 
-    If you want to include the App Protect DoS module in the image, you can use the `debian-image-nap-dos-plus` target or the `ubi-image-nap-dos-plus` target for OpenShift.
+    ```shell
+    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](#makefile-targets) table below for the list of build options.
+
+    ```shell
+    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:
+
+    ```shell
+    make debian-image-dos-plus PREFIX=<my-docker-registry>/nginx-plus-ingress TARGET=download
+    ```
 
-    If you intend to use [external references](https://docs.nginx.com/nginx-app-protect/configuration/#external-references) in NGINX App Protect WAF policies, you may want to provide a custom CA certificate to authenticate with the hosting server.
-    In order to do so, place the `*.crt` file in the build folder and uncomment the lines that follow this comment:
-    `#Uncomment the lines below if you want to install a custom CA certificate`
+     **What to expect**: The image is built and tagged with a version number, which is derived from the `VERSION` variable in the [_Makefile_]({{< relref "installation/building-nginx-ingress-controller.md#makefile-details" >}}). This version number is used for tracking and deployment purposes.
 
-     > **Note**: [External References](/nginx-app-protect/configuration-guide/configuration/#external-references) in the Ingress Controller are deprecated and will not be supported in future releases.
+{{<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. {{</note>}}
 
-    **Note**: In the event of a patch version of NGINX Plus being [released](/nginx/releases/), make sure to rebuild your image to get the latest version. The Dockerfile will use the latest available version of the [Attack Signatures](/nginx-app-protect/configuration/#attack-signatures) and [Threat Campaigns](/nginx-app-protect/configuration/#threat-campaigns) packages at the time of build. If your system is caching the Docker layers and not updating the packages, add `DOCKER_BUILD_OPTIONS="--no-cache"` to the `make` command.
+### Makefile targets {#makefile-targets}
 
-- [Push the image to your local Docker registry]({{< relref "installation/building-nginx-ingress-controller.md#build-image-push-to-private-repo" >}}.
+{{<bootstrap-table "table table-striped table-bordered">}}
+| Makefile Target           | Description                                                       | Compatible Systems  |
+|---------------------------|-------------------------------------------------------------------|---------------------|
+| **debian-image-nap-plus** | Builds a Debian-based image with NGINX Plus and the [NGINX App Protect WAF](/nginx-app-protect-waf/) module. | Debian  |
+| **debian-image-nap-dos-plus** | Builds a Debian-based image with NGINX Plus, [NGINX App Protect WAF](/nginx-app-protect-waf/), and [NGINX App Protect DoS](/nginx-app-protect-dos/) | Debian  |
+| **ubi-image-nap-plus**    | Builds a UBI-based image with NGINX Plus and the [NGINX App Protect WAF](/nginx-app-protect-waf/) module. | OpenShift |
+| **ubi-image-nap-dos-plus** | Builds a UBNI-based image with NGINX Plus, [NGINX App Protect WAF](/nginx-app-protect-waf/), and [NGINX App Protect DoS](/nginx-app-protect-dos/). | OpenShift |
+{{</bootstrap-table>}}
 
-## Install the Ingress Controller
+<br>
+
+{{<see-also>}} For the complete list of _Makefile_ targets and customizable variables, see the [Building NGINX Ingress Controller]({{< relref "installation/building-nginx-ingress-controller.md#makefile-details" >}}) guide. {{</see-also>}}
+
+If you intend to use [external references](/nginx-app-protect-waf/configuration/#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. {{</warning>}}
+
+---
+
+## Push the image to your private registry
+
+Once you've successfully built the NGINX Ingress Controller image with NGINX App Protect WAF, 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.
+
+```shell
+make push PREFIX=<my-docker-registry>/nginx-plus-ingress
+```
+
+---
 
-Take the steps below to set up and deploy the NGINX Ingress Controller and App Protect WAF module in your Kubernetes cluster.
+## Set up role-based access control (RBAC) {#set-up-rbac}
 
-1. [Configure role-based access control (RBAC)]({{< relref "installation/installing-nic/installation-with-manifests.md#configure-rbac" >}}).
+{{< include "rbac/set-up-rbac.md" >}}
+
+---
+
+## Create common resources {#create-common-resources}
+
+{{< include "installation/create-common-resources.md" >}}
+
+---
+
+## Deploy NGINX Ingress Controller {#deploy-ingress-controller}
+
+{{< include "installation/deploy-controller.md" >}}
+
+### Using a Deployment
+
+{{< include "installation/manifests/deployment.md" >}}
+
+### Using a DaemonSet
+
+{{< include "installation/manifests/daemonset.md" >}}
+
+---
+
+## Enable NGINX App Protect WAF module
+
+To enable the NGINX App Protect DoS Module:
+
+- Add the `enable-app-protect` [command-line argument]({{< relref "configuration/global-configuration/command-line-arguments.md#cmdoption-enable-app-protect" >}}) to your Deployment or DaemonSet file.
+
+---
+
+## Confirm NGINX Ingress Controller is running
+
+{{< include "installation/manifests/verify-pods-are-running.md" >}}
+
+For more information, see the [Configuration guide]({{< relref "installation/integrations/app-protect-waf/configuration.md" >}}),the [NGINX Ingress Controller with App Protect WAF example for VirtualServer](https://github.com/nginxinc/kubernetes-ingress/tree/v3.3.2/examples/custom-resources/app-protect-waf) and the [NGINX Ingress Controller with App Protect WAF example for Ingress](https://github.com/nginxinc/kubernetes-ingress/tree/v3.3.2/examples/ingress-resources/app-protect-waf).
+
+---
 
-    > **Important**: You must have an admin role to configure RBAC in your Kubernetes cluster.
+## Alternatives to building your own image {#pre-built-images}
 
-2. [Create the common Kubernetes resources]({{< relref "installation/installing-nic/installation-with-manifests.md#create-common-resources" >}}).
-3. Enable the App Protect WAF module by adding the `enable-app-protect` [cli argument]({{< relref "configuration/global-configuration/command-line-arguments.md#cmdoption-enable-app-protect" >}}) to your Deployment or DaemonSet file.
-4. [Deploy the Ingress Controller]({{< relref "installation/installing-nic/installation-with-manifests.md#deploy-ingress-controller" >}}).
+If you prefer not to build your own NGINX Ingress Controller image, you can use pre-built images. Here are your options:
 
-For more information, see the [Configuration guide]({{< relref "installation/integrations/app-protect-waf/configuration.md" >}}) and the NGINX Ingress Controller with App Protect example resources on GitHub [for VirtualServer resources](https://github.com/nginxinc/kubernetes-ingress/tree/v3.3.2/examples/custom-resources/app-protect-waf) and [for Ingress resources](https://github.com/nginxinc/kubernetes-ingress/tree/v3.3.2/examples/ingress-resources/app-protect-waf" >}}).
+- Download the image using your NGINX Ingress Controller subscription certificate and key. See the [Getting the F5 Registry NGINX Ingress Controller Image]({{< relref "installation/nic-images/pulling-ingress-controller-image.md" >}}) guide.
+- Use your NGINX Ingress Controller subscription JWT token to get the image: Instructions are in [Getting the NGINX Ingress Controller Image with JWT]({{< relref "installation/nic-images/using-the-jwt-token-docker-secret.md" >}}).