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

[travisamartin]

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]

✅ Deploy Preview will be available once build job completes!

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

---

[vepatel]

iirc PLM controller creates the CRDs

[sjberman]

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

[vepatel]

maybe in that case point to upcoming release tag instead of main
cc @ohad-perets

[shaun-nx]

If we are going to use this command anywhere, it should probably use the latest released version instead of main.

So something like this:

kubectl apply -f https://raw.githubusercontent.com/nginx/waf-policy-controller/{{< version-waf >}}/manifests/1-deploy-crds.yaml

[ohad-perets]

Agreed on pinning to a release tag rather than main — main will drift out from under the published docs.

• The chart does ship the CRDs. They're in crds/ (the four appprotect.f5.com CRDs) and in the seaweedfs-operator subchart's crds/ (seaweeds.seaweed.seaweedfs.com).
• Helm applies crds/ on first install only and never on upgrade, so @sjberman is correct that the manual apply is only useful for upgrades. On a clean install this step is redundant.

*We can frame the step as an upgrade concern, or mark it optional on first install, so a new user isn't led to think the install fails without it.

[sjberman]

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.

[ciarams87]

We need to at the very least provide a link to the full values.yaml so the user knows all the possible configuration options available.

[travisamartin]

@ohad-perets Can you share the link? or is there a reference page we can link to?

As a workaround, I added:

To see all available configuration options for the PLM chart, run:

```shell
helm show values nginx-stable/f5-waf-policy-controller --version {{< version-waf-policy-controller >}}
```

[ohad-perets]

This is what we have: helm show values nginx-stable/f5-waf-policy-controller --version 5.14.0

It needs no authentication (helm.nginx.com/stable is public), returns the full values file, and the file is well commented — including the certificates block and filerHttpsMtls. It also has the advantage of always matching whatever version the reader is installing, which a static link wouldn't.

[ciarams87]

We absolutely require a prerequisite section for PLM detailing the storage requirements and configurations and detailing the default behaviour

[travisamartin]

@ohad-perets -- Can you draft a prerequisite section for PLM covering storage requirements, configuration, and default behavior?

[ohad-perets]

Prerequisites**

Before installing PLM you need:

• A Kubernetes cluster with a default StorageClass that supports dynamic provisioning. PLM's object store is backed by PersistentVolumeClaims; without a default StorageClass the SeaweedFS pods stay Pending.
• An F5 WAF for NGINX JWT from MyF5, used to pull images from private-registry.nginx.com.
• Optionally, nginx-repo.crt and nginx-repo.key from MyF5, used only for authenticated signature updates from pkgs.nginx.com.

Storage and default behaviour

PLM ships with an embedded SeaweedFS S3-compatible object store, deployed by the bundled SeaweedFS operator. You do not need to provide an external S3 bucket. Compiled policy bundles are written here, and the data plane reads them from it.

By default the deployment creates one master, one filer, and three volume pods, each volume pod backed by its own PVC. The store is provisioned with credentials generated by the chart and held in the <release>-f5-waf-seaweedfs-auth Secret.

Communication between PLM and the object store is unencrypted HTTP by default. To enable TLS, see [mTLS section].

[ciarams87]

We should also have a troubleshooting section.

[travisamartin]

@ohad-perets , since you're the SME here, can you draft the troubleshooting steps for this section? Doesn't need to cover everything, just the 80/20: the issues most likely to come up during deploy.

[ohad-perets]

These are the five failures I actually hit while validating on 5.14.0, roughly in order of likelihood.

Troubleshooting

Pods stuck in ImagePullBackOff
The JWT is wrong, expired, or was pasted with a line break. Confirm with:

kubectl get events --namespace plm-system --field-selector reason=Failed

The username is the entire JWT and the password is the literal string none.

Policy Controller stays in Init:0/1
Expected during startup. The init container waits for both the compiler service and the S3 endpoint. If it persists beyond a few minutes, check that the SeaweedFS pods are Running:

kubectl get pods --namespace plm-system --selector app.kubernetes.io/name=seaweedfs

The usual cause is PVCs stuck Pending because the cluster has no default StorageClass.

SeaweedFS pods Pending
No default StorageClass, or insufficient capacity:

kubectl get pvc --namespace plm-system
kubectl get storageclass

APPolicy stuck in pending with a certificate error
Applies to the precompiled-bundle method. Check the resource status:

kubectl describe appolicy <name> --namespace plm-system

x509: certificate signed by unknown authority means the Policy Controller does not trust the artifact registry's CA. Note that SSL_CERT_FILE replaces the trust store rather than adding to it, so if SeaweedFS TLS is also enabled, both CAs must be in a single file.

APPolicy shows invalid with unexpected EOF after enabling TLS
Enabling TLS on an existing installation restarts the storage backend and can orphan objects written beforehand. Confirm in the filer log:

kubectl logs --namespace plm-system <release>-f5-waf-seaweed-filer-0 | grep "not found"

A volume N not found message confirms it. Remove the orphaned object and restart the Policy Controller so it is regenerated.

Helm install fails on a ClusterRole
An error naming seaweed-editor-role or seaweed-viewer-role means another PLM installation already exists in the cluster. Only one is supported; remove the existing release first.

---

Most useful single command for anything policy-related:

kubectl logs --namespace plm-system deploy/<release>-f5-waf-policy-controller -c policy-controller

Note the -c policy-controller — the pod has more than one container, and the containers are distroless, so kubectl exec isn't available for debugging.

[ciarams87]

We don't detail anywhere in this deployment guide how to configure mTLS, but we specify it in the NGF guide, with no guidance in either on how to create/ manage/ provide the CA or certificates

[travisamartin]

@ciarams87 @ohad-perets — this include is WAF-team-owned content, so I want to make sure we're putting the mTLS guidance in the right place before writing it.

Two questions:

1. Is this include the right place for mTLS setup? The include covers PLM infrastructure deployment and is shared between the NGF and NIC tutorials. If mTLS configuration between PLM storage and the data plane is a one-time cluster-level setup step that happens at install time, it belongs here. If it's something configured separately per product (NGF vs NIC), it may belong in the parent tutorial instead.

2. If it does belong here, can you draft the steps? Specifically:

   • How is the CA certificate obtained — generated by the PLM chart, or user-provided?
   • What Secret format does caSecretName expect (field name, for example ca.crt)?
   • Same for clientSSLSecretName (tls.crt / tls.key)?
   • Is there a recommended way to generate a self-signed CA for non-production use?

If the information belongs somewhere other than this include, let me know where and I'll move the placeholder.

[ohad-perets]

Is the CA chart-generated or user-provided?
User-provided. The chart does not generate certificates — there is no genCA/genSignedCert anywhere in it. If you set certificates.enabled=true without pre-creating the Secrets, the pods will fail to mount. This is the single most important thing to state, and it's currently not stated anywhere.

TBH, not sure where this info belongs - adding also @ViktorFefilovF5

[ciarams87]

An awful lot of the following sections could be reused for NIC - the sample deployment, the ApLogConf definition, the ApPolicy configuration. How these policies are referenced by the products is different (and NIC does not use a ReferenceGrant), but the PLM owned CRD config can be pulled out to shared includes files

[shaun-nx]

Instead of having a separate kubectl apply -f, step, we usually wrap the full yaml example file in the command.

So something like this:

kubectl apply -f - <<EOF
apiVersion: appprotect.f5.com/v1
kind: APPolicy
metadata:
  name: <POLICY_NAME>
  namespace: plm-system
spec:
  policy:
    $ref: "https://<ARTIFACT_REGISTRY_HOST>/<PATH/TO/POLICY_BUNDLE>.tgz"
EOF

This saves the user from creating their own file and allows them to just apply the resource directly. They will still need to update certain fields.

[shaun-nx]

Also, after they apply the file, it's good to add a step to confirm the resource was applied correctly, and to include the output from that command. There's an example here where we verify a service.

[travisamartin]

Updated. Can you take another look?

[shaun-nx]

We want to avoid users needing to add their JWT to a command.

Have the user first create a new Secret in their cluster, which contains a base64 encoded version of their JWT. Assuming their JWT is stored in a file, they can run this command first to create the secret from that file. This example assumes their JWT is in a file called license.jwt

kubectl create secret generic jwt-reg-secret --from-file=license.jwt

You then should be able to replace --docker-username=<JWT> with this:

--docker-username=<(kubectl get secret jwt-reg-secret -o jsonpath='{.data.license\.jwt}' | base64 -d) \

This will extract the data from the secret, and pass the JWT directly to the --docker-username flag.

[travisamartin]

@ohad-perets, @shaun-nx

Two questions:

1. Is this the JWT from MyF5?
2. Should having the JWT be listed in the tutorial prerequisites?

[shaun-nx]

1. Is this the JWT from MyF5?

Yes, they come from MyF5. Here's an example of that step from our Plus install guide

2. Should having the JWT be listed in the tutorial prerequisites?

Yes, especially since that's required for creating this regcred secret.

[shaun-nx]

Are users really required to add their full cert and key in this config? Or does this reference to their cert and key file?

[travisamartin]

@ohad-perets Can you confirm whether the full cert and key are required, or if these are references to the files? If the latter, I'll update the placeholder text to make it clearer.

[shaun-nx]

We probably can't change this now, but this securityUpdatesRepo field should really use a Kubernetes Secret instead of the certs and keys directly. @ohad-perets is something that we could change in the helm chart in the future?

[ohad-perets]

Not sure; we will need to check it. @ViktorFefilovF5 can you check it?

[ohad-perets]

These certificates are OPTIONAL and only needed for authenticated access to signature repositories. The Policy Controller will start successfully with empty values.

[JTorreG]

Loving this

[JTorreG]

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

[shaun-nx]

Lets an example output here

[ohad-perets]

Are you sure that this one will work?
i think we need to change both <<EOF to <<'EOF'. The closing EOF stays unquoted.

[ohad-perets]

also here: change both <<EOF to <<'EOF'. The closing EOF stays unquoted.

[ohad-perets]

The SeaweedFS pods are created by that operator afterwards,
When it reconciles the Seaweed CR — so there is a real window where the operator is
Available, but no seaweedfs pods exist yet, and the documented command aborts the procedure.

not sure if we really can do something with that, but just raising. @ViktorFefilovF5 what do you think?