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.

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)

- Add maintainer HTML comment noting the APPolicy CRD prerequisite and directing future reusers to add a parent-document note - Convert the 'Update a precompiled bundle' step to inline EOF pattern, consistent with the initial apply step - Add placeholder explanation ('Replace <X>, <Y>, and <Z> with your values') before the update code block, following the pattern used elsewhere in the include

JTorreG · 2026-08-12T12:33:17Z

+- content/nic/waf-integration/get-started-plm.md
+---
+
+<!-- Maintainer note: This include assumes the APPolicy CRD is already installed. In the NGF and NIC tutorials, CRD installation happens in the "Deploy PLM infrastructure" section. If you reuse this include elsewhere, add a prerequisite note in the parent document confirming CRDs are present before this section. -->


Loving this

wondering if notes could be a metadata field like f5-note

Co-authored-by: Shaun <s.odonovan@f5.com>

Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com>

…ocumentation into techdocs-5345-deploy-plm

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.

travisamartin · 2026-08-14T16:18:09Z

+    pullSecrets: regcred
+```
+
+#### Enable TLS for PLM storage (optional)


@ohad-perets @ciarams87

This new section addresses the comment above.

This section is AI-generated and needs SME review before accepting.

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.

travisamartin added 3 commits July 28, 2026 14:18

Added "Get started with F5 WAF for NGINX with PLM"

ddbd331

Merge remote-tracking branch 'origin' into ngf-waf-plm

31def9a

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 5 commits August 10, 2026 11:25

Merge remote-tracking branch 'origin' into ngf-waf-plm

94950bb

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

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

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 3 commits August 10, 2026 13:11

travisamartin added 3 commits August 11, 2026 09:45

Merge remote-tracking branch 'origin' into nginx-august-releases

0539daf

Merge branch 'nginx-august-releases' into techdocs-5345-deploy-plm

e5b60df

JTorreG reviewed Aug 12, 2026

View reviewed changes

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

shaun-nx reviewed Aug 12, 2026

View reviewed changes

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

shaun-nx reviewed Aug 12, 2026

View reviewed changes

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

shaun-nx reviewed Aug 12, 2026

View reviewed changes

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

shaun-nx reviewed Aug 12, 2026

View reviewed changes

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

shaun-nx reviewed Aug 12, 2026

View reviewed changes

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

travisamartin and others added 5 commits August 12, 2026 13:17

style edits applied to get-started-plm.md

62a1c01

Apply suggestions from code review

cd3c38e

Co-authored-by: Shaun <s.odonovan@f5.com>

Apply suggestions from code review

8a75252

Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com>

removed TODO from plm-define-policy-bundle-method.md

567731b

Merge branch 'techdocs-5345-deploy-plm' of https://github.com/nginx/d…

39d2e9a

…ocumentation into techdocs-5345-deploy-plm

ohad-perets reviewed Aug 13, 2026

View reviewed changes

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

ohad-perets reviewed Aug 13, 2026

View reviewed changes

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

ohad-perets reviewed Aug 13, 2026

View reviewed changes

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

travisamartin changed the base branch from nginx-august-releases to main August 13, 2026 20:18

travisamartin added 8 commits August 13, 2026 13:19

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

992e28b

fix: Quote heredoc delimiter to prevent $ref expansion

6c58435

fix: Add example output to CRD verification and CRD upgrade steps

98cbbb3

fix: Clarify securityUpdatesRepo cert and key are optional

2545406

travisamartin commented Aug 14, 2026

View reviewed changes

travisamartin added 2 commits August 14, 2026 09:25

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 43 commits into
mainfrom
techdocs-5345-deploy-plm

travisamartin commented Aug 10, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Aug 10, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sjberman commented Aug 10, 2026

Uh oh!

JTorreG Aug 12, 2026

Uh oh!

JTorreG Aug 12, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

travisamartin Aug 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 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!

Uh oh!

Uh oh!

sjberman commented Aug 10, 2026

Uh oh!

JTorreG Aug 12, 2026

Choose a reason for hiding this comment

Uh oh!

JTorreG Aug 12, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

travisamartin Aug 14, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 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)