docs: Add PLM policy source tutorial and copy edits for NGF WAF integration by travisamartin · Pull Request #2197 · nginx/documentation

travisamartin · 2026-08-10T18:05:27Z

What this PR does

Adds documentation for using Policy Lifecycle Management (PLM) as a WAF policy source in NGINX Gateway Fabric, and applies style guide copy edits across the NGF WAF integration docs.

New files

`content/includes/waf/plm-deploy-infrastructure.md`

A shared include covering PLM backend deployment. Consumable by both the NGINX Gateway Fabric and NGINX Ingress Controller tutorials without modification. Covers:

PLM architecture: Policy Controller → gRPC → NAP compiler service → SeaweedFS/S3
Installing the four required CRDs (appolicies, aplogconfs, apusersigs, apsignatures)
Creating the registry pull secret
Helm install with plm-values.yaml (uses the version-waf-policy-controller shortcode for the chart version)
Verification: SeaweedFS backend readiness, Policy Controller pod, expected 8-pod output, CRD confirmation

`content/includes/waf/plm-define-policy-bundle-method.md`

A shared include covering the precompiled-bundle policy definition method. Product-neutral and consumable by both tutorials. Covers:

Referencing a .tgz bundle from an artifact registry
bundle.state values (pending, processing, ready, invalid)
isCompiled: false behavior
Correct update trigger: re-apply the APPolicy resource (the Policy Controller does not poll)

`content/ngf/waf-integration/get-started-plm.md`

New end-to-end tutorial for protecting traffic with F5 WAF for NGINX using PLM in NGINX Gateway Fabric. Covers:

Deploying the PLM infrastructure (pulls in the shared include above)
Connecting NGINX Gateway Fabric to in-cluster PLM storage
Defining WAF policies using three methods: inline, Git-reference, and precompiled bundle
Deploying a Gateway and attaching a WAFPolicy
Configuring HTTPRoutes
Validating policy compilation and application
Testing WAF enforcement with a sample application
Applying a route-level data guard override

Updated files

`content/ngf/waf-integration/overview.md`

`content/ngf/waf-integration/policy-sources.md`

`content/ngf/reference/cli-help.md` (PLM storage flags)

Copy edits applying the F5 style guide:

Replaced em dashes with commas, periods, colons, or parentheses
Replaced Latin abbreviations (via → through/using)
Replaced since (causal) with because
Replaced ensure with make sure
Preferred contractions per Modern Voice guidelines
Recasted product name possessives (PLM's, NGINX Agent's)
Fixed placeholder casing (<namespace>/ → <NAMESPACE>/)
Replaced non-RFC-5737 IP address (10.96.20.187 → 192.0.2.1) across six files
Updated f5-description in policy-sources.md to include PLM
Removed redundant heading in policy-sources.md

Open questions for SME review

Registry credentials: the install covers JWT, certificate, and key. Confirm whether a separate registry token is also required and where it is passed.
Private CA for bundle server: confirm the Helm value or config mechanism for trusting a private CA when using the precompiled-bundle method.

github-actions · 2026-08-10T18:07:16Z

✅ Deploy Preview will be available once build job completes!

Name	Link
😎 Deploy Preview	https://frontdoor-test-docs.nginx.com/previews/docs/2197/

sjberman · 2026-08-10T19:56:02Z

We probably need some consistency brought into this doc. In NGF, we avoid placeholder values as much as possible (except for sensitive info) so that a user can just copy/paste commands. The PLM docs don't follow this right now.

Helm installs CRDs on first install automatically, so the manual kubectl apply step is only required when upgrading. Relocate it from the top of the install flow (where it misled new users) to a new "Update the CRDs" section after "Verify the deployment". Add a note clarifying that the step can be skipped on a fresh install. Remove the redundant CRD verification block from the upgrade section, as the verify section already confirms CRD presence. Also pins the GitHub raw URL to the versioned tag using the version-waf-policy-controller shortcode, replacing the previous reference to main.

- Rewrite registry pull secret steps to store the JWT in a Kubernetes Secret before use, avoiding inline JWT exposure - Add JWT download steps to get-started-plm.md prerequisites, reorder prereqs so JWT comes before the registry Secret - Copy edit download-jwt.md include: active voice in call-out, bold UI labels separated, update f5-files consumer list

- Add content/includes/waf/plm-prerequisites.md with PLM-specific prerequisites (StorageClass, Helm, JWT) and SeaweedFS storage defaults (embedded S3 store, default pod topology, credential Secret, HTTP-by-default note) - Restructure get-started-plm.md Before you begin: add PLM prerequisites subsection, add Example values H3 - Copy edit get-started-plm.md: fix causal 'since' → 'because', remove hedge ('should show'), split two-action step, rewrite passive results, tighten team-ownership callouts, fix directional reference, fix 'this guide' → 'this tutorial' - Copy edit plm-define-policy-bundle-method.md: use contraction ('doesn't poll')

The PLM chart does not generate TLS certificates. If certificates.enabled is set to true in the seaweedfsOperatorConfig, all five Secrets (CA, master, volume, filer, client) must be pre-created before running helm upgrade --install. Missing Secrets cause SeaweedFS pods to fail on mount. Add an optional TLS subsection to the 'Install the Policy Controller' section that: - States TLS is off by default - Shows the certificates block with the five secretName keys - Warns explicitly that the chart does not generate certificates - Provides kubectl create secret commands for each required Secret - Explains the PKI prerequisite Resolves feedback from code review.

The SeaweedFS operator deployment becomes Available before it reconciles the SeaweedFS CR and creates the SeaweedFS pods. This means kubectl wait --selector app.kubernetes.io/name=seaweedfs can exit immediately with no matches (and therefore an error) during the window between the operator being ready and the pods being created. Replace the two-step wait with a polling loop that retries kubectl wait every 5 seconds until either all SeaweedFS pods are Ready or a 300s timeout is exceeded.

- Add '#### Install the chart' heading before the helm repo add / helm upgrade commands to visually separate them from the optional TLS subsection. Without this heading, the install commands appeared to be continuation content of the TLS section rather than a step for all readers. - Replace inline skip note on '### Update the CRDs' with a note call-out so the upgrade-only scope is the first thing readers see before the imperative content.

@ciarams87

Move the sample app deployment, security logging configuration, and APPolicy inline/Git-reference definitions from get-started-plm.md into product-agnostic shared includes so NIC can reuse them: - plm-sample-app.md: customers and orders Deployment/Service manifests - plm-configure-logging.md: security namespace and APLogConf definition - plm-define-policy-inline-git.md: APPolicy inline and Git-reference methods The ReferenceGrant block stays inline in the NGF tutorial — NIC does not use ReferenceGrant. The precompiled-bundle method remains in the existing plm-define-policy-bundle-method.md include. Addresses review comment by @ciarams87 (r3756532202).

NIC tutorials have not been created yet. Remove the placeholder content/nic/waf-integration/get-started-plm.md f5-files entry from all five PLM includes. These will be restored when the NIC tutorial is written as part of the NIC work.

@ohad-perets

Add five deploy-time failure scenarios from SME review by @ohad-perets (r3769976191) to plm-deploy-infrastructure.md: - ImagePullBackOff: bad/expired JWT or line break in token - Policy Controller Init:0/1: SeaweedFS not ready, PVCs pending - SeaweedFS pods Pending: no default StorageClass - APPolicy invalid after enabling TLS: orphaned objects in storage - Helm ClusterRole conflict: duplicate PLM installation Also adds the Policy Controller log command as the primary diagnostic path, with a note that containers are distroless (kubectl exec unavailable). The APPolicy certificate error (x509: unknown authority) is placed in plm-define-policy-bundle-method.md as it only applies to the precompiled-bundle method, not general deployment. Addresses review comment by @ciarams87 and @ohad-perets (r3769976191).

Apply F5 style guide to troubleshooting content added in the previous commit: - Convert bold symptom labels to #### subheadings (bold.md) - Rename heading from gerund to imperative (headings.md) - Rewrite fragment topic sentences (paragraph-structure.md) - Reorder conditional sentences: condition before instruction (conditional-sentences.md) - Tighten passive constructions to active imperative (active-voice.md) - Split sentences exceeding the 25-word conceptual limit (sentence-length.md) - Replace contractions withheld by ASD-STE100 (contractions.md) - Drop hedge phrase 'Note that' (modern-voice.md) - Tighten Note in plm-define-policy-bundle-method.md: split long sentence, remove 'must be able to'

Merge plm-define-policy-inline-git.md and plm-define-policy-bundle-method.md into a single plm-define-policy-methods.md include that wraps all three policy definition methods (Inline, Git reference, Precompiled bundle) in a tabs shortcode. Hugo tab shortcodes cannot span include boundaries, so separate includes cannot be tabbed from a parent template. Consolidating into one include lets the tabbed UI render correctly while keeping the content reusable for the NIC tutorial. The ReferenceGrant block remains inline in get-started-plm.md after the include, as it is NGF-specific and does not belong in a shared include.

Convert the five symptom-based troubleshooting items in the PLM infrastructure include from subheadings to {{< details >}} expandos. Readers can scan symptom labels and expand only the relevant one. The 'Check the Policy Controller logs' subsection stays open as a universal diagnostic step that applies to all scenarios.

The two kubectl apply heredocs in the Git-reference tab contained $ref: fields. Using unquoted <<EOF caused the shell to expand $ref as an empty variable, corrupting the YAML. Changed both to <<'EOF' to pass content literally. All other heredocs in the PLM includes and tutorial contain no $ fields that require expansion, so their unquoted <<EOF is correct.

Apply style guide placeholder rules (all-caps, angle brackets, PATH/TO/ for paths): - plm-prerequisites.md: <release> -> <RELEASE> - plm-deploy-infrastructure.md: <PATH_TO_*> -> <PATH/TO/*> for all five TLS certificate/key placeholders and the prose reference - get-started-plm.md: <nginx-pod-name> -> <NGINX_POD_NAME>

- Moved the skip-logging note above the include so readers see it before deciding whether to continue with the section - Replaced vague 'in the next steps' with a direct link to the specific WAFPolicy section where securityLogs is configured

- configuration.md: document logRef.apLogConfRef as the PLM equivalent of logSource - troubleshooting.md: add RefNotPermitted condition and note PLM APPolicy/APLogConf refs in ResolvedRefs/InvalidRef - get-started-plm.md: add inline PLM-side compile-failure diagnosis (bundle.state table + Policy Controller logs), link CLI flags and storage rollout check, switch security logging to stderr for verifiability, and note per-Gateway WAF, GRPCRoute inheritance, and WAFPolicy conflict rules

@ohad-perets

…nal logging The security namespace was created inside the optional 'Configure security logging' section. Readers who skipped that section got 'namespaces "security" not found' when applying the APPolicy in the next required step. Fix: extract namespace creation into a new shared include (plm-create-security-namespace.md) and pull it into the tutorial as a required '## Create the security namespace' step that runs before the optional logging section. The ordering is now: 1. Create the security namespace (required) 2. Configure security logging (optional) 3. Define the WAF policy (required, uses namespace: security) Readers who skip logging still have the namespace available for APPolicy, APLogConf, and ReferenceGrant resources. Addresses review comment by @ohad-perets (r3823360430).

…hooting Edit pass on text added in commit 3ab3d15: get-started-plm.md: - CLI flags sentence: remove 'instead of Helm', tighten phrasing - bundle.state table: add missing 'ready' row; add sentence-ending periods per lists.md; reword 'was stored' -> 'is stored' (present tense) - Policy Controller logs: add -c policy-controller flag (pod has multiple containers; omitting the flag returns an error) - NginxProxy note: 'attach a per-Gateway NginxProxy through' -> 'create ... and reference it from' (active, imperative) - WAFPolicy conflict note: rewrite passive 'is rejected' with clear subject; tighten sentence length troubleshooting.md: - ResolvedRefs table: remove (or, for PLM, ...) and (PLM) parentheticals; rewrite meanings as plain statements covering all source types

@ohad-perets

plm-define-policy-methods.md precompiled-bundle tab: - namespace: plm-system -> security. APPolicy resources belong in the security namespace (per the tutorial example values table), not the PLM backend namespace. - Fix update trigger wording: annotating or re-applying an unchanged APPolicy doesn't trigger a fetch. To pick up a new bundle, update the $ref URL and reapply. To re-fetch the same URL, delete and recreate the APPolicy. (Per SME correction by @ohad-perets, r3823399725.) Also applies the same update-trigger correction to the Git-reference tab's 'Update a Git-referenced policy' section.

plm-deploy-infrastructure.md (Ohad's comment, r3822699625): - Fix CA Secret creation: add --from-file=tls.crt alongside ca.crt. PLM chart components mount the CA via tls.crt; the data plane S3 client reads ca.crt. Both keys are required. - Switch to chart-default Secret names (plm-f5-waf-seaweedfs-*) and remove the five explicit *SecretName overrides from Helm values. Names now match what helm show values documents. - Add prose explaining why both CA keys are needed. - Add forward reference from TLS caution to the troubleshooting entry for 'APPolicy invalid with unexpected EOF after enabling TLS'. - Fix broken anchor: replace direct expando link with link to the Troubleshoot the deployment section heading. Call-out audit across guide and all PLM includes: - Promote note -> important for skip-logging, ReferenceGrant ownership, and WAFPolicy conflict rule (reader must act) - Promote note -> caution for enabling TLS on existing install and Git-reference branch pin risk - Promote note -> tip for DNS record shortcut - Promote note -> important for private CA registry configuration - Add informative titles to all call-outs in place of 'Note'/'Warning'

- Rewrite passive ownership sentence to active voice - Remove hedging ('typically') from security team ownership sentence - Split em-dash compound into two sentences (em-dash rule) - Replace ambiguous 'it' pronouns with specific nouns throughout - Split run-on task sentences that exceeded 20-word limit - Convert 'Re-applying' gerund to standard verb form 'Reapplying' - Replace em dashes with parentheses in git-ref update prose - Replace 'enabled' with 'turned on' (enable-disable rule) - Replace 'as-is' idiom with 'without recompilation' (global-audience) - Rewrite passive table entries to active voice (active-voice rule) - Replace 'decouple' with 'separate' (global-audience, simpler word) - Remove SSL_CERT_FILE em dash; clarify ambiguous 'it' referent

Copilot

Pull request overview

Adds a new end-to-end tutorial for using Policy Lifecycle Management (PLM) as a WAF policy source with NGINX Gateway Fabric, along with shared PLM include content and broad copy edits across existing NGF security/WAF docs (including new PLM storage CLI flags and RFC 5737 example IP updates).

Changes:

Add PLM “get started” tutorial for NGF WAF integration plus several new PLM include fragments (deploy PLM backend, policy definition methods, sample app, etc.).
Extend NGF WAF integration docs to document PLM as a WAFPolicy.spec.type, including ReferenceGrant behavior and PLM field differences.
Apply style/consistency edits and update example IPs to 192.0.2.1, plus add new PLM storage flags to CLI reference docs.

Reviewed changes

Copilot reviewed 18 out of 24 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
layouts/shortcodes/version-waf.html	WAF version shortcode update (no functional doc flow change).
layouts/shortcodes/version-waf-policy-controller.html	Policy Controller version shortcode update.
layouts/shortcodes/version-waf-ip-intelligence.html	IP Intelligence version shortcode update.
layouts/shortcodes/version-waf-enforcer.html	Enforcer version shortcode update.
layouts/shortcodes/version-waf-config-mgr.html	Config Manager version shortcode update.
layouts/shortcodes/version-waf-compiler.html	Compiler version shortcode update.
content/ngf/waf-integration/troubleshooting.md	Expand `ResolvedRefs` troubleshooting to cover PLM refs and ReferenceGrant restrictions.
content/ngf/waf-integration/policy-sources.md	Add PLM as a policy source type and update navigation to the new HTTP/PLM tutorials.
content/ngf/waf-integration/overview.md	Document PLM as a first-class source type and add an overview comparison section.
content/ngf/waf-integration/get-started-plm.md	New PLM tutorial: install PLM backend, connect NGF to storage, define policies, and validate enforcement.
content/ngf/waf-integration/get-started-http.md	Rename HTTP tutorial and add an alias to preserve the old URL.
content/ngf/waf-integration/configuration.md	Add PLM-specific guidance for log configuration (`logRef.apLogConfRef`).
content/ngf/traffic-security/oidc-authentication.md	Update example Gateway IP to RFC 5737 address.
content/ngf/traffic-security/jwt-authentication.md	Update example Gateway IP to RFC 5737 address.
content/ngf/traffic-security/cors.md	Update example Gateway IP to RFC 5737 address.
content/ngf/traffic-security/basic-authentication.md	Update example Gateway IP to RFC 5737 address.
content/ngf/reference/cli-help.md	Document new PLM storage CLI flags.
content/includes/waf/plm-sample-app.md	New shared include: sample apps for PLM tutorial testing.
content/includes/waf/plm-prerequisites.md	New shared include: PLM prerequisites and defaults.
content/includes/waf/plm-deploy-infrastructure.md	New shared include: deploy PLM backend via Helm with verification/troubleshooting.
content/includes/waf/plm-define-policy-methods.md	New shared include: define APPolicy via inline/Git/precompiled bundle methods.
content/includes/waf/plm-create-security-namespace.md	New shared include: create the security namespace.
content/includes/waf/plm-configure-logging.md	New shared include: define an APLogConf log profile.
content/includes/ngf/installation/nginx-plus/download-jwt.md	Expand include usage to additional install paths and update wording/call-out formatting.

Suppressed comments (1)

content/ngf/waf-integration/get-started-plm.md:112

This section says the PLM installation creates the credentials Secret automatically, but the example Secret manifest uses a different name/namespace (plm-storage-credentials in nginx-gateway) than the values.yaml examples above (plm-system/plm-f5-waf-seaweedfs-auth). As written, readers won’t know which Secret they should actually reference for credentialsSecretName.

kind: Secret
metadata:
name: plm-storage-credentials
namespace: nginx-gateway
type: Opaque

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

travisamartin · 2026-08-10T18:05:27Z

What this PR does

Adds documentation for using Policy Lifecycle Management (PLM) as a WAF policy source in NGINX Gateway Fabric, and applies style guide copy edits across the NGF WAF integration docs.

New files

`content/includes/waf/plm-deploy-infrastructure.md`

A shared include covering PLM backend deployment. Consumable by both the NGINX Gateway Fabric and NGINX Ingress Controller tutorials without modification. Covers:

PLM architecture: Policy Controller → gRPC → NAP compiler service → SeaweedFS/S3
Installing the four required CRDs (appolicies, aplogconfs, apusersigs, apsignatures)
Creating the registry pull secret
Helm install with plm-values.yaml (uses the version-waf-policy-controller shortcode for the chart version)
Verification: SeaweedFS backend readiness, Policy Controller pod, expected 8-pod output, CRD confirmation

`content/includes/waf/plm-define-policy-bundle-method.md`

A shared include covering the precompiled-bundle policy definition method. Product-neutral and consumable by both tutorials. Covers:

Referencing a .tgz bundle from an artifact registry
bundle.state values (pending, processing, ready, invalid)
isCompiled: false behavior
Correct update trigger: re-apply the APPolicy resource (the Policy Controller does not poll)

`content/ngf/waf-integration/get-started-plm.md`

New end-to-end tutorial for protecting traffic with F5 WAF for NGINX using PLM in NGINX Gateway Fabric. Covers:

Deploying the PLM infrastructure (pulls in the shared include above)
Connecting NGINX Gateway Fabric to in-cluster PLM storage
Defining WAF policies using three methods: inline, Git-reference, and precompiled bundle
Deploying a Gateway and attaching a WAFPolicy
Configuring HTTPRoutes
Validating policy compilation and application
Testing WAF enforcement with a sample application
Applying a route-level data guard override

Updated files

`content/ngf/waf-integration/overview.md`

`content/ngf/waf-integration/policy-sources.md`

`content/ngf/reference/cli-help.md` (PLM storage flags)

Copy edits applying the F5 style guide:

Replaced em dashes with commas, periods, colons, or parentheses
Replaced Latin abbreviations (via → through/using)
Replaced since (causal) with because
Replaced ensure with make sure
Preferred contractions per Modern Voice guidelines
Recasted product name possessives (PLM's, NGINX Agent's)
Fixed placeholder casing (<namespace>/ → <NAMESPACE>/)
Replaced non-RFC-5737 IP address (10.96.20.187 → 192.0.2.1) across six files
Updated f5-description in policy-sources.md to include PLM
Removed redundant heading in policy-sources.md

Open questions for SME review

Registry credentials: the install covers JWT, certificate, and key. Confirm whether a separate registry token is also required and where it is passed.
Private CA for bundle server: confirm the Helm value or config mechanism for trusting a private CA when using the precompiled-bundle method.

github-actions · 2026-08-10T18:07:16Z

✅ Deploy Preview will be available once build job completes!

Name	Link
😎 Deploy Preview	https://frontdoor-test-docs.nginx.com/previews/docs/2197/

sjberman · 2026-08-10T19:56:02Z

We probably need some consistency brought into this doc. In NGF, we avoid placeholder values as much as possible (except for sensitive info) so that a user can just copy/paste commands. The PLM docs don't follow this right now.

Helm installs CRDs on first install automatically, so the manual kubectl apply step is only required when upgrading. Relocate it from the top of the install flow (where it misled new users) to a new "Update the CRDs" section after "Verify the deployment". Add a note clarifying that the step can be skipped on a fresh install. Remove the redundant CRD verification block from the upgrade section, as the verify section already confirms CRD presence. Also pins the GitHub raw URL to the versioned tag using the version-waf-policy-controller shortcode, replacing the previous reference to main.

- Rewrite registry pull secret steps to store the JWT in a Kubernetes Secret before use, avoiding inline JWT exposure - Add JWT download steps to get-started-plm.md prerequisites, reorder prereqs so JWT comes before the registry Secret - Copy edit download-jwt.md include: active voice in call-out, bold UI labels separated, update f5-files consumer list

- Add content/includes/waf/plm-prerequisites.md with PLM-specific prerequisites (StorageClass, Helm, JWT) and SeaweedFS storage defaults (embedded S3 store, default pod topology, credential Secret, HTTP-by-default note) - Restructure get-started-plm.md Before you begin: add PLM prerequisites subsection, add Example values H3 - Copy edit get-started-plm.md: fix causal 'since' → 'because', remove hedge ('should show'), split two-action step, rewrite passive results, tighten team-ownership callouts, fix directional reference, fix 'this guide' → 'this tutorial' - Copy edit plm-define-policy-bundle-method.md: use contraction ('doesn't poll')

The PLM chart does not generate TLS certificates. If certificates.enabled is set to true in the seaweedfsOperatorConfig, all five Secrets (CA, master, volume, filer, client) must be pre-created before running helm upgrade --install. Missing Secrets cause SeaweedFS pods to fail on mount. Add an optional TLS subsection to the 'Install the Policy Controller' section that: - States TLS is off by default - Shows the certificates block with the five secretName keys - Warns explicitly that the chart does not generate certificates - Provides kubectl create secret commands for each required Secret - Explains the PKI prerequisite Resolves feedback from code review.

The SeaweedFS operator deployment becomes Available before it reconciles the SeaweedFS CR and creates the SeaweedFS pods. This means kubectl wait --selector app.kubernetes.io/name=seaweedfs can exit immediately with no matches (and therefore an error) during the window between the operator being ready and the pods being created. Replace the two-step wait with a polling loop that retries kubectl wait every 5 seconds until either all SeaweedFS pods are Ready or a 300s timeout is exceeded.

- Add '#### Install the chart' heading before the helm repo add / helm upgrade commands to visually separate them from the optional TLS subsection. Without this heading, the install commands appeared to be continuation content of the TLS section rather than a step for all readers. - Replace inline skip note on '### Update the CRDs' with a note call-out so the upgrade-only scope is the first thing readers see before the imperative content.

@ciarams87

Move the sample app deployment, security logging configuration, and APPolicy inline/Git-reference definitions from get-started-plm.md into product-agnostic shared includes so NIC can reuse them: - plm-sample-app.md: customers and orders Deployment/Service manifests - plm-configure-logging.md: security namespace and APLogConf definition - plm-define-policy-inline-git.md: APPolicy inline and Git-reference methods The ReferenceGrant block stays inline in the NGF tutorial — NIC does not use ReferenceGrant. The precompiled-bundle method remains in the existing plm-define-policy-bundle-method.md include. Addresses review comment by @ciarams87 (r3756532202).

NIC tutorials have not been created yet. Remove the placeholder content/nic/waf-integration/get-started-plm.md f5-files entry from all five PLM includes. These will be restored when the NIC tutorial is written as part of the NIC work.

@ohad-perets