From 70d10c19ad00b5d50756ad234fc333208e44f7e3 Mon Sep 17 00:00:00 2001 From: Ciara Stacke <18287516+ciarams87@users.noreply.github.com> Date: Wed, 13 May 2026 10:21:02 +0100 Subject: [PATCH 1/3] NGF: Add supported images to tech specs and guidance around WAF images --- content/ngf/install/helm.md | 2 + content/ngf/install/nginx-plus.md | 2 + .../ngf/overview/technical-specifications.md | 52 +++++++++++ content/ngf/waf-integration/configuration.md | 86 ++++++++++++++++++- 4 files changed, 140 insertions(+), 2 deletions(-) diff --git a/content/ngf/install/helm.md b/content/ngf/install/helm.md index 23259bd2d..a8634fac9 100644 --- a/content/ngf/install/helm.md +++ b/content/ngf/install/helm.md @@ -20,6 +20,8 @@ To complete this guide, you will need: - [Helm 3.0 or later](https://helm.sh/docs/intro/install/), for deploying and managing applications on Kubernetes. - [Add certificates for secure authentication]({{< ref "/ngf/install/secure-certificates.md" >}}) in a production environment. +For a list of available images and their registries, see [Supported container images]({{< ref "/ngf/overview/technical-specifications.md#supported-container-images" >}}). + {{< call-out "important" >}} If you’d like to use NGINX Plus, some additional setup is also required: {{< /call-out >}} {{< details summary="NGINX Plus JWT setup" >}} diff --git a/content/ngf/install/nginx-plus.md b/content/ngf/install/nginx-plus.md index a988fd5f7..065b5f289 100644 --- a/content/ngf/install/nginx-plus.md +++ b/content/ngf/install/nginx-plus.md @@ -192,6 +192,8 @@ docker pull private-registry.nginx.com/nginx-gateway-fabric/nginx-plus:{{< versi Once you have successfully pulled the image, you can tag it as needed, then push it to a different container registry. +For a complete list of available NGINX Plus images, including UBI-based and WAF variants, see [Supported container images]({{< ref "/ngf/overview/technical-specifications.md#supported-container-images" >}}). + ## Alternative installation options There are alternative ways to get an NGINX Plus image for NGINX Gateway Fabric: diff --git a/content/ngf/overview/technical-specifications.md b/content/ngf/overview/technical-specifications.md index 1f594dd0b..309cca323 100644 --- a/content/ngf/overview/technical-specifications.md +++ b/content/ngf/overview/technical-specifications.md @@ -45,6 +45,58 @@ The following table lists the OpenShift versions and Operator versions compatibl NGINX Gateway Fabric is conformant with the Gateway API version installed on supported OCP versions. The "OCP with Preferred GWAPI" column shows which OCP versions ship with the preferred Gateway API version. On OCP versions with an older Gateway API installed, NGF remains fully conformant with that installed version, but features from newer Gateway API versions that NGF supports will be unavailable. +## Supported container images + +NGINX Gateway Fabric provides container images for the control plane and the NGINX data plane. All images are available for `amd64` and `arm64` architectures unless otherwise noted. + +### Control plane images + +The control plane image contains the NGINX Gateway Fabric binary. + +| Name | Base image | Image | Architectures | +|-----------------|-----------------------|--------------------------------------------------------------|----------------| +| Default image | `scratch` | `ghcr.io/nginx/nginx-gateway-fabric:{{< version-ngf >}}` | amd64
arm64 | +| UBI-based image | `redhat/ubi9-minimal` | `ghcr.io/nginx/nginx-gateway-fabric:{{< version-ngf >}}-ubi` | amd64
arm64 | + +### Data plane images with NGINX + +_All images include NGINX 1.30.0._ + +| Name | Base image | Image | Architectures | +|-----------------|----------------------------|--------------------------------------------------------------------|----------------| +| Default image | `nginx:1.30.0-alpine-otel` | `ghcr.io/nginx/nginx-gateway-fabric/nginx:{{< version-ngf >}}` | amd64
arm64 | +| UBI-based image | `redhat/ubi9-minimal` | `ghcr.io/nginx/nginx-gateway-fabric/nginx:{{< version-ngf >}}-ubi` | amd64
arm64 | + +### Data plane images with NGINX Plus + +NGINX Plus images are available through the F5 Container registry `private-registry.nginx.com`. For setup instructions and authentication details, see [Install NGINX Gateway Fabric with NGINX Plus]({{< ref "/ngf/install/nginx-plus.md" >}}). + +_All images include NGINX Plus R36._ + +| Name | Base image | Image | Architectures | +|---------------------------------------|-----------------------|--------------------------------------------------------------------------------------------|----------------| +| Default image | `alpine:3.22` | `private-registry.nginx.com/nginx-gateway-fabric/nginx-plus:{{< version-ngf >}}` | amd64
arm64 | +| UBI-based image | `redhat/ubi9-minimal` | `private-registry.nginx.com/nginx-gateway-fabric/nginx-plus:{{< version-ngf >}}-ubi` | amd64
arm64 | +| Default image with F5 WAF for NGINX | `alpine:3.22` | `private-registry.nginx.com/nginx-gateway-fabric/nginx-plus-f5waf:{{< version-ngf >}}` | amd64 | +| UBI-based image with F5 WAF for NGINX | `redhat/ubi9-minimal` | `private-registry.nginx.com/nginx-gateway-fabric/nginx-plus-f5waf:{{< version-ngf >}}-ubi` | amd64 | + +### WAF sidecar images + +When F5 WAF for NGINX is enabled, two additional sidecar containers are deployed alongside the NGINX container. These images are available from the F5 Container registry. + +| Name | Image | Architectures | +|--------------------|---------------------------------------------------------------------------------|-------| +| WAF Enforcer | `private-registry.nginx.com/nap/waf-enforcer:{{< ngf-waf-release-version >}}` | amd64 | +| WAF Config Manager | `private-registry.nginx.com/nap/waf-config-mgr:{{< ngf-waf-release-version >}}` | amd64 | + +For more information on WAF integration, see [F5 WAF for NGINX overview]({{< ref "/ngf/waf-integration/overview.md" >}}). + +### Custom images + +You can build custom NGINX Gateway Fabric images from source. For instructions, see [Build NGINX Gateway Fabric]({{< ref "/ngf/install/build-image.md" >}}). + +--- + ## Gateway API compatibility The following tables summarizes which Gateway API resources NGINX Gateway Fabric supports and to which level. diff --git a/content/ngf/waf-integration/configuration.md b/content/ngf/waf-integration/configuration.md index 9a0ed79d5..b9f1eaa51 100644 --- a/content/ngf/waf-integration/configuration.md +++ b/content/ngf/waf-integration/configuration.md @@ -4,10 +4,10 @@ weight: 400 toc: true f5-content-type: how-to f5-product: FABRIC -f5-description: Configure security logging, polling, TLS, authentication, cookie seed, bundle integrity, and fail-open behavior for F5 WAF for NGINX. +f5-description: Configure security logging, polling, TLS, authentication, cookie seed, bundle integrity, fail-open behavior, and WAF container settings for F5 WAF for NGINX. --- -This page covers operational configuration for F5 WAF for NGINX in NGINX Gateway Fabric: security logging, automatic policy updates, TLS and authentication, bundle integrity verification, cookie seed management, and fetch failure handling. +This page covers operational configuration for F5 WAF for NGINX in NGINX Gateway Fabric: security logging, automatic policy updates, TLS and authentication, bundle integrity verification, cookie seed management, fetch failure handling, and WAF container settings. --- @@ -250,10 +250,92 @@ NGINX Gateway Fabric retries on the next reconciliation or poll cycle. No manual --- +## Configure WAF containers + +When WAF is enabled, NGINX Gateway Fabric deploys two sidecar containers — `waf-enforcer` and `waf-config-mgr` — alongside the main NGINX container. You can customize the image, resource requirements, and additional volume mounts for each container using the `NginxProxy` resource. + +These settings are configured under `spec.kubernetes.deployment.wafContainers` (or `spec.kubernetes.daemonSet.wafContainers` for DaemonSet mode). This follows the same infrastructure configuration pattern described in [Configure infrastructure-related settings]({{< ref "/ngf/how-to/data-plane-configuration.md#configure-infrastructure-related-settings" >}}). For the full list of configurable fields, see the `NginxProxy` spec in the [API reference]({{< ref "/ngf/reference/api.md" >}}). + +Each container (`enforcer` and `configManager`) supports the following fields: + +- **`image`**: Override the default image repository, tag, and pull policy. If not specified, NGINX Gateway Fabric uses the defaults from the F5 Container registry. For the default images, see [Supported container images]({{< ref "/ngf/overview/technical-specifications.md#supported-container-images" >}}). +- **`resources`**: Set CPU and memory requests and limits. +- **`volumeMounts`**: Add extra volume mounts. NGINX Gateway Fabric automatically configures the shared volumes required for communication between the NGINX, `waf-enforcer`, and `waf-config-mgr` containers. Additional mounts are appended to these defaults. + +The following example uses custom images from a private registry and sets resource requirements for both containers: + +```yaml +apiVersion: gateway.nginx.org/v1alpha2 +kind: NginxProxy +metadata: + name: waf-enabled-proxy +spec: + waf: + enable: true + kubernetes: + deployment: + wafContainers: + enforcer: + image: + repository: registry.example.com/nap/waf-enforcer + tag: "5.12.1" + resources: + requests: + cpu: 100m + memory: 128Mi + limits: + cpu: "1" + memory: 1Gi + configManager: + image: + repository: registry.example.com/nap/waf-config-mgr + tag: "5.12.1" + resources: + requests: + cpu: 50m + memory: 64Mi + limits: + cpu: 500m + memory: 256Mi +``` + +When installing with Helm, set the equivalent values under `nginx.wafContainers`: + +```yaml +# values.yaml +nginx: + config: + waf: + enable: true + wafContainers: + enforcer: + image: + repository: registry.example.com/nap/waf-enforcer + tag: "5.12.1" + resources: + requests: + cpu: 100m + memory: 128Mi + configManager: + image: + repository: registry.example.com/nap/waf-config-mgr + tag: "5.12.1" + resources: + requests: + cpu: 50m + memory: 64Mi +``` + +{{< call-out "note" >}} Image pull Secrets for private registries must be configured at install time using the `nginx.imagePullSecret` or `nginx.imagePullSecrets` Helm values (or the `--nginx-docker-secret` flag for manifest installs). The control plane copies these Secrets into any namespace where NGINX is deployed. For details, see [Install NGINX Gateway Fabric with NGINX Plus]({{< ref "/ngf/install/nginx-plus.md" >}}). {{< /call-out >}} + +--- + ## See also - [F5 WAF for NGINX overview]({{< ref "/ngf/waf-integration/overview.md" >}}) - [Configure policy sources (NGINX Instance Manager and NGINX One Console)]({{< ref "/ngf/waf-integration/policy-sources.md" >}}) +- [Configure infrastructure-related settings]({{< ref "/ngf/how-to/data-plane-configuration.md#configure-infrastructure-related-settings" >}}) - [Troubleshoot WAFPolicy status]({{< ref "/ngf/waf-integration/troubleshooting.md" >}}) +- [Supported container images]({{< ref "/ngf/overview/technical-specifications.md#supported-container-images" >}}) - [WAFPolicy and NginxProxy API reference]({{< ref "/ngf/reference/api.md" >}}) - [Build and use the compiler tool]({{< ref "/waf/configure/compiler.md" >}}) From 64835eddec0e2ecba75a8d232dcce7c8bc1f786f Mon Sep 17 00:00:00 2001 From: Ciara Stacke <18287516+ciarams87@users.noreply.github.com> Date: Mon, 18 May 2026 16:53:31 +0100 Subject: [PATCH 2/3] Improve image references --- content/ngf/overview/technical-specifications.md | 6 +----- content/ngf/waf-integration/configuration.md | 12 ++++++------ content/ngf/waf-integration/get-started.md | 9 ++++++++- content/ngf/waf-integration/overview.md | 13 ++++++++++++- 4 files changed, 27 insertions(+), 13 deletions(-) diff --git a/content/ngf/overview/technical-specifications.md b/content/ngf/overview/technical-specifications.md index 309cca323..4a826d702 100644 --- a/content/ngf/overview/technical-specifications.md +++ b/content/ngf/overview/technical-specifications.md @@ -60,19 +60,15 @@ The control plane image contains the NGINX Gateway Fabric binary. ### Data plane images with NGINX -_All images include NGINX 1.30.0._ - | Name | Base image | Image | Architectures | |-----------------|----------------------------|--------------------------------------------------------------------|----------------| -| Default image | `nginx:1.30.0-alpine-otel` | `ghcr.io/nginx/nginx-gateway-fabric/nginx:{{< version-ngf >}}` | amd64
arm64 | +| Default image | `nginx:alpine-otel` | `ghcr.io/nginx/nginx-gateway-fabric/nginx:{{< version-ngf >}}` | amd64
arm64 | | UBI-based image | `redhat/ubi9-minimal` | `ghcr.io/nginx/nginx-gateway-fabric/nginx:{{< version-ngf >}}-ubi` | amd64
arm64 | ### Data plane images with NGINX Plus NGINX Plus images are available through the F5 Container registry `private-registry.nginx.com`. For setup instructions and authentication details, see [Install NGINX Gateway Fabric with NGINX Plus]({{< ref "/ngf/install/nginx-plus.md" >}}). -_All images include NGINX Plus R36._ - | Name | Base image | Image | Architectures | |---------------------------------------|-----------------------|--------------------------------------------------------------------------------------------|----------------| | Default image | `alpine:3.22` | `private-registry.nginx.com/nginx-gateway-fabric/nginx-plus:{{< version-ngf >}}` | amd64
arm64 | diff --git a/content/ngf/waf-integration/configuration.md b/content/ngf/waf-integration/configuration.md index b9f1eaa51..f6aa65c3c 100644 --- a/content/ngf/waf-integration/configuration.md +++ b/content/ngf/waf-integration/configuration.md @@ -252,9 +252,9 @@ NGINX Gateway Fabric retries on the next reconciliation or poll cycle. No manual ## Configure WAF containers -When WAF is enabled, NGINX Gateway Fabric deploys two sidecar containers — `waf-enforcer` and `waf-config-mgr` — alongside the main NGINX container. You can customize the image, resource requirements, and additional volume mounts for each container using the `NginxProxy` resource. +When WAF is enabled, NGINX Gateway Fabric deploys two sidecar containers — `waf-enforcer` and `waf-config-mgr` — alongside the main NGINX container. -These settings are configured under `spec.kubernetes.deployment.wafContainers` (or `spec.kubernetes.daemonSet.wafContainers` for DaemonSet mode). This follows the same infrastructure configuration pattern described in [Configure infrastructure-related settings]({{< ref "/ngf/how-to/data-plane-configuration.md#configure-infrastructure-related-settings" >}}). For the full list of configurable fields, see the `NginxProxy` spec in the [API reference]({{< ref "/ngf/reference/api.md" >}}). +These settings are configured under `spec.kubernetes.deployment.wafContainers` (or `spec.kubernetes.daemonSet.wafContainers` for DaemonSet mode) in the NginxProxy resource. This follows the same infrastructure configuration pattern described in [Configure infrastructure-related settings]({{< ref "/ngf/how-to/data-plane-configuration.md#configure-infrastructure-related-settings" >}}). For the full list of configurable fields, see the `NginxProxy` spec in the [API reference]({{< ref "/ngf/reference/api.md" >}}). Each container (`enforcer` and `configManager`) supports the following fields: @@ -278,7 +278,7 @@ spec: enforcer: image: repository: registry.example.com/nap/waf-enforcer - tag: "5.12.1" + tag: "{{< ngf-waf-release-version >}}" resources: requests: cpu: 100m @@ -289,7 +289,7 @@ spec: configManager: image: repository: registry.example.com/nap/waf-config-mgr - tag: "5.12.1" + tag: "{{< ngf-waf-release-version >}}" resources: requests: cpu: 50m @@ -311,7 +311,7 @@ nginx: enforcer: image: repository: registry.example.com/nap/waf-enforcer - tag: "5.12.1" + tag: "{{< ngf-waf-release-version >}}" resources: requests: cpu: 100m @@ -319,7 +319,7 @@ nginx: configManager: image: repository: registry.example.com/nap/waf-config-mgr - tag: "5.12.1" + tag: "{{< ngf-waf-release-version >}}" resources: requests: cpu: 50m diff --git a/content/ngf/waf-integration/get-started.md b/content/ngf/waf-integration/get-started.md index f3f6e94f0..a4ca4deb4 100644 --- a/content/ngf/waf-integration/get-started.md +++ b/content/ngf/waf-integration/get-started.md @@ -116,6 +116,11 @@ metadata: spec: waf: enable: true + kubernetes: + deployment: + container: + image: + repository: private-registry.nginx.com/nginx-gateway-fabric/nginx-plus-f5waf --- apiVersion: gateway.networking.k8s.io/v1 kind: Gateway @@ -136,7 +141,9 @@ spec: EOF ``` -{{< call-out "tip" >}} This creates a per-Gateway NginxProxy. You can also enable WAF for all Gateways at once using the GatewayClass-level NginxProxy or Helm values. See [Enable WAF on the NginxProxy]({{< ref "/ngf/waf-integration/overview.md#enable-waf-on-the-nginxproxy" >}}) for details, including custom WAF container images and additional settings. {{< /call-out >}} +{{< call-out "important" >}} The per-Gateway NginxProxy must specify the WAF-enabled NGINX Plus image (`nginx-plus-f5waf`). If you installed NGINX Gateway Fabric with an explicit NGINX Plus image (as shown in the [Helm install guide]({{< ref "/ngf/install/helm.md" >}})), that image is inherited by the per-Gateway NginxProxy through the [merging semantics]({{< ref "/ngf/how-to/data-plane-configuration.md#merging-semantics" >}}). The standard `nginx-plus` image does not include the WAF module, so you must override it here. {{< /call-out >}} + +{{< call-out "tip" >}} You can also enable WAF for all Gateways at once using the GatewayClass-level NginxProxy or Helm values. See [Enable WAF on the NginxProxy]({{< ref "/ngf/waf-integration/overview.md#enable-waf-on-the-nginxproxy" >}}) for details. {{< /call-out >}} --- diff --git a/content/ngf/waf-integration/overview.md b/content/ngf/waf-integration/overview.md index 57922bdd4..26705f789 100644 --- a/content/ngf/waf-integration/overview.md +++ b/content/ngf/waf-integration/overview.md @@ -59,8 +59,15 @@ metadata: spec: waf: enable: true + kubernetes: + deployment: + container: + image: + repository: private-registry.nginx.com/nginx-gateway-fabric/nginx-plus-f5waf ``` +{{< call-out "important" >}} The per-Gateway NginxProxy must specify the WAF-enabled NGINX Plus image (`nginx-plus-f5waf`). If you installed with an explicit NGINX Plus image, the standard `nginx-plus` image is inherited from the GatewayClass and does not include the WAF module. See [Supported container images]({{< ref "/ngf/overview/technical-specifications.md#supported-container-images" >}}) for the full list of available images. {{< /call-out >}} + ```yaml apiVersion: gateway.networking.k8s.io/v1 kind: Gateway @@ -81,11 +88,14 @@ spec: ### Enable WAF for all Gateways -To enable WAF globally, set `nginx.config.waf.enable` in your Helm values. This configures the GatewayClass-level `NginxProxy` that is created automatically at install time: +To enable WAF globally, set `nginx.config.waf.enable` and `nginx.image.repository` in your Helm values. This configures the GatewayClass-level `NginxProxy` that is created automatically at install time: ```yaml # values.yaml nginx: + image: + repository: private-registry.nginx.com/nginx-gateway-fabric/nginx-plus-f5waf + plus: true config: waf: enable: true @@ -94,6 +104,7 @@ nginx: ```shell helm upgrade --install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric \ --namespace nginx-gateway --create-namespace \ + --set nginx.imagePullSecret=nginx-plus-registry-secret \ -f values.yaml ``` From ce44f36ee8aec00bd20b71e60ffd57254778e2d3 Mon Sep 17 00:00:00 2001 From: Ciara Stacke <18287516+ciarams87@users.noreply.github.com> Date: Tue, 19 May 2026 12:30:24 +0100 Subject: [PATCH 3/3] Add WAF install tab to helm docs; refactor WAF docs --- content/ngf/install/helm.md | 26 +++++++++++++- content/ngf/waf-integration/get-started.md | 28 +++------------ content/ngf/waf-integration/overview.md | 40 ++++++---------------- 3 files changed, 40 insertions(+), 54 deletions(-) diff --git a/content/ngf/install/helm.md b/content/ngf/install/helm.md index a8634fac9..4c71756c0 100644 --- a/content/ngf/install/helm.md +++ b/content/ngf/install/helm.md @@ -22,7 +22,7 @@ To complete this guide, you will need: For a list of available images and their registries, see [Supported container images]({{< ref "/ngf/overview/technical-specifications.md#supported-container-images" >}}). -{{< call-out "important" >}} If you’d like to use NGINX Plus, some additional setup is also required: {{< /call-out >}} +{{< call-out "important" >}} If you’d like to use NGINX Plus or NGINX Plus with F5 WAF for NGINX, some additional setup is also required: {{< /call-out >}} {{< details summary="NGINX Plus JWT setup" >}} @@ -79,6 +79,18 @@ helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric --set nginx.im {{% /tab %}} +{{%tab name="NGINX Plus with WAF"%}} + +{{< call-out "note" >}} If applicable, replace the F5 Container registry `private-registry.nginx.com` with your internal registry, and replace `nginx-plus-registry-secret` with your Secret name containing the registry credentials. If your NGINX Plus JWT Secret has a different name than the default `nplus-license`, then define that name using the `nginx.usage.secretName` flag. {{< /call-out >}} + +To install the latest stable release of NGINX Gateway Fabric with F5 WAF for NGINX enabled globally across all Gateways, run the following command: + +```shell +helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric --set nginx.image.repository=private-registry.nginx.com/nginx-gateway-fabric/nginx-plus-f5waf --set nginx.plus=true --set nginx.config.waf.enable=true --set nginx.imagePullSecret=nginx-plus-registry-secret --create-namespace -n nginx-gateway +``` + +{{% /tab %}} + {{}} `ngf` is the name of the release, and can be changed to any name you want. This name is added as a prefix to the Deployment name. @@ -121,6 +133,18 @@ helm install ngf . --set nginx.image.repository=private-registry.nginx.com/nginx {{% /tab %}} +{{%tab name="NGINX Plus with WAF"%}} + +{{< call-out "note" >}} If applicable, replace the F5 Container registry `private-registry.nginx.com` with your internal registry, and replace `nginx-plus-registry-secret` with your Secret name containing the registry credentials. If your NGINX Plus JWT Secret has a different name than the default `nplus-license`, then define that name using the `nginx.usage.secretName` flag. {{< /call-out >}} + +To install the chart into the **nginx-gateway** namespace with F5 WAF for NGINX enabled globally across all Gateways, run the following command: + +```shell +helm install ngf . --set nginx.image.repository=private-registry.nginx.com/nginx-gateway-fabric/nginx-plus-f5waf --set nginx.plus=true --set nginx.config.waf.enable=true --set nginx.imagePullSecret=nginx-plus-registry-secret -n nginx-gateway +``` + +{{% /tab %}} + {{}} `ngf` is the name of the release, and can be changed to any name you want. This name is added as a prefix to the Deployment name. diff --git a/content/ngf/waf-integration/get-started.md b/content/ngf/waf-integration/get-started.md index a4ca4deb4..dcb04c543 100644 --- a/content/ngf/waf-integration/get-started.md +++ b/content/ngf/waf-integration/get-started.md @@ -18,7 +18,7 @@ For an overview of WAF concepts and architecture, see [F5 WAF for NGINX overview ## Before you begin -- [Install]({{< ref "/ngf/install/" >}}) NGINX Gateway Fabric with NGINX Plus. +- [Install]({{< ref "/ngf/install/helm.md" >}}) NGINX Gateway Fabric using the **NGINX Plus with WAF** tab. This sets the WAF-enabled NGINX Plus image and enables WAF globally. - Have a valid F5 WAF for NGINX subscription. F5 WAF for NGINX is a separate add-on to NGINX Plus and is not included with the NGINX Plus license. - Have NGINX Gateway Fabric configured with an `imagePullSecret` for the NGINX private container registry (`private-registry.nginx.com`), either through Helm values or deployment manifests. When a Gateway is deployed, NGINX Gateway Fabric automatically creates the registry secret in the Gateway's namespace with the naming convention `-nginx-. The bundle server Deployment in this guide references the same secret for pulling the F5 WAF compiler image, be sure to update the secret name to match your environment. @@ -103,36 +103,18 @@ EOF --- -## Create the Gateway with WAF enabled +## Create the Gateway -Create an `NginxProxy` with `waf.enable: true` and a Gateway that references it. This instructs NGINX Gateway Fabric to deploy the WAF sidecar containers alongside the NGINX Pod for this Gateway: +Create a Gateway. Because you installed using the **NGINX Plus with WAF** tab, WAF is already enabled globally — NGINX Gateway Fabric automatically deploys the WAF sidecar containers alongside the NGINX Pod: ```yaml kubectl apply -f - <}} The per-Gateway NginxProxy must specify the WAF-enabled NGINX Plus image (`nginx-plus-f5waf`). If you installed NGINX Gateway Fabric with an explicit NGINX Plus image (as shown in the [Helm install guide]({{< ref "/ngf/install/helm.md" >}})), that image is inherited by the per-Gateway NginxProxy through the [merging semantics]({{< ref "/ngf/how-to/data-plane-configuration.md#merging-semantics" >}}). The standard `nginx-plus` image does not include the WAF module, so you must override it here. {{< /call-out >}} - -{{< call-out "tip" >}} You can also enable WAF for all Gateways at once using the GatewayClass-level NginxProxy or Helm values. See [Enable WAF on the NginxProxy]({{< ref "/ngf/waf-integration/overview.md#enable-waf-on-the-nginxproxy" >}}) for details. {{< /call-out >}} +{{< call-out "note" >}} If you installed with the standard NGINX Plus image and need to enable WAF on a specific Gateway, see [Enable WAF per Gateway]({{< ref "/ngf/waf-integration/overview.md#enable-waf-per-gateway" >}}). {{< /call-out >}} --- diff --git a/content/ngf/waf-integration/overview.md b/content/ngf/waf-integration/overview.md index 26705f789..5762b3b17 100644 --- a/content/ngf/waf-integration/overview.md +++ b/content/ngf/waf-integration/overview.md @@ -42,14 +42,22 @@ WAF is enabled by setting `waf.enable: true` on an `NginxProxy` resource. This i You can enable WAF at two levels: -- **Per Gateway** — Create an `NginxProxy` and reference it from a Gateway's `spec.infrastructure.parametersRef`. Only that Gateway gets WAF sidecars. - **All Gateways** — Set WAF on the GatewayClass-level `NginxProxy` so that every Gateway managed by this NGINX Gateway Fabric instance gets WAF sidecars by default. A per-Gateway `NginxProxy` can override this (for example, to disable WAF on a specific Gateway). +- **Per Gateway** — Create an `NginxProxy` and reference it from a Gateway's `spec.infrastructure.parametersRef`. Only that Gateway gets WAF sidecars. For details on how GatewayClass and Gateway-level NginxProxy settings are merged, see [Data plane configuration]({{< ref "/ngf/how-to/data-plane-configuration.md" >}}). +### Enable WAF for all Gateways + +To enable WAF at install time use the **NGINX Plus with WAF** tab in the [Helm install guide]({{< ref "/ngf/install/helm.md" >}}). This sets the WAF-enabled NGINX Plus image (`nginx-plus-f5waf`) and enables WAF on the GatewayClass-level `NginxProxy`, so every Gateway gets WAF sidecars by default. + +To disable WAF for a specific Gateway, create a per-Gateway `NginxProxy` with `waf.enable: false` and reference it from that Gateway. + +{{< call-out "note" >}} For additional WAF-related NginxProxy settings — including `disableCookieSeed`, `bundleFailOpen`, and custom WAF container images — see [Configure WAF settings]({{< ref "/ngf/waf-integration/configuration.md" >}}). {{< /call-out >}} + ### Enable WAF per Gateway -Create an `NginxProxy` and reference it from your Gateway: +If you installed with the standard NGINX Plus image and want WAF on a specific Gateway only, create a per-Gateway `NginxProxy`. You must also set the NGINX image to `nginx-plus-f5waf`, since the standard `nginx-plus` image inherited from the GatewayClass does not include the WAF module: ```yaml apiVersion: gateway.nginx.org/v1alpha2 @@ -66,8 +74,6 @@ spec: repository: private-registry.nginx.com/nginx-gateway-fabric/nginx-plus-f5waf ``` -{{< call-out "important" >}} The per-Gateway NginxProxy must specify the WAF-enabled NGINX Plus image (`nginx-plus-f5waf`). If you installed with an explicit NGINX Plus image, the standard `nginx-plus` image is inherited from the GatewayClass and does not include the WAF module. See [Supported container images]({{< ref "/ngf/overview/technical-specifications.md#supported-container-images" >}}) for the full list of available images. {{< /call-out >}} - ```yaml apiVersion: gateway.networking.k8s.io/v1 kind: Gateway @@ -86,31 +92,7 @@ spec: protocol: HTTP ``` -### Enable WAF for all Gateways - -To enable WAF globally, set `nginx.config.waf.enable` and `nginx.image.repository` in your Helm values. This configures the GatewayClass-level `NginxProxy` that is created automatically at install time: - -```yaml -# values.yaml -nginx: - image: - repository: private-registry.nginx.com/nginx-gateway-fabric/nginx-plus-f5waf - plus: true - config: - waf: - enable: true -``` - -```shell -helm upgrade --install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric \ - --namespace nginx-gateway --create-namespace \ - --set nginx.imagePullSecret=nginx-plus-registry-secret \ - -f values.yaml -``` - -Every Gateway attached to this GatewayClass will have WAF sidecars deployed. To disable WAF for a specific Gateway, create a per-Gateway `NginxProxy` with `waf.enable: false` and reference it from that Gateway. - -{{< call-out "note" >}} For additional WAF-related NginxProxy settings — including `disableCookieSeed`, `bundleFailOpen`, and custom WAF container images — see [Configure WAF settings]({{< ref "/ngf/waf-integration/configuration.md" >}}). {{< /call-out >}} +For the full list of available images, see [Supported container images]({{< ref "/ngf/overview/technical-specifications.md#supported-container-images" >}}). ---