From 59a9a858add9a52534fd08e171c2c67d5d94838e Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Thu, 30 Nov 2023 11:38:42 +0000 Subject: [PATCH 1/5] Rewrite NGINX App Protect WAF Installation, add deployment include This commit rewrites the installation document for NGINX App Protect WAF to match the format posited in the prior NGINX App Protect DOS rewrite. As part of the changes, a snippet of text indicating the deployment options for NGINX Ingress Controller was turned into an include. --- .../installation/deploy-controller.md | 10 ++ .../app-protect-dos/installation.md | 7 +- .../app-protect-waf/installation.md | 153 ++++++++++++++---- 3 files changed, 130 insertions(+), 40 deletions(-) create mode 100644 docs/content/includes/installation/deploy-controller.md diff --git a/docs/content/includes/installation/deploy-controller.md b/docs/content/includes/installation/deploy-controller.md new file mode 100644 index 0000000000..5ce2472607 --- /dev/null +++ b/docs/content/includes/installation/deploy-controller.md @@ -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. \ No newline at end of file diff --git a/docs/content/installation/integrations/app-protect-dos/installation.md b/docs/content/installation/integrations/app-protect-dos/installation.md index 61d60220d2..206780609a 100644 --- a/docs/content/installation/integrations/app-protect-dos/installation.md +++ b/docs/content/installation/integrations/app-protect-dos/installation.md @@ -118,12 +118,7 @@ make push PREFIX=/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 diff --git a/docs/content/installation/integrations/app-protect-waf/installation.md b/docs/content/installation/integrations/app-protect-waf/installation.md index 696084e63d..5ee0ddb5f9 100644 --- a/docs/content/installation/integrations/app-protect-waf/installation.md +++ b/docs/content/installation/integrations/app-protect-waf/installation.md @@ -1,6 +1,6 @@ --- -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 @@ -8,61 +8,146 @@ 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. +{{}}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.{{}} -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 `` with the path to your own private registry. + + ```shell + docker login + ``` + +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=/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 `` with your chosen build option and `` with your private registry's path. Refer to the [Makefile targets](#makefile-targets) table below for the list of build options. + + ```shell + make PREFIX=/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=/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. +{{}} 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**: 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" >}}. +{{}} +| 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 | +{{}} -## Install the Ingress Controller +
+ +{{}} 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. {{}} + +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` + +{{}} External references are deprecated in NGINX Ingress Controller and will not be supported in future releases. {{}} + +--- + +## 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 `` with your private registry's path. + +```shell +make push PREFIX=/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" >}}). \ No newline at end of file From f57d8445fcc40197159f6eeadc94ecb3452465bf Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 30 Nov 2023 11:49:02 +0000 Subject: [PATCH 2/5] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/content/includes/installation/deploy-controller.md | 2 +- .../installation/integrations/app-protect-waf/installation.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/content/includes/installation/deploy-controller.md b/docs/content/includes/installation/deploy-controller.md index 5ce2472607..d1d86c3260 100644 --- a/docs/content/includes/installation/deploy-controller.md +++ b/docs/content/includes/installation/deploy-controller.md @@ -7,4 +7,4 @@ 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. \ No newline at end of file +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. diff --git a/docs/content/installation/integrations/app-protect-waf/installation.md b/docs/content/installation/integrations/app-protect-waf/installation.md index 5ee0ddb5f9..f76debc4f8 100644 --- a/docs/content/installation/integrations/app-protect-waf/installation.md +++ b/docs/content/installation/integrations/app-protect-waf/installation.md @@ -82,7 +82,7 @@ Follow these steps to build the NGINX Controller Image with NGINX App Protect WA {{}} 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. {{}} -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. +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` @@ -150,4 +150,4 @@ For more information, see the [Configuration guide]({{< relref "installation/int 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]({{< 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" >}}). \ No newline at end of file +- 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" >}}). From b0c437b9e3e4a8efa39983b8a160a75de4dab5e6 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Wed, 13 Dec 2023 11:07:47 +0000 Subject: [PATCH 3/5] Add custom resource include, update files related to App Protect This commit adds a new include file for custom resources, and subsequently adds it to the relevant App Protect WAF/DoS documentation. A few documentation improvements arej also included to rephrase sections of the configuration document for conciseness and clarity. --- .../installation/create-custom-resources.md | 48 +++++ .../installation-with-manifests.md | 72 +------- .../app-protect-dos/installation.md | 44 +++++ .../app-protect-waf/configuration.md | 164 +++++++++--------- .../app-protect-waf/installation.md | 78 ++++++++- 5 files changed, 254 insertions(+), 152 deletions(-) create mode 100644 docs/content/includes/installation/create-custom-resources.md diff --git a/docs/content/includes/installation/create-custom-resources.md b/docs/content/includes/installation/create-custom-resources.md new file mode 100644 index 0000000000..924835c5cd --- /dev/null +++ b/docs/content/includes/installation/create-custom-resources.md @@ -0,0 +1,48 @@ +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: + +1. Using a URL to apply a single CRD yaml file, which we recommend. +1. Applying your local copy of the CRD yaml files, which requires you to clone the repository. + +{{}} + +{{%tab name="Install CRDs from single YAML"%}} + +This single YAML file creates CRDs for the following resources: + +- [VirtualServer and VirtualServerRoute]({{< relref "configuration/virtualserver-and-virtualserverroute-resources.md" >}}) +- [TransportServer]({{< relref "configuration/transportserver-resource.md" >}}) +- [Policy]({{< relref "configuration/policy-resource.md" >}}) +- [GlobalConfiguration]({{< relref "configuration/global-configuration/globalconfiguration-resource.md" >}}) + +```shell +kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.3.2/deploy/crds.yaml +``` + +{{%/tab%}} + +{{%tab name="Install CRDs after cloning the repo"%}} + +{{< note >}} If you are installing the CRDs this way, ensure you have first cloned the repository. {{< /note >}} + +These YAML files create CRDs for the following resources: + +- [VirtualServer and VirtualServerRoute]({{< relref "configuration/virtualserver-and-virtualserverroute-resources.md" >}}) +- [TransportServer]({{< relref "configuration/transportserver-resource.md" >}}) +- [Policy]({{< relref "configuration/policy-resource.md" >}}) +- [GlobalConfiguration]({{< relref "configuration/global-configuration/globalconfiguration-resource.md" >}}) + +```shell +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 +``` + +{{%/tab%}} + +{{}} \ No newline at end of file diff --git a/docs/content/installation/installing-nic/installation-with-manifests.md b/docs/content/installation/installing-nic/installation-with-manifests.md index 8cce2039a2..91ca99e61a 100644 --- a/docs/content/installation/installing-nic/installation-with-manifests.md +++ b/docs/content/installation/installing-nic/installation-with-manifests.md @@ -15,7 +15,7 @@ docs: "DOCS-603" ### Get the NGINX Controller Image -{{}}Always use the most up-to-date stable release listed on the [releases page]({{< relref "releases.md" >}}).{{}} +{{}} Always use the most up-to-date stable release listed on the [releases page]({{< relref "releases.md" >}}).{{}} Choose one of the following methods to get the NGINX Ingress Controller image: @@ -55,76 +55,8 @@ This guide assumes you are using the latest release. ## Create custom resources {#create-custom-resources} -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: - 1. Using a URL to apply a single CRD yaml file. We recommend this approach. - 2. Applying your local copy of the CRD yaml files. This requires that you [clone the repository](#lone-the-repository). +{{< include "installation/create-custom-resources.md" >}} -{{}} - -{{%tab name="Install CRDs from single YAML"%}} - -### Core custom resource definitions - -1. Create CRDs for [VirtualServer and VirtualServerRoute]({{< relref "configuration/virtualserver-and-virtualserverroute-resources.md" >}}), [TransportServer]({{< relref "configuration/transportserver-resource.md" >}}), [Policy]({{< relref "configuration/policy-resource.md" >}}) and [GlobalConfiguration]({{< relref "configuration/global-configuration/globalconfiguration-resource.md" >}}): - - ```shell - kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.3.2/deploy/crds.yaml - ``` - -### Optional custom resource definitions - -1. For the NGINX App Protect WAF module, create CRDs for `APPolicy`, `APLogConf` and `APUserSig`: - - ```shell - kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.3.2/deploy/crds-nap-waf.yaml - ``` - -2. For the NGINX App Protect DoS module, create CRDs for `APDosPolicy`, `APDosLogConf` and `DosProtectedResource`: - - ```shell - kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.3.2/deploy/crds-nap-dos.yaml - ``` - -{{%/tab%}} - -{{%tab name="Install CRDs after cloning the repo"%}} - -If you are installing the CRDs this way, ensure that you have first [cloned the repository](#clone-the-repository) - -### Core custom resource definitions - -1. Create CRDs for [VirtualServer and VirtualServerRoute]({{< relref "configuration/virtualserver-and-virtualserverroute-resources.md" >}}), [TransportServer]({{< relref "configuration/transportserver-resource.md" >}}), [Policy]({{< relref "configuration/policy-resource.md" >}}) and [GlobalConfiguration]({{< relref "configuration/global-configuration/globalconfiguration-resource.md" >}}): - - ```shell - 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 - ``` -### Optional custom resource definitions - -{{< note >}} This step can be skipped if you are using App Protect WAF module with policy bundles. {{< /note >}} - -1. For the NGINX App Protect WAF module, create CRDs for `APPolicy`, `APLogConf` and `APUserSig`: - - ```shell - kubectl apply -f config/crd/bases/appprotect.f5.com_aplogconfs.yaml - kubectl apply -f config/crd/bases/appprotect.f5.com_appolicies.yaml - kubectl apply -f config/crd/bases/appprotect.f5.com_apusersigs.yaml - ``` - -2. For the NGINX App Protect DoS module, create CRDs for `APDosPolicy`, `APDosLogConf` and `DosProtectedResource`: - - ```shell - kubectl apply -f config/crd/bases/appprotectdos.f5.com_apdoslogconfs.yaml - kubectl apply -f config/crd/bases/appprotectdos.f5.com_apdospolicy.yaml - kubectl apply -f config/crd/bases/appprotectdos.f5.com_dosprotectedresources.yaml - ``` -{{%/tab%}} - -{{}} --- diff --git a/docs/content/installation/integrations/app-protect-dos/installation.md b/docs/content/installation/integrations/app-protect-dos/installation.md index 206780609a..2eb8a24be7 100644 --- a/docs/content/installation/integrations/app-protect-dos/installation.md +++ b/docs/content/installation/integrations/app-protect-dos/installation.md @@ -116,6 +116,50 @@ make push PREFIX=/nginx-plus-ingress --- +## Create custom resources {#create-custom-resources} + +{{< include "installation/create-custom-resources.md" >}} + +--- + +## Create App Protect DoS custom resources + +{{}} + +{{%tab name="Install CRDs from single YAML"%}} + +This single YAML file creates CRDs for the following resources: + +- `APDosPolicy` +- `APDosLogConf` +- `DosProtectedResource` + +```shell +kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.3.2/deploy/crds-nap-dos.yaml +``` + +{{%/tab%}} + +{{%tab name="Install CRDs after cloning the repo"%}} + +These YAML files create CRDs for the following resources: + +- `APDosPolicy` +- `APDosLogConf` +- `DosProtectedResource` + +```shell +kubectl apply -f config/crd/bases/appprotectdos.f5.com_apdoslogconfs.yaml +kubectl apply -f config/crd/bases/appprotectdos.f5.com_apdospolicy.yaml +kubectl apply -f config/crd/bases/appprotectdos.f5.com_dosprotectedresources.yaml +``` + +{{%/tab%}} + +{{}} + +--- + ## Deploy NGINX Ingress Controller {#deploy-ingress-controller} {{< include "installation/deploy-controller.md" >}} diff --git a/docs/content/installation/integrations/app-protect-waf/configuration.md b/docs/content/installation/integrations/app-protect-waf/configuration.md index b44a8e0b78..ec3b3c5dd1 100644 --- a/docs/content/installation/integrations/app-protect-waf/configuration.md +++ b/docs/content/installation/integrations/app-protect-waf/configuration.md @@ -1,6 +1,6 @@ --- title: Configuration -description: "Learn how to use NGINX Ingress Controller to configure NGINX App Protect WAF." +description: "This document explains how to use F5 NGINX Ingress Controller to configure NGINX App Protect WAF." weight: 1900 doctypes: [""] toc: true @@ -8,107 +8,108 @@ docs: "DOCS-578" aliases: ["/app-protect/configuration/"] --- -> Check out the complete NGINX Ingress Controller with NGINX App Protect WAF 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). +{{< note >}} The NGINX Ingress Controller repository has complete NGINX App Protect WAF examples with [VirtualServer resources](https://github.com/nginxinc/kubernetes-ingress/tree/v3.3.2/examples/custom-resources/app-protect-waf) and [Ingress resources](https://github.com/nginxinc/kubernetes-ingress/tree/v3.3.2/examples/ingress-resources/app-protect-waf). {{< /note >}} ## Global Configuration -NGINX Ingress Controller has a set of global configuration parameters that align with those available in NGINX App Protect WAF. See [ConfigMap keys]({{< relref "configuration/global-configuration/configmap-resource.md#modules" >}}) for the complete list. The NGINX App Protect WAF parameters use the `app-protect*` prefix. +NGINX Ingress Controller has global configuration parameters that match those in NGINX App Protect WAF. They are found in the [ConfigMap resource]({{< relref "configuration/global-configuration/configmap-resource.md#modules" >}}): the NGINX App Protect WAF parameters are prefixed with `app-protect*`. ## Enable NGINX App Protect WAF -You can enable and configure NGINX App Protect WAF on the Custom Resources (VirtualServer, VirtualServerRoute) or on the Ingress-resource basis. +NGINX App Protect WAF can be enabled and configured for custom resources (VirtualServer, VirtualServerRoute) or Ingress resources. -To configure NGINX App Protect WAF on a VirtualServer resource, you would create a Policy Custom Resource referencing the `APPolicy` Custom Resource or `APPolicy` Bundle, and add this to the VirtualServer definition. See the documentation on the [NGINX App Protect WAF Policy]({{< relref "configuration/policy-resource.md#waf" >}}). +- For custom resources, you need to create a Policy Custom Resource referencing the `APPolicy` custom resource or bundle, then add it to the VirtualServer definition. Additional detail can be found in the [Policy Resource documentation]({{< relref "configuration/policy-resource.md#waf" >}}). +- For Ingress resources, apply the [`app-protect` annotations]({{< relref "configuration/ingress-resources/advanced-configuration-with-annotations.md#app-protect" >}}) to each desired resource. -To configure NGINX App Protect WAF on an Ingress resource, you would apply the [`app-protect` annotations]({{< relref "configuration/ingress-resources/advanced-configuration-with-annotations.md#app-protect" >}}) to each desired resource. ## NGINX App Protect WAF Policies -You can define NGINX App Protect WAF policies for your VirtualServer, VirtualServerRoute, or Ingress resources by creating an `APPolicy` [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). +NGINX App Protect WAF Policies can be created for VirtualServer, VirtualServerRoute, or Ingress resources by creating an `APPolicy` [custom resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). There are some caveats: - > **Note**: The fields `policy.signature-requirements[].minRevisionDatetime` and `policy.signature-requirements[].maxRevisionDatetime` are not supported. - - > **Note**: [The Advanced gRPC Protection for Unary Traffic](/nginx-app-protect-waf/configuration-guide/configuration/#grpc-protection-for-unary-traffic) only supports providing an `idl-file` inline. The fields `policy.idl-files[].link`, `policy.idl-files[].$ref`, and +- The fields `policy.signature-requirements[].minRevisionDatetime` and `policy.signature-requirements[].maxRevisionDatetime` are not supported. +- [The Advanced gRPC Protection for Unary Traffic](/nginx-app-protect-waf/configuration-guide/configuration/#grpc-protection-for-unary-traffic) only supports providing an `idl-file` inline. The fields `policy.idl-files[].link`, `policy.idl-files[].$ref`, and `policy.idl-files[].file` are not supported. The IDL file should be provided in field `policy.idl-files[].contents`. The value of this field can be base64 encoded. In this case the field `policy.idl-files[].isBase64` should be set to `true`. - > **Note**: [External References](/nginx-app-protect-waf/configuration-guide/configuration/#external-references) in the Ingress Controller are deprecated and will not be supported in future releases. - -To add any [NGINX App Protect WAF policy](/nginx-app-protect-waf/declarative-policy/policy/) to an Ingress resource: - -1. Create an `APPolicy` Custom resource manifest. -2. Add the desired policy to the `spec` field in the `APPolicy` resource. - - > **Note**: The relationship between the Policy JSON and the resource spec is 1:1. If you're defining your resources in YAML, as we do in our examples, you'll need to represent the policy as YAML. The fields must match those in the source JSON exactly in name and level. - - For example, say you want to use the [DataGuard policy](/nginx-app-protect-waf/declarative-policy/policy/#policy/data-guard) shown below: - - ```json - { - "policy": { - "name": "dataguard_blocking", - "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" }, - "applicationLanguage": "utf-8", - "enforcementMode": "blocking", - "blocking-settings": { - "violations": [ - { - "name": "VIOL_DATA_GUARD", - "alarm": true, - "block": true - } - ] - }, - "data-guard": { - "enabled": true, - "maskData": true, - "creditCardNumbers": true, - "usSocialSecurityNumbers": true, - "enforcementMode": "ignore-urls-in-list", - "enforcementUrls": [] - } - } - } - ``` +{{}} External references are deprecated in NGINX Ingress Controller and will not be supported in future releases. {{}} - You would create an `APPolicy` resource with the policy defined in the `spec`, as shown below: +To add an [NGINX App Protect WAF policy](/nginx-app-protect-waf/declarative-policy/policy/) to an Ingress resource: - ```yaml - apiVersion: appprotect.f5.com/v1beta1 - kind: APPolicy - metadata: - name: dataguard-blocking - spec: - policy: - name: dataguard_blocking - template: - name: POLICY_TEMPLATE_NGINX_BASE - applicationLanguage: utf-8 - enforcementMode: blocking - blocking-settings: - violations: - - name: VIOL_DATA_GUARD - alarm: true - block: true - data-guard: - enabled: true - maskData: true - creditCardNumbers: true - usSocialSecurityNumbers: true - enforcementMode: ignore-urls-in-list - enforcementUrls: [] +1. Create an `APPolicy` custom resource manifest. +1. Add the policy to the `spec` field in the `APPolicy` resource. + +A resource specification and its Policy JSON **must** match. The fields must be identical in name and nesting level. If the resources are defined with YAML, the policy must also be represented in YAML. + +As an example, this is a [DataGuard policy](/nginx-app-protect-waf/declarative-policy/policy/#policy/data-guard): + +```json +{ + "policy": { + "name": "dataguard_blocking", + "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" }, + "applicationLanguage": "utf-8", + "enforcementMode": "blocking", + "blocking-settings": { + "violations": [ + { + "name": "VIOL_DATA_GUARD", + "alarm": true, + "block": true + } + ] + }, + "data-guard": { + "enabled": true, + "maskData": true, + "creditCardNumbers": true, + "usSocialSecurityNumbers": true, + "enforcementMode": "ignore-urls-in-list", + "enforcementUrls": [] + } + } +} ``` - > Notice how the fields match exactly in name and level. NGINX Ingress Controller will transform the YAML into a valid JSON WAF policy config. +This is what its corresponding `APPolicy` resource defined in the `spec` would look like: + +```yaml +apiVersion: appprotect.f5.com/v1beta1 +kind: APPolicy +metadata: + name: dataguard-blocking +spec: + policy: + name: dataguard_blocking + template: + name: POLICY_TEMPLATE_NGINX_BASE + applicationLanguage: utf-8 + enforcementMode: blocking + blocking-settings: + violations: + - name: VIOL_DATA_GUARD + alarm: true + block: true + data-guard: + enabled: true + maskData: true + creditCardNumbers: true + usSocialSecurityNumbers: true + enforcementMode: ignore-urls-in-list + enforcementUrls: [] +``` + +Notice that the fields match in name and nesting: NGINX Ingress Controller will transform the YAML into a valid JSON WAF policy config. ## NGINX App Protect WAF Logs +Configuring + You can set the [NGINX App Protect WAF log configurations](/nginx-app-protect-waf/logging-overview/logs-overview/) by creating an `APLogConf` [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). To add the [log configurations](/nginx-app-protect-waf/logging-overview/security-log/) to a VirtualServer or an Ingress resource: 1. Create an `APLogConf` Custom Resource manifest. -2. Add the desired log configuration to the `spec` field in the `APLogConf` resource. -3. Add the `APLogConf` reference to the [VirtualServer Policy resource]({{< relref "configuration/policy-resource.md#waf" >}}) or the [Ingress resource]({{< relref "configuration/ingress-resources/advanced-configuration-with-annotations.md#app-protect" >}}) as per the documentation. +1. Add the log configuration to the `spec` field in the `APLogConf` resource. +1. Add a reference to `APLogConf` in the [VirtualServer Policy resource]({{< relref "configuration/policy-resource.md#waf" >}}) or the [Ingress resource]({{< relref "configuration/ingress-resources/advanced-configuration-with-annotations.md#app-protect" >}}) as per the documentation. > **Note**: The fields from the JSON must be presented in the YAML *exactly* the same, in name and level. NGINX Ingress Controller will transform the YAML into a valid JSON WAF log config. @@ -209,12 +210,15 @@ spec: ## App Protect WAF Bundles -You can define App Protect WAF bundles for VirtualServers by creating policy bundles and putting them on a mounted volume accessible from NGINX Ingress Controller. +You can define App Protect WAF bundles for VirtualServer custom resources by creating policy bundles and putting them on a mounted volume accessible from NGINX Ingress Controller. +Before applying a policy, a WAF policy bundle must be created, then copied to a volume mounted to `/etc/nginx/waf/bundles`. + +{{< note >}} NGINX Ingress Controller does not currently support `securityLogs` for policy bundles. {{< /note >}} + +This example show how a policy is configured by referencing a generated WAF Policy Bundle: -For example, you can configure a policy by referencing generated WAF Policy Bundle: -> **Note**: Currently we do not support `securityLogs` for policy bundles. ```yaml apiVersion: k8s.nginx.org/v1 kind: Policy @@ -226,8 +230,6 @@ spec: apBundle: ".tgz" ``` -> **Note**: Before applying the policy, a WAF Policy Bundle must be created, copied to a volume, and the volume must be mounted to `/etc/nginx/waf/bundles`. - ## OpenAPI Specification in NGINX Ingress Controller The OpenAPI Specification defines the spec file format needed to describe RESTful APIs. The spec file can be written either in JSON or YAML. Using a spec file simplifies the work of implementing API protection. Refer to the [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification) (formerly called Swagger) for details. diff --git a/docs/content/installation/integrations/app-protect-waf/installation.md b/docs/content/installation/integrations/app-protect-waf/installation.md index f76debc4f8..1608d921b1 100644 --- a/docs/content/installation/integrations/app-protect-waf/installation.md +++ b/docs/content/installation/integrations/app-protect-waf/installation.md @@ -10,7 +10,7 @@ aliases: ["/app-protect/installation/"] {{< custom-styles >}} -{{}}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.{{}} +{{}} 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.{{}} ## Before you start @@ -115,10 +115,86 @@ make push PREFIX=/nginx-plus-ingress --- +## Create core custom resources {#create-custom-resources} + + +{{< include "installation/create-custom-resources.md" >}} + +--- + +## Create App Protect WAF custom resources + +{{< note >}} If you're using NGINX Ingress Controller with the App Protect WAF module and policy bundles, you can skip this section. You will need to create and configure [Persistent Volume and Persistent Volume Claim](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) in your Kubernetes cluster. {{< /note >}} + +
+ +{{}} + +{{%tab name="Install CRDs from single YAML"%}} + +This single YAML file creates CRDs for the following resources: + +- `APPolicy` +- `APLogConf` +- `APUserSig` + +```shell +kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.3.2/deploy/crds-nap-waf.yaml +``` + +{{%/tab%}} + +{{%tab name="Install CRDs after cloning the repo"%}} + +{{< note >}} If you are installing the CRDs this way, ensure you have first cloned the repository. {{< /note >}} + +These YAML files create CRDs for the following resources: + +- `APPolicy` +- `APLogConf` +- `APUserSig` + +```shell +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 "installation/deploy-controller.md" >}} +{{< note >}} If you're using NGINX Ingress Controller with the AppProtect WAF module and policy bundles, you will need to modify the Deployment or DaemonSet file to include volumes and volume mounts. + +NGINX Ingress Controller **requires** the volume mount path to be `/etc/nginx/waf/bundles`. {{< /note >}} + +Add a `volumes` section to deployment template spec: + +```yaml +... +volumes: +- name: +persistentVolumeClaim: + claimName: +... +``` + +Add volume mounts to the `containers` section: + +```yaml +... +volumeMounts: +- name: + mountPath: /etc/nginx/waf/bundles +... +``` + ### Using a Deployment {{< include "installation/manifests/deployment.md" >}} From dd7b089f6c8ca4855fe3da9735c14fe5f4065c9a Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 13 Dec 2023 11:14:44 +0000 Subject: [PATCH 4/5] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- .../includes/installation/create-custom-resources.md | 6 +++--- .../integrations/app-protect-waf/configuration.md | 2 +- .../integrations/app-protect-waf/installation.md | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/content/includes/installation/create-custom-resources.md b/docs/content/includes/installation/create-custom-resources.md index 924835c5cd..20dbf6c54f 100644 --- a/docs/content/includes/installation/create-custom-resources.md +++ b/docs/content/includes/installation/create-custom-resources.md @@ -1,4 +1,4 @@ -To make sure your NGINX Ingress Controller pods reach the `Ready` state, you'll need to create custom resource definitions (CRDs) for various components. +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`. @@ -26,7 +26,7 @@ kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v {{%tab name="Install CRDs after cloning the repo"%}} -{{< note >}} If you are installing the CRDs this way, ensure you have first cloned the repository. {{< /note >}} +{{< note >}} If you are installing the CRDs this way, ensure you have first cloned the repository. {{< /note >}} These YAML files create CRDs for the following resources: @@ -45,4 +45,4 @@ kubectl apply -f config/crd/bases/k8s.nginx.org_globalconfigurations.yaml {{%/tab%}} -{{}} \ No newline at end of file +{{}} diff --git a/docs/content/installation/integrations/app-protect-waf/configuration.md b/docs/content/installation/integrations/app-protect-waf/configuration.md index ec3b3c5dd1..4c0065573d 100644 --- a/docs/content/installation/integrations/app-protect-waf/configuration.md +++ b/docs/content/installation/integrations/app-protect-waf/configuration.md @@ -101,7 +101,7 @@ Notice that the fields match in name and nesting: NGINX Ingress Controller will ## NGINX App Protect WAF Logs -Configuring +Configuring You can set the [NGINX App Protect WAF log configurations](/nginx-app-protect-waf/logging-overview/logs-overview/) by creating an `APLogConf` [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). diff --git a/docs/content/installation/integrations/app-protect-waf/installation.md b/docs/content/installation/integrations/app-protect-waf/installation.md index 1608d921b1..a37814bfbf 100644 --- a/docs/content/installation/integrations/app-protect-waf/installation.md +++ b/docs/content/installation/integrations/app-protect-waf/installation.md @@ -146,7 +146,7 @@ kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v {{%tab name="Install CRDs after cloning the repo"%}} -{{< note >}} If you are installing the CRDs this way, ensure you have first cloned the repository. {{< /note >}} +{{< note >}} If you are installing the CRDs this way, ensure you have first cloned the repository. {{< /note >}} These YAML files create CRDs for the following resources: @@ -164,7 +164,7 @@ kubectl apply -f config/crd/bases/appprotect.f5.com_apusersigs.yaml {{}} ---- +--- ## Deploy NGINX Ingress Controller {#deploy-ingress-controller} From 9542415dd702d0ef1eb112e6ac34ca3f47ef195f Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Wed, 13 Dec 2023 16:08:56 +0000 Subject: [PATCH 5/5] Update docs/content/installation/installing-nic/installation-with-manifests.md Signed-off-by: Alan Dooley --- .../installation/installing-nic/installation-with-manifests.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/installation/installing-nic/installation-with-manifests.md b/docs/content/installation/installing-nic/installation-with-manifests.md index 91ca99e61a..d1f16ded4c 100644 --- a/docs/content/installation/installing-nic/installation-with-manifests.md +++ b/docs/content/installation/installing-nic/installation-with-manifests.md @@ -15,7 +15,7 @@ docs: "DOCS-603" ### Get the NGINX Controller Image -{{}} Always use the most up-to-date stable release listed on the [releases page]({{< relref "releases.md" >}}).{{}} +{{}}Always use the most up-to-date stable release listed on the [releases page]({{< relref "releases.md" >}}).{{}} Choose one of the following methods to get the NGINX Ingress Controller image: