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)

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

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 7 commits August 13, 2026 13:34

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

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

travisamartin and others added 12 commits August 14, 2026 09:25