diff --git a/content/ngf/waf-integration/configuration.md b/content/ngf/waf-integration/configuration.md index b2246e8e2..c87f07b26 100644 --- a/content/ngf/waf-integration/configuration.md +++ b/content/ngf/waf-integration/configuration.md @@ -106,9 +106,9 @@ policySource: ## Configure PLM storage access -When you use the `PLM` policy type, NGINX Gateway Fabric fetches compiled bundles from PLM's in-cluster storage. Access to that storage is configured once, cluster-wide, at install time — it is not set per `WAFPolicy`. This configuration applies to all `WAFPolicy` resources that use `type: PLM`. +When you use the `PLM` policy type, NGINX Gateway Fabric fetches compiled bundles from PLM's in-cluster storage. Storage access is configured once, cluster-wide, at install time — not per `WAFPolicy`. This configuration applies to all `WAFPolicy` resources that use `type: PLM`. -{{< call-out "note" >}} This section covers only the NGINX Gateway Fabric side of PLM configuration. Installing the PLM system and authoring `APPolicy`/`APLogConf` resources are covered in the [F5 WAF PLM documentation]({{< ref "/waf/" >}}). {{< /call-out >}} +{{< call-out "note" >}} This section covers the NGINX Gateway Fabric side of PLM configuration only. For installing the PLM system and authoring `APPolicy`/`APLogConf` resources, see the [F5 WAF PLM documentation]({{< ref "/waf/" >}}). {{< /call-out >}} ### Helm values @@ -136,11 +136,11 @@ The equivalent control plane CLI flags for manifest installs are: | `--plm-storage-client-ssl-secret` | Secret containing the client certificate and key (`tls.crt`/`tls.key`) | No | | `--plm-storage-skip-verify` | Skip TLS certificate verification (testing only) | No | -Secret names may include a namespace prefix (`namespace/name`). If no namespace is given, the NGINX Gateway Fabric control plane namespace is assumed. +Secret names may include a namespace prefix (`namespace/name`). If you don't include a namespace, the NGINX Gateway Fabric control plane namespace is used. ### Credentials Secret -The credentials Secret is created automatically by the PLM installation. It contains the S3 secret access key in the `seaweedfs_admin_secret` field; the access key ID is `admin` by default: +The PLM installation creates the credentials Secret automatically. It contains the S3 secret access key in the `seaweedfs_admin_secret` field; the access key ID is `admin` by default: ```yaml apiVersion: v1 @@ -153,15 +153,15 @@ data: seaweedfs_admin_secret: ``` -NGINX Gateway Fabric watches the PLM credentials and TLS Secrets and rebuilds its storage client when they change, so credentials can be rotated without restarting the pod. +NGINX Gateway Fabric watches the PLM credentials and TLS Secrets and rebuilds its storage client when they change. You can rotate credentials without restarting the pod. -{{< call-out "caution" >}} For production, always use HTTPS with TLS verification by providing `caSecretName`. Enable mutual TLS with `clientSSLSecretName` for high-security environments. Never set `insecureSkipVerify: true` (or `--plm-storage-skip-verify=true`) in production. {{< /call-out >}} +{{< call-out "caution" >}} For production, always use HTTPS with TLS verification by providing `caSecretName`. Add `clientSSLSecretName` for mutual TLS in high-security environments. Never set `insecureSkipVerify: true` (or `--plm-storage-skip-verify=true`) in production. {{< /call-out >}} --- ## Configure the WAF cookie seed -When WAF is enabled, NGINX Gateway Fabric automatically sets the `app_protect_cookie_seed` NGINX directive to a stable value derived from the Gateway's UID. This ensures that WAF session cookies issued by one NGINX replica can be validated by any other replica in the same deployment. Without this, each replica generates its own random seed at startup, which causes cross-replica cookie validation failures. +When WAF is enabled, NGINX Gateway Fabric sets the `app_protect_cookie_seed` NGINX directive to a stable value derived from the Gateway's UID. This lets any NGINX replica validate WAF session cookies issued by any other replica in the same deployment. Without this, each replica generates its own random seed at startup, causing cross-replica cookie validation failures. If you have pre-compiled the cookie seed into your WAF policy bundles using the [compiler global settings]({{< ref "/waf/configure/compiler.md" >}}), disable the automatic cookie seed in the NginxProxy CRD to avoid conflicting with the compiled-in value: @@ -253,11 +253,11 @@ policySource: The `expectedChecksum` must be a 64-character hexadecimal SHA-256 digest. -{{< call-out "note" >}} `verifyChecksum` and `expectedChecksum` are mutually exclusive. You can use one or the other on the same policy source, but not both. {{< /call-out >}} +{{< call-out "note" >}} `verifyChecksum` and `expectedChecksum` are mutually exclusive. Use one or the other on the same policy source, but not both. {{< /call-out >}} ### PLM source -For the `PLM` policy type, integrity verification is automatic and requires no configuration. NGINX Gateway Fabric verifies the downloaded bundle against `status.bundle.sha256` from the referenced `APPolicy` or `APLogConf` resource. A mismatch prevents the bundle from being deployed and sets `Programmed=False` with reason `IntegrityError`. +For the `PLM` policy type, integrity verification is automatic — no configuration needed. NGINX Gateway Fabric verifies the downloaded bundle against `status.bundle.sha256` from the referenced `APPolicy` or `APLogConf` resource. A mismatch prevents the bundle from being deployed and sets `Programmed=False` with reason `IntegrityError`. --- diff --git a/content/ngf/waf-integration/overview.md b/content/ngf/waf-integration/overview.md index e3b4b37d6..fd7e1b5c7 100644 --- a/content/ngf/waf-integration/overview.md +++ b/content/ngf/waf-integration/overview.md @@ -108,7 +108,7 @@ WAF policies must be compiled before they can be applied. Compilation takes a JS ### Source types -The following policy source types are supported, selected via the `spec.type` field on the `WAFPolicy` resource: +Set the source type using the `spec.type` field on the `WAFPolicy` resource: | Type | Description | |--------|---------------------------------------------------------------------------------------------------| @@ -117,13 +117,13 @@ The following policy source types are supported, selected via the `spec.type` fi | `HTTP` | Direct HTTP/HTTPS URL to a compiled bundle file | | `PLM` | Policy Lifecycle Management — `APPolicy`/`APLogConf` CRDs, fetched from in-cluster storage | -The `NIM`, `N1C`, and `HTTP` source types reference an externally compiled bundle through `policySource` (and `logSource` for log profiles), and detect updates by polling. The `PLM` source type is Kubernetes-native and event-driven: it references `APPolicy` and `APLogConf` custom resources through `policyRef` (and `logRef`), and requires no polling. See [PLM (Policy Lifecycle Management)](#plm-policy-lifecycle-management) below. +The `NIM`, `N1C`, and `HTTP` source types reference an externally compiled bundle through `policySource` (and `logSource` for log profiles). They detect updates by polling. The `PLM` source type is Kubernetes-native and event-driven: it references `APPolicy` and `APLogConf` custom resources through `policyRef` (and `logRef`), and doesn't require polling. See [PLM (Policy Lifecycle Management)](#plm-policy-lifecycle-management) below. For details on configuring each source type, see [Configure policy sources]({{< ref "/ngf/waf-integration/policy-sources.md" >}}). ### PLM (Policy Lifecycle Management) -Policy Lifecycle Management (PLM) is a Kubernetes-native policy source. Instead of pointing NGINX Gateway Fabric at an externally compiled bundle, you define your WAF security posture as `APPolicy` and `APLogConf` custom resources in the cluster. The PLM controller watches these resources, compiles them automatically, and stores the resulting bundles in in-cluster S3-compatible storage. NGINX Gateway Fabric then fetches the bundles from that storage and deploys them to the data plane. +Policy Lifecycle Management (PLM) is a Kubernetes-native policy source. Instead of pointing NGINX Gateway Fabric at an externally compiled bundle, you define your WAF security posture as `APPolicy` and `APLogConf` custom resources in the cluster. The PLM controller watches these resources, compiles them automatically, and stores the resulting bundles in in-cluster S3-compatible storage. NGINX Gateway Fabric fetches the bundles from that storage and deploys them to the data plane. The following table summarizes how PLM differs from the HTTP, NGINX Instance Manager, and NGINX One Console source types: @@ -145,11 +145,11 @@ NGINX Gateway Fabric detects the ready status via watch → fetches the bundle f in-cluster storage → deploys to the data plane ``` -Subsequent changes to an `APPolicy` or `APLogConf` spec trigger recompilation and an automatic re-fetch — no polling and no change to the `WAFPolicy` resource are required. +Changes to an `APPolicy` or `APLogConf` spec trigger recompilation and an automatic re-fetch — no polling required, and no change to the `WAFPolicy` resource. -When a `WAFPolicy` references an `APPolicy` or `APLogConf` in a different namespace, a [ReferenceGrant](https://gateway-api.sigs.k8s.io/api-types/referencegrant/) is required in the target namespace to permit the reference. +When a `WAFPolicy` references an `APPolicy` or `APLogConf` in a different namespace, create a [ReferenceGrant](https://gateway-api.sigs.k8s.io/api-types/referencegrant/) in the target namespace to permit the reference. -{{< call-out "note" >}} PLM requires the PLM system to be installed in the cluster, and requires PLM storage access to be configured on NGINX Gateway Fabric at install time. For authoring `APPolicy`/`APLogConf` resources and installing PLM, see the [F5 WAF PLM documentation]({{< ref "/waf/" >}}). For NGINX Gateway Fabric configuration, see [Configure PLM storage access]({{< ref "/ngf/waf-integration/configuration.md#configure-plm-storage-access" >}}). {{< /call-out >}} +{{< call-out "note" >}} PLM requires the PLM system to be installed in the cluster and PLM storage access to be set up on NGINX Gateway Fabric at install time. For authoring `APPolicy`/`APLogConf` resources and installing PLM, see the [F5 WAF PLM documentation]({{< ref "/waf/" >}}). For NGINX Gateway Fabric configuration, see [Configure PLM storage access]({{< ref "/ngf/waf-integration/configuration.md#configure-plm-storage-access" >}}). {{< /call-out >}} --- diff --git a/content/ngf/waf-integration/policy-sources.md b/content/ngf/waf-integration/policy-sources.md index 90978b207..e19f3b021 100644 --- a/content/ngf/waf-integration/policy-sources.md +++ b/content/ngf/waf-integration/policy-sources.md @@ -15,7 +15,7 @@ Before configuring a policy source, ensure that WAF is [enabled on the NginxProx --- -## NGINX Instance Manager (NGINX Instance Manager) +## NGINX Instance Manager Use this option when you manage WAF policies through NGINX Instance Manager. For details on creating and compiling policies in NGINX Instance Manager, see [How WAF policy management works]({{< ref "/nim/waf-integration/overview.md" >}}) and [Create a security policy bundle]({{< ref "/nim/waf-integration/policies-and-logs/bundles/create-bundle.md" >}}). @@ -222,21 +222,21 @@ Use this option when you manage WAF policies as Kubernetes resources with Policy Unlike the other source types, PLM is Kubernetes-native and event-driven: -- Policies and log profiles are referenced with `policyRef.apPolicyRef` and `logRef.apLogConfRef` instead of `policySource` and `logSource`. -- Updates are detected through a Kubernetes watch, so [polling]({{< ref "/ngf/waf-integration/configuration.md#configure-automatic-policy-updates-polling" >}}) does not apply. -- No per-`WAFPolicy` credentials Secret is needed. Access to PLM storage is configured once, cluster-wide, at install time. +- Reference policies and log profiles with `policyRef.apPolicyRef` and `logRef.apLogConfRef` instead of `policySource` and `logSource`. +- Updates are detected through a Kubernetes watch, so [polling]({{< ref "/ngf/waf-integration/configuration.md#configure-automatic-policy-updates-polling" >}}) doesn't apply. +- No per-`WAFPolicy` credentials Secret is needed. PLM storage access is set up once, cluster-wide, at install time. For a comparison of PLM with the other source types, see [PLM (Policy Lifecycle Management)]({{< ref "/ngf/waf-integration/overview.md#plm-policy-lifecycle-management" >}}). **Before you begin:** -- The PLM system must be installed in the cluster, and PLM storage access must be configured on NGINX Gateway Fabric. See [Configure PLM storage access]({{< ref "/ngf/waf-integration/configuration.md#configure-plm-storage-access" >}}). +- The PLM system must be installed in the cluster, and PLM storage access must be set up on NGINX Gateway Fabric. See [Configure PLM storage access]({{< ref "/ngf/waf-integration/configuration.md#configure-plm-storage-access" >}}). **Workflow:** 1. Create your `APPolicy` (and optionally `APLogConf`) resources. The PLM controller compiles them and sets `status.bundle.state` to `ready` when the bundle is available. 2. Create a `WAFPolicy` with `type: PLM` that references the `APPolicy` by name and namespace. -3. NGINX Gateway Fabric watches the referenced resources and deploys the bundle once it is `ready`. Later changes to the `APPolicy` or `APLogConf` spec trigger recompilation and an automatic re-fetch — no change to the `WAFPolicy` is required. +3. NGINX Gateway Fabric watches the referenced resources and deploys the bundle when it's `ready`. Later changes to the `APPolicy` or `APLogConf` spec trigger recompilation and an automatic re-fetch — no change to the `WAFPolicy` is required. ### Create namespaces @@ -270,7 +270,7 @@ spec: EOF ``` -Without a matching `ReferenceGrant`, the `WAFPolicy` is rejected with `ResolvedRefs=False` and reason `RefNotPermitted`. See [Troubleshoot WAFPolicy status]({{< ref "/ngf/waf-integration/troubleshooting.md" >}}). +Without a matching `ReferenceGrant`, the `WAFPolicy` is rejected with `ResolvedRefs=False` and reason `RefNotPermitted`. See [Troubleshoot WAFPolicy status]({{< ref "/ngf/waf-integration/troubleshooting.md" >}}) for details. ### Create the APPolicy and APLogConf resources @@ -323,7 +323,7 @@ EOF Wait until both resources report `status.bundle.state: ready` before referencing them from a `WAFPolicy`. -{{< call-out "note" >}} These examples are a starting point. For the full `APPolicy` and `APLogConf` specifications and additional configuration options, see the [F5 WAF PLM documentation]({{< ref "/waf/" >}}). {{< /call-out >}} +{{< call-out "note" >}} These examples are a starting point. For the full `APPolicy` and `APLogConf` specifications, see the [F5 WAF PLM documentation]({{< ref "/waf/" >}}). {{< /call-out >}} ### Create a gateway-level WAFPolicy @@ -393,7 +393,7 @@ spec: EOF ``` -This example reuses the `attack-signatures` policy for the route-level override. In practice, create a separate `APPolicy` (and, if needed, `APLogConf`) with the stricter posture you want for this route, then reference it here. This policy overrides the gateway-level policy for the `customers` route only. Any other routes attached to the gateway continue to use the gateway-level policy. +This example reuses the `attack-signatures` policy for the route-level override. In practice, create a separate `APPolicy` (and, if needed, `APLogConf`) with the stricter posture you want for this route, then reference it here. This policy overrides the gateway-level policy for the `customers` route only. Other routes attached to the gateway continue to use the gateway-level policy. --- diff --git a/content/ngf/waf-integration/troubleshooting.md b/content/ngf/waf-integration/troubleshooting.md index fa1724803..b718cd31a 100644 --- a/content/ngf/waf-integration/troubleshooting.md +++ b/content/ngf/waf-integration/troubleshooting.md @@ -48,15 +48,15 @@ Use `kubectl describe wafpolicy ` to inspect status conditions. ### `FetchError` with HTTP 403 -The credentials Secret is either missing, contains the wrong keys, or the credentials are invalid. Verify the Secret exists in the same namespace as the `WAFPolicy` and that the keys match the authentication method (`username`/`password` for Basic Auth, `token` for Bearer/APIToken). +The credentials Secret is missing, contains the wrong keys, or the credentials are invalid. Verify the Secret exists in the same namespace as the `WAFPolicy`. Confirm the keys match the authentication method (`username`/`password` for Basic Auth, `token` for Bearer/APIToken). ### `FetchError` with HTTP 404 on NGINX Instance Manager or NGINX One Console -The referenced policy was not found or has not been compiled yet. For NGINX Instance Manager, verify that compilation succeeded in the NGINX Instance Manager console before creating the `WAFPolicy`. For NGINX One Console, NGINX Gateway Fabric triggers compilation if no bundle exists, and a 404 after initial setup may indicate the policy was deleted in NGINX One Console. +The referenced policy wasn't found or hasn't been compiled yet. For NGINX Instance Manager, verify that compilation succeeded in the NGINX Instance Manager console before creating the `WAFPolicy`. For NGINX One Console, NGINX Gateway Fabric triggers compilation if no bundle exists. A 404 after initial setup may mean the policy was deleted in NGINX One Console. ### `InvalidRef` on a PLM policy: `APPolicy` not ready -For `type: PLM`, NGINX Gateway Fabric only fetches a bundle once the referenced `APPolicy` (or `APLogConf`) reports `status.bundle.state: ready`. While PLM is still compiling, the `ResolvedRefs` condition is `False` with reason `InvalidRef`: +For `type: PLM`, NGINX Gateway Fabric only fetches a bundle after the referenced `APPolicy` (or `APLogConf`) reports `status.bundle.state: ready`. While PLM is still compiling, the `ResolvedRefs` condition is `False` with reason `InvalidRef`: ```text - Type: ResolvedRefs @@ -69,7 +69,7 @@ Verify the `APPolicy` exists and that PLM has finished compiling it: `kubectl ge ### `RefNotPermitted` on a PLM policy: missing `ReferenceGrant` -When a `WAFPolicy` references an `APPolicy` or `APLogConf` in a different namespace, a `ReferenceGrant` must exist in the target namespace: +When a `WAFPolicy` references an `APPolicy` or `APLogConf` in a different namespace, a `ReferenceGrant` must exist in the target namespace to allow the reference: ```text - Type: ResolvedRefs @@ -78,11 +78,11 @@ When a `WAFPolicy` references an `APPolicy` or `APLogConf` in a different namesp Message: cross-namespace reference to APLogConf namespace/name not permitted by ReferenceGrant ``` -Create a `ReferenceGrant` in the target namespace that allows `WAFPolicy` resources from the source namespace to reference the `APPolicy`/`APLogConf` Kinds. See [Cross-namespace references]({{< ref "/ngf/waf-integration/policy-sources.md#cross-namespace-references" >}}). +Create a `ReferenceGrant` in the target namespace that allows `WAFPolicy` resources from the source namespace to reference the `APPolicy`/`APLogConf` kinds. See [Cross-namespace references]({{< ref "/ngf/waf-integration/policy-sources.md#cross-namespace-references" >}}). ### `Pending` -The bundle has never been successfully fetched. If `bundleFailOpen` is `false` (the default), the NGINX configuration push is withheld for this Gateway. If `bundleFailOpen` is `true`, traffic flows without WAF protection. +The bundle has never been successfully fetched. If `bundleFailOpen` is `false` (the default), NGINX Gateway Fabric withholds the configuration push for this Gateway. If `bundleFailOpen` is `true`, traffic flows without WAF protection. Check the `Programmed` condition message for the last fetch error. Common causes include network connectivity issues, incorrect URLs, or authentication failures. Verify the policy source URL and credentials Secret.