diff --git a/content/ngf/install/helm.md b/content/ngf/install/helm.md index 23259bd2d..4c71756c0 100644 --- a/content/ngf/install/helm.md +++ b/content/ngf/install/helm.md @@ -20,7 +20,9 @@ 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. -{{< call-out "important" >}} If you’d like to use NGINX Plus, some additional setup is also required: {{< /call-out >}} +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 or NGINX Plus with F5 WAF for NGINX, some additional setup is also required: {{< /call-out >}} {{< details summary="NGINX Plus JWT setup" >}} @@ -77,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. @@ -119,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/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..4a826d702 100644 --- a/content/ngf/overview/technical-specifications.md +++ b/content/ngf/overview/technical-specifications.md @@ -45,6 +45,54 @@ 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 + +| Name | Base image | Image | Architectures | +|-----------------|----------------------------|--------------------------------------------------------------------|----------------| +| 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" >}}). + +| 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..f6aa65c3c 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. + +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: + +- **`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: "{{< ngf-waf-release-version >}}" + resources: + requests: + cpu: 100m + memory: 128Mi + limits: + cpu: "1" + memory: 1Gi + configManager: + image: + repository: registry.example.com/nap/waf-config-mgr + tag: "{{< ngf-waf-release-version >}}" + 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: "{{< ngf-waf-release-version >}}" + resources: + requests: + cpu: 100m + memory: 128Mi + configManager: + image: + repository: registry.example.com/nap/waf-config-mgr + tag: "{{< ngf-waf-release-version >}}" + 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" >}}) diff --git a/content/ngf/waf-integration/get-started.md b/content/ngf/waf-integration/get-started.md index f3f6e94f0..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,31 +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 - <}} 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 "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 57922bdd4..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 @@ -59,6 +67,11 @@ metadata: spec: waf: enable: true + kubernetes: + deployment: + container: + image: + repository: private-registry.nginx.com/nginx-gateway-fabric/nginx-plus-f5waf ``` ```yaml @@ -79,27 +92,7 @@ spec: protocol: HTTP ``` -### 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: - -```yaml -# values.yaml -nginx: - config: - waf: - enable: true -``` - -```shell -helm upgrade --install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric \ - --namespace nginx-gateway --create-namespace \ - -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" >}}). ---