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.

Satisfies TECHDOCS-5343 (Story 3) and TECHDOCS-5347 (Story 7) for the NGF + F5 WAF for NGINX with PLM tutorial. Story 3 — Deploy PLM infrastructure (shared include): - Add content/includes/waf/plm-deploy-infrastructure.md - Covers PLM architecture (Policy Controller → gRPC → compiler → SeaweedFS/S3), CRD installation, registry pull secret creation, Helm install with plm-values.yaml, and deployment verification - No NGF-specific content; consumable by the NIC tutorial unmodified - Flags open item: registry token credential (TECHDOCS-5342) Story 7 — Define the WAF policy (NGF content + shared include): - Add content/includes/waf/plm-define-policy-bundle-method.md (precompiled-bundle method; product-neutral shared include) - Add inline and Git-reference methods directly to get-started-plm.md as NGF-specific content - Documents correct recompile trigger (spec/annotation change required; controller does not poll Git or Artifactory) - Documents bundle.state values: pending | processing | ready | invalid - Documents isCompiled: false for precompiled bundles Also updates get-started-plm.md with TODO placeholders for all remaining sections (Stories 2, 4, 5, 6, 8, 9, 10, 11).

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/

Remove the hard-coded NGINX Gateway Fabric product name from the deploy-infrastructure include. The separate-Helm-charts note now refers to the NGINX data plane generically so both the NGF and NIC tutorials can consume the include unmodified. Also adds the NIC target file to f5-files front matter in both includes.

Headings in include files cause TOC and hierarchy issues depending on the level of the section they are embedded in. Replace all ### and #### headings with bold lead-in sentences.

Match heading levels to the consuming section in each case: - plm-deploy-infrastructure.md: ### (consumed under ##) - plm-define-policy-bundle-method.md: #### (consumed under ###) Ensures TOC entries and visual hierarchy are consistent with the parallel method subsections in get-started-plm.md.

vepatel · 2026-08-10T19:10:39Z

+Install the four custom resource definitions (CRDs) that the Policy Controller manages:
+
+```shell
+kubectl apply -f https://raw.githubusercontent.com/nginx/waf-policy-controller/main/manifests/1-deploy-crds.yaml


iirc PLM controller creates the CRDs

This would only be beneficial for an upgrade since helm doesn't upgrade CRDs.

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.

Address PR feedback (sjberman): avoid placeholder values where possible so commands are copy-pasteable. - Namespace: plm-system (matches plm-storage-service.plm-system URL already used in the NGF guide) - Release name: plm - Version: {{< version-waf-policy-controller >}} shortcode (already exists at 5.14.0; auto-updates with future releases) Sensitive values retained as placeholders: <JWT>, <BASE64_NGINX_REPO_CRT>, <BASE64_NGINX_REPO_KEY>.

Apply F5 style guide rules across four files: - get-started-plm.md - overview.md - policy-sources.md - cli-help.md (lines 47-51, PLM storage flags) Changes applied: - em-dash: replace all em dashes with commas, periods, colons, or parentheses; use -- only where unavoidable - latin-abbreviations: via → through/using; since (causal) → because - ensure-vs-make-sure: ensure → make sure - contractions: does not/cannot → doesn't/can't per Modern Voice - possessives: PLM's in-cluster storage → in-cluster PLM storage - word-list: ensures that → means; enables → results in - placeholders: <namespace>/ → <NAMESPACE>/ per formatting rules - sensitive-information: non-RFC-5737 IP replaced with 192.0.2.1 - f5-product-names: PLM storage flag descriptions spell out Policy Lifecycle Manager on first mention - Removed redundant heading: NGINX Instance Manager (NGINX Instance Manager) → NGINX Instance Manager - Updated f5-description in policy-sources.md to include PLM

- possessives: fix PLM's, NGINX Agent's (product name possessives recasted using 'of' or restructured) - em-dash: fix reverted em dash in get-started-plm.md - sentence-length: split long Bundles sentence in overview.md - grammar: 'begins at fetching' → 'begins with fetching' - active-voice: recast passive 'to be set up' → 'to be configured' in overview.md call-out - possessives: Gateway's parametersRef → parametersRef field on a Gateway (inanimate object restructured)

Replace 10.96.20.187 with 192.0.2.1 (RFC 5737 documentation range) in all six NGF files where it appeared as a Gateway IP example. Files updated: - content/ngf/traffic-security/basic-authentication.md - content/ngf/traffic-security/cors.md - content/ngf/traffic-security/jwt-authentication.md - content/ngf/traffic-security/oidc-authentication.md - content/ngf/waf-integration/get-started-http.md - content/ngf/waf-integration/get-started-plm.md

travisamartin · 2026-08-10T22:48:29Z

+```
+
+{{< call-out class="note" title="Note" >}}
+The Policy Controller must be able to reach the artifact registry host over HTTPS. If the registry uses a private certificate authority, configure the Policy Controller to trust that CA. <!-- TODO: SME to confirm and document the Helm value or config mechanism for trusting a private CA on the bundle server. -->


@ohad-perets -- Can you verify this note? There's a TODO to resolve.

Use concrete namespace (plm-system) to match the deploy infrastructure include. Normalize manifest filename and output placeholders to ALL_CAPS_UNDERSCORES per style guide.

Add a table mapping all concrete example values used throughout the tutorial so readers know what is configurable before running any commands. Covers: plm-system (PLM namespace), plm (Helm release), version-waf-policy-controller shortcode, security (policy namespace), default (Gateway/WAFPolicy namespace), and cafe.example.com (hostname). Removes the redundant note from the deploy infrastructure include -- the Before you begin table covers both includes in one place.

Add a Mermaid flowchart showing the six-step tutorial workflow so readers can see the end-to-end picture before starting: 1. Deploy PLM infrastructure 2. Connect NGF to PLM storage 3. Define WAF policy (APPolicy/APLogConf) 4. Attach WAFPolicy to Gateway (with PLM compilation step called out) 5. Configure HTTPRoutes 6. Validate and test

The Hugo theme's bundled Mermaid version does not support the flowchart directive or stadium node shapes. Switch to graph LR with quoted rectangle nodes and HTML line breaks, matching the syntax used in other working diagrams in the repo.

Replace the failed Mermaid diagram and redundant numbered list with a concise 'By the end, you will have:' bullet list. Rewrite the opening sentence to lead with the tutorial framing rather than a long colon-separated summary. The left-nav TOC already shows the section structure, so the numbered list added no value.

The tutorial spans three personas (cluster admin, SecOps, platform engineer/app dev) but gave no signal when ownership shifted between them. Add plain-prose callouts at four points: - Configure security logging: flag as a security team task - Define the WAF policy: explain the security namespace separation and name the handoff artifact (APPolicy name and namespace) - ReferenceGrant note: clarify that the grant lives in the security namespace and requires coordination with whoever owns it - Apply a route-level override: frame the pattern as a SecOps and app team collaboration rather than a generic optional step Also remove six standalone horizontal rules that preceded section headings, per repo convention.

github-actions Bot added documentation Improvements or additions to documentation product/ngf Issues related to NGINX Gateway Fabric product/waf Issues related to F5 WAF for NGINX labels Aug 10, 2026

travisamartin changed the base branch from main to ngf-waf-plm August 10, 2026 18:22

Merge remote-tracking branch 'origin' into techdocs-5345-deploy-plm

f186b23

travisamartin added 4 commits August 10, 2026 11:26

Merge branch 'ngf-waf-plm' into techdocs-5345-deploy-plm

989aad4

style: Remove headings from PLM includes

04fd349

Headings in include files cause TOC and hierarchy issues depending on the level of the section they are embedded in. Replace all ### and #### headings with bold lead-in sentences.

sjberman reviewed Aug 10, 2026

View reviewed changes

Comment thread content/ngf/waf-integration/get-started-plm.md Outdated

vepatel reviewed Aug 10, 2026

View reviewed changes

sjberman reviewed Aug 10, 2026

View reviewed changes

Comment thread content/includes/waf/plm-deploy-infrastructure.md Outdated

Add NGF PLM docs

ee9508a

sjberman requested a review from a team August 10, 2026 19:52

travisamartin added 4 commits August 10, 2026 13:11

travisamartin marked this pull request as ready for review August 10, 2026 21:05

travisamartin requested a review from a team as a code owner August 10, 2026 21:05

travisamartin requested review from a team as code owners August 10, 2026 21:05

travisamartin deleted the branch nginx-august-releases August 10, 2026 21:06

travisamartin closed this Aug 10, 2026

travisamartin reopened this Aug 10, 2026

travisamartin changed the base branch from ngf-waf-plm to nginx-august-releases August 10, 2026 21:10

travisamartin changed the title ~~docs: Add PLM infrastructure and WAF policy sections for NGF tutorial~~ docs: NGF WAF + PLM tutorial and copy edits (August release) Aug 10, 2026

travisamartin changed the title ~~docs: NGF WAF + PLM tutorial and copy edits (August release)~~ docs: Add PLM policy source tutorial and copy edits for NGF WAF integration Aug 10, 2026

Fix installation and version files

25c48b1

travisamartin requested a review from ohad-perets August 10, 2026 22:46

travisamartin commented Aug 10, 2026

View reviewed changes

travisamartin added 6 commits August 10, 2026 15:51

style: Align placeholders in bundle-method include with deploy include

e7055dc

Use concrete namespace (plm-system) to match the deploy infrastructure include. Normalize manifest filename and output placeholders to ALL_CAPS_UNDERSCORES per style guide.

Navigation Menu

Uh oh!

docs: Add PLM policy source tutorial and copy edits for NGF WAF integration - #2197

docs: Add PLM policy source tutorial and copy edits for NGF WAF integration#2197
travisamartin wants to merge 18 commits into
nginx-august-releasesfrom
techdocs-5345-deploy-plm

travisamartin commented Aug 10, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Aug 10, 2026

Uh oh!

Uh oh!

vepatel Aug 10, 2026

Uh oh!

sjberman Aug 10, 2026

Uh oh!

Uh oh!

sjberman commented Aug 10, 2026

Uh oh!

travisamartin Aug 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

travisamartin commented Aug 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this PR does

New files

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

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

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

Updated files

content/ngf/waf-integration/overview.md

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

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

Open questions for SME review

Uh oh!

github-actions Bot commented Aug 10, 2026

✅ Deploy Preview will be available once build job completes!

Uh oh!

Uh oh!

vepatel Aug 10, 2026

Choose a reason for hiding this comment

Uh oh!

sjberman Aug 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sjberman commented Aug 10, 2026

Uh oh!

travisamartin Aug 10, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

travisamartin commented Aug 10, 2026 •

edited

Loading

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

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

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

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

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

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