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..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..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 ```