docs: Add PLM policy source tutorial and copy edits for NGF WAF integration #2197
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,75 @@ | ||
| --- | ||
| f5-product: F5 WAF for NGINX | ||
| f5-files: | ||
| - content/ngf/waf-integration/get-started-plm.md | ||
| - content/nic/waf-integration/get-started-plm.md | ||
| --- | ||
|
|
||
| The precompiled-bundle method lets you reference a `.tgz` policy bundle stored in an artifact registry (for example, Artifactory or Nexus). The Policy Controller imports the bundle and stores it in the SeaweedFS object store without recompiling it. | ||
|
|
||
| Use this method when: | ||
|
|
||
| - Your security team compiles and publishes bundles through an external pipeline. | ||
| - You want to decouple policy compilation from cluster operations. | ||
|
|
||
| Create an `APPolicy` resource that references your bundle: | ||
|
|
||
| ```yaml | ||
| 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" | ||
| ``` | ||
|
|
||
| Replace `<POLICY_NAME>`, `<ARTIFACT_REGISTRY_HOST>`, and `<PATH/TO/POLICY_BUNDLE>` with your values. | ||
|
|
||
| Apply the resource: | ||
|
|
||
| ```shell | ||
| kubectl apply -f <POLICY_MANIFEST_FILE>.yaml | ||
| ``` | ||
|
|
||
| {{< 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. --> | ||
| {{< /call-out >}} | ||
|
|
||
| #### Confirm the policy is ready | ||
|
|
||
| The Policy Controller processes the bundle and updates the `APPolicy` status. Check the `bundle.state` field: | ||
|
|
||
| ```shell | ||
| kubectl get appolicy <POLICY_NAME> \ | ||
| --namespace plm-system \ | ||
| --output jsonpath='State: {.status.bundle.state}{"\n"}Bundle: {.status.bundle.location}{"\n"}isCompiled: {.status.processing.isCompiled}{"\n"}' | ||
| ``` | ||
|
|
||
| When the bundle is ready, the output looks like this: | ||
|
|
||
| ```text | ||
| State: ready | ||
| Bundle: s3://plm-system/bundles/<POLICY_NAME>_imported_<HASH>.tgz | ||
| isCompiled: false | ||
| ``` | ||
|
|
||
| `isCompiled: false` confirms the bundle was imported as-is and not recompiled. | ||
|
|
||
| `bundle.state` can be one of: | ||
|
|
||
| | State | Meaning | | ||
| |-------|---------| | ||
| | `pending` | The Policy Controller has not yet processed the resource. | | ||
| | `processing` | The Policy Controller is importing or storing the bundle. | | ||
| | `ready` | The bundle is stored and ready to use. `bundle.location` is populated. | | ||
| | `invalid` | The bundle could not be imported. Check the status for error detail. | | ||
|
|
||
| #### Update a precompiled bundle | ||
|
|
||
| The Policy Controller does not poll the artifact registry for changes. To pick up a new version of a bundle, update the `APPolicy` resource to reference the new bundle URL (or bump its revision annotation) and re-apply it: | ||
|
|
||
| ```shell | ||
| kubectl apply -f <UPDATED_POLICY_MANIFEST_FILE>.yaml | ||
| ``` | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,147 @@ | ||
| --- | ||
| f5-product: F5 WAF for NGINX | ||
| f5-files: | ||
| - content/ngf/waf-integration/get-started-plm.md | ||
| - content/nic/waf-integration/get-started-plm.md | ||
| --- | ||
|
|
||
| The Policy Lifecycle Manager (PLM) backend runs as a Kubernetes operator. It watches WAF custom resources and compiles WAF policies into bundles. The Policy Controller delegates compilation to a separate compiler service over gRPC. The resulting bundles are stored in an embedded SeaweedFS S3-compatible object store. | ||
|
|
||
| F5 WAF for NGINX is installed using a separate Helm chart from your NGINX data plane. The steps in this section install only the F5 WAF for NGINX PLM components and do not affect your existing NGINX installation. | ||
|
|
||
| ### Install the CRDs | ||
|
|
||
| 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 | ||
|
Contributor
There was a problem hiding this comment. iirc PLM controller creates the CRDs
Contributor
There was a problem hiding this comment. This would only be beneficial for an upgrade since helm doesn't upgrade CRDs. |
||
| ``` | ||
|
|
||
| Confirm all four CRDs are present: | ||
|
|
||
| ```shell | ||
| kubectl get crd | grep appprotect.f5.com | ||
| ``` | ||
|
|
||
| Expected output: | ||
|
|
||
| ```text | ||
| appolicies.appprotect.f5.com | ||
| aplogconfs.appprotect.f5.com | ||
| apsignatures.appprotect.f5.com | ||
| apusersigs.appprotect.f5.com | ||
| ``` | ||
|
|
||
| ### Create the registry pull secret | ||
|
|
||
| Create a namespace for the PLM components, then create the registry pull secret using the credentials from the previous section. Replace `<JWT>` with your F5 WAF for NGINX JWT. | ||
|
|
||
| <!-- TODO (TECHDOCS-5342 / Prerequisites): The Story 3 AC lists four credentials: JWT, certificate, key, and registry token. Confirm with SME what the registry token is and whether it's passed separately in the Helm install or covered by the JWT above. --> | ||
|
|
||
| ```shell | ||
| kubectl create namespace plm-system | ||
|
|
||
| kubectl create secret docker-registry regcred \ | ||
| --namespace plm-system \ | ||
| --docker-server=private-registry.nginx.com \ | ||
| --docker-username=<JWT> \ | ||
| --docker-password=none \ | ||
| --dry-run=client --output yaml | kubectl apply -f - | ||
| ``` | ||
|
|
||
| ### Install the Policy Controller | ||
|
Contributor
There was a problem hiding this comment. We absolutely require a prerequisite section for PLM detailing the storage requirements and configurations and detailing the default behaviour |
||
|
|
||
| Create a values file for the Helm installation. Replace `<BASE64_NGINX_REPO_CRT>` and `<BASE64_NGINX_REPO_KEY>` with the base64-encoded contents of your `nginx-repo.crt` and `nginx-repo.key` files. To encode them, run: | ||
|
|
||
| ```shell | ||
| base64 --wrap=0 < nginx-repo.crt | ||
| base64 --wrap=0 < nginx-repo.key | ||
| ``` | ||
|
|
||
| Create `/tmp/plm-values.yaml`: | ||
|
|
||
| ```yaml | ||
| imagePullSecrets: | ||
| - name: regcred | ||
| securityUpdatesRepo: | ||
| cert: "<BASE64_NGINX_REPO_CRT>" | ||
| key: "<BASE64_NGINX_REPO_KEY>" | ||
| policyController: | ||
|
Contributor
There was a problem hiding this comment. 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 |
||
| image: | ||
| tag: "{{< version-waf-policy-controller >}}" | ||
| compiler: | ||
| image: | ||
| tag: "{{< version-waf-policy-controller >}}" | ||
| seaweedfsOperatorConfig: | ||
| seaweedfs: | ||
| image: | ||
| tag: "{{< version-waf-policy-controller >}}" | ||
| seaweedfs-operator: | ||
|
Contributor
There was a problem hiding this comment. 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. |
||
| image: | ||
| tag: "{{< version-waf-policy-controller >}}" | ||
| pullSecrets: regcred | ||
| ``` | ||
|
|
||
| Add the NGINX Helm repository and install the chart: | ||
|
|
||
| ```shell | ||
| helm repo add nginx-stable https://helm.nginx.com/stable | ||
| helm repo update nginx-stable | ||
|
|
||
| helm upgrade --install plm nginx-stable/f5-waf-policy-controller \ | ||
| --version {{< version-waf-policy-controller >}} \ | ||
| --namespace plm-system \ | ||
| --values /tmp/plm-values.yaml | ||
| ``` | ||
|
|
||
| ### Verify the deployment | ||
|
|
||
| Wait for all PLM components to become ready. The Policy Controller's init container waits for both the compiler service and the SeaweedFS S3 endpoint to be available before it starts, so the controller pod will show `Init:0/1` until SeaweedFS is ready. | ||
|
|
||
| Wait for the SeaweedFS storage backend: | ||
|
|
||
| ```shell | ||
| kubectl rollout status deployment/plm-seaweedfs-operator \ | ||
| --namespace plm-system --timeout=120s | ||
|
|
||
| kubectl wait pods \ | ||
| --selector app.kubernetes.io/name=seaweedfs \ | ||
| --for=condition=Ready \ | ||
| --namespace plm-system \ | ||
| --timeout=180s | ||
| ``` | ||
|
|
||
| Wait for the Policy Controller: | ||
|
|
||
| ```shell | ||
| kubectl rollout status deployment/plm-f5-waf-policy-controller \ | ||
| --namespace plm-system --timeout=180s | ||
| ``` | ||
|
|
||
| Confirm all eight pods are running: | ||
|
|
||
| ```shell | ||
| kubectl get pods --namespace plm-system | ||
| ``` | ||
|
|
||
| Expected output: | ||
|
|
||
| ```text | ||
| NAME READY STATUS RESTARTS | ||
| plm-f5-waf-compiler-service-xxxxx 1/1 Running 0 | ||
| plm-f5-waf-policy-controller-xxxxx 1/1 Running 0 | ||
| plm-seaweedfs-operator-xxxxx 1/1 Running 0 | ||
| plm-f5-waf-seaweed-master-0 1/1 Running 0 | ||
| plm-f5-waf-seaweed-filer-0 1/1 Running 0 | ||
| plm-f5-waf-seaweed-volume-0 1/1 Running 0 | ||
| plm-f5-waf-seaweed-volume-1 1/1 Running 0 | ||
| plm-f5-waf-seaweed-volume-2 1/1 Running 0 | ||
| ``` | ||
|
|
||
| Confirm the four CRDs are present: | ||
|
Contributor
There was a problem hiding this comment. We should also have a troubleshooting section. |
||
|
|
||
| ```shell | ||
| kubectl get crd | grep appprotect.f5.com | ||
| ``` | ||
|
|
||
| All eight pods running and all four CRDs present confirms the PLM backend is ready. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@ohad-perets -- Can you verify this note? There's a TODO to resolve.