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..20dbf6c54f --- /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%}} + +{{}} diff --git a/docs/content/includes/installation/deploy-controller.md b/docs/content/includes/installation/deploy-controller.md new file mode 100644 index 0000000000..d1d86c3260 --- /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. diff --git a/docs/content/installation/installing-nic/installation-with-manifests.md b/docs/content/installation/installing-nic/installation-with-manifests.md index 8cce2039a2..d1f16ded4c 100644 --- a/docs/content/installation/installing-nic/installation-with-manifests.md +++ b/docs/content/installation/installing-nic/installation-with-manifests.md @@ -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 61d60220d2..2eb8a24be7 100644 --- a/docs/content/installation/integrations/app-protect-dos/installation.md +++ b/docs/content/installation/integrations/app-protect-dos/installation.md @@ -116,14 +116,53 @@ make push PREFIX=/nginx-plus-ingress --- -## Deploy NGINX Ingress Controller {#deploy-ingress-controller} +## 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 +``` -You have two options for deploying NGINX Ingress Controller: +{{%/tab%}} -- **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. +{{%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} -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/configuration.md b/docs/content/installation/integrations/app-protect-waf/configuration.md index b44a8e0b78..4c0065573d 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 9ab4b891d7..a37814bfbf 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,86 +8,222 @@ 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: + + ```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 + ``` + + **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. + +{{}} 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. {{}} + +### Makefile targets {#makefile-targets} + +{{}} +| 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 | +{{}} + +
+ +{{}} 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 +``` + +--- + +## Set up role-based access control (RBAC) {#set-up-rbac} + +{{< include "rbac/set-up-rbac.md" >}} + +--- + +## Create common resources {#create-common-resources} + +{{< include "installation/create-common-resources.md" >}} + +--- + +## 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` - 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 +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 +``` - 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` +{{%/tab%}} - > **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 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. +--- + +## 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 >}} -- [Push the image to your local Docker registry]({{< relref "installation/building-nginx-ingress-controller.md#build-image-push-to-private-repo" >}}. +Add a `volumes` section to deployment template spec: -## Install the Ingress Controller +```yaml +... +volumes: +- name: +persistentVolumeClaim: + claimName: +... +``` -Take the steps below to set up and deploy the NGINX Ingress Controller and App Protect WAF module in your Kubernetes cluster. +Add volume mounts to the `containers` section: -1. [Configure role-based access control (RBAC)]({{< relref "installation/installing-nic/installation-with-manifests.md#configure-rbac" >}}). +```yaml +... +volumeMounts: +- name: + mountPath: /etc/nginx/waf/bundles +... +``` - > **Important**: You must have an admin role to configure RBAC in your Kubernetes cluster. +### Using a Deployment + +{{< include "installation/manifests/deployment.md" >}} + +### Using a DaemonSet + +{{< include "installation/manifests/daemonset.md" >}} + +--- -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. - If you intend to use the NGINX Ingress Controller with the AppProtect WAF module and policy bundles, follow these additional steps: - - Skip configuring custom resource definition for `APPolicy` `APLogConf` and `APUserSig`. - - Create and configure [Persistent Volume and Persistent Volume Claim](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) in your Kubernetes cluster. - - Modify NGINX Ingress Controller Deployment or DaemonSet file to include volumes and volume mounts. +## 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). + +--- - Make the following changes: - Add `volumes` section to deployment template spec: - ```yaml - ... - volumes: - - name: - persistentVolumeClaim: - claimName: - ... - ``` - Add volume mounts to `containers` section: - ```yaml - ... - volumeMounts: - - name: - mountPath: /etc/nginx/waf/bundles - ... - ``` - > **Important**: NGINX Ingress Controller requires the volume mount path to be `/etc/nginx/waf/bundles` +## Alternatives to building your own image {#pre-built-images} -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" >}}).