From f66491a2fd275b6d7729f096229724d60454045a Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Wed, 5 Nov 2025 15:44:08 +0000 Subject: [PATCH] feat: Add pseudo-variables to F5 WAF for NGINX This commit uses the shortcode psuedo-variable pattern to make multiple component versions for F5 WAF for NGINX into strings. This allows for content in multiple locations to be changed at once by updating the file relating to the version. Many of the versions are currently identical: if the individual components all use the same version, then the amount of shortcode files can be reduced accordingly. - Closes #1318 by replacing the string with a shortcode - Closes #1364 by creating shortcode psuedovariables for each item --- content/waf/configure/compiler.md | 29 ++++--------------- .../fundamentals/technical-specifications.md | 2 ++ .../waf/install/disconnected-environment.md | 14 ++++----- content/waf/install/docker.md | 8 ++--- content/waf/install/kubernetes-plm.md | 26 ++++++++--------- content/waf/install/kubernetes.md | 14 ++++----- content/waf/policies/ip-intelligence.md | 11 +++---- layouts/shortcodes/version-waf-compiler.html | 1 + .../shortcodes/version-waf-config-mgr.html | 1 + layouts/shortcodes/version-waf-enforcer.html | 1 + .../version-waf-ip-intelligence.html | 1 + .../version-waf-policy-controller.html | 1 + layouts/shortcodes/version-waf.html | 1 + 13 files changed, 46 insertions(+), 64 deletions(-) create mode 100644 layouts/shortcodes/version-waf-compiler.html create mode 100644 layouts/shortcodes/version-waf-config-mgr.html create mode 100644 layouts/shortcodes/version-waf-enforcer.html create mode 100644 layouts/shortcodes/version-waf-ip-intelligence.html create mode 100644 layouts/shortcodes/version-waf-policy-controller.html create mode 100644 layouts/shortcodes/version-waf.html diff --git a/content/waf/configure/compiler.md b/content/waf/configure/compiler.md index 160f4e1c3..7dbe55566 100644 --- a/content/waf/configure/compiler.md +++ b/content/waf/configure/compiler.md @@ -7,9 +7,7 @@ weight: 300 toc: true # Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this nd-content-type: how-to -# Intended for internal catalogue and search, case sensitive: -# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit -nd-product: NAP-WAF +nd-product: WAF --- This document describes how to use the F5 WAF for NGINX compiler, a tool for converting security policies and logging profiles from JSON to a bundle file that F5 WAF can process and apply. @@ -64,7 +62,7 @@ This example Dockerfile is based on a Debian image. ```dockerfile # syntax=docker/dockerfile:1 -ARG BASE_IMAGE=private-registry.nginx.com/nap/waf-compiler: +ARG BASE_IMAGE=private-registry.nginx.com/nap/waf-compiler:{{< version-waf-compiler >}} FROM ${BASE_IMAGE} # Installing packages as root @@ -114,23 +112,6 @@ Replace `` with the location of your client key and curl -s https://private-registry.nginx.com/v2/nap/waf-compiler/tags/list --key --cert ``` -```json -{ - "name": "nap/waf-compiler", - "tags": [ - "1.0.0", - "5.1.0", - "5.2.0" - ] -} -``` - -{{< call-out "note" >}} - -The [jq](https://jqlang.github.io/jq/) command was used to format the example output. - -{{< /call-out >}} - ## Build the container image Run the following command to build your image, where `waf-compiler-:custom` is an example of the image tag: @@ -190,7 +171,7 @@ To compile a policy with global settings, add the `-g` parameter: ```shell docker run --rm \ -v $(pwd):$(pwd) \ - waf-compiler-1.0.0:custom \ + waf-compiler-:custom \ -g $(pwd)/global_settings.json -p $(pwd)/policy.json -o $(pwd)/compiled_policy.tgz ``` @@ -199,7 +180,7 @@ You can incorporate the source of the policy (as `policy.json`) or logging profi ```shell docker run --rm \ -v $(pwd):$(pwd) \ - waf-compiler-1.0.0:custom \ + waf-compiler-:custom \ -include-source -full-export -g $(pwd)/global_settings.json -p $(pwd)/policy.json -o $(pwd)/compiled_policy.tgz ``` @@ -236,6 +217,7 @@ When [configuring policies]({{< ref "/waf/policies/configuration.md">}}), you ma There are ways to remediate them based on the context: {{< table >}} + | Description | Solution | | ----------------------- | -------- | | _Expected declarative policy_ | Ensure the JSON of the policy is well-formed | @@ -248,6 +230,7 @@ There are ways to remediate them based on the context: | _Duplicate policy name found_ | Don't compile multiple policies with the same name, or one policy to multiple bundles. Each policy can be compiled once but a bundle can be re-used. | | _Duplicate logging profile name found_ | Don't compile the same logging profile to multiple bundles. Each profile can be compiled once but a bundle can be re-used. | | _Timeout waiting for enforcer_ | Likely an internal issue: [contact Support]({{< ref "/waf/support.md" >}}) | + {{< /table >}} ## Global settings diff --git a/content/waf/fundamentals/technical-specifications.md b/content/waf/fundamentals/technical-specifications.md index cfe7bfddd..f97e38377 100644 --- a/content/waf/fundamentals/technical-specifications.md +++ b/content/waf/fundamentals/technical-specifications.md @@ -14,6 +14,8 @@ nd-product: NAP-WAF This page outlines the technical specifications for F5 WAF for NGINX, which includes the minimum requirements and supported platforms. +The latest version of F5 WAF for NGINX is {{< version-waf >}}. + ## Resource limitations - F5 WAF for NGINX supports a **maximum** of **127** CPU cores. diff --git a/content/waf/install/disconnected-environment.md b/content/waf/install/disconnected-environment.md index 8891d5613..f51ace3cd 100644 --- a/content/waf/install/disconnected-environment.md +++ b/content/waf/install/disconnected-environment.md @@ -7,9 +7,7 @@ weight: 500 toc: false # Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this nd-content-type: how-to -# Intended for internal catalogue and search, case sensitive: -# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit -nd-product: NAP-WAF +nd-product: WAF --- This topic describes how to install F5 WAF for NGINX in a disconnected or air-gapped environment. @@ -48,7 +46,6 @@ You will need `git` and `wget` in your connected environment. Run the following two commands: replace `` with the tarball appropriate to the environment from [the release page](https://github.com/gohugoio/hugo/releases/tag/v0.147.8): - ```shell git clone git@github.com:nginx/documentation.git wget @@ -97,10 +94,10 @@ Once you've obtained the package files and transferred them to your disconnected After pulling or building Docker images in a connected environment, you can save them to `.tar` files: ```shell -docker save -o waf-enforcer.tar waf-enforcer:5.2.0 -docker save -o waf-config-mgr.tar waf-config-mgr:5.2.0 +docker save -o waf-enforcer.tar waf-enforcer:{{< version-waf-enforcer >}} +docker save -o waf-config-mgr.tar waf-config-mgr:{{< version-waf-config-mgr >}} # Optional, if using IP intelligence -docker save -o waf-ip-intelligence.tar waf-ip-intelligence:5.2.0 +docker save -o waf-ip-intelligence.tar waf-ip-intelligence:{{< version-waf-ip-intelligence >}} ``` You can then transfer the files and load the images in your disconnected environment: @@ -112,5 +109,4 @@ docker load -i waf-config-mgr.tar docker load -i waf-ip-intelligence.tar ``` -Ensure your Docker compose files use the tagged images you've transferred. - +Ensure your Docker compose files use the tagged images you've transferred. \ No newline at end of file diff --git a/content/waf/install/docker.md b/content/waf/install/docker.md index d54ca7d2d..57bd6a355 100644 --- a/content/waf/install/docker.md +++ b/content/waf/install/docker.md @@ -7,9 +7,7 @@ weight: 400 toc: true # Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this nd-content-type: how-to -# Intended for internal catalogue and search, case sensitive: -# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit -nd-product: NAP-WAF +nd-product: WAF --- This page describes how to install F5 WAF for NGINX using Docker. @@ -466,7 +464,7 @@ services: waf-enforcer: container_name: waf-enforcer - image: waf-enforcer:5.2.0 + image: waf-enforcer:{{< version-waf-enforcer >}} environment: - ENFORCER_PORT=50000 ports: @@ -479,7 +477,7 @@ services: waf-config-mgr: container_name: waf-config-mgr - image: waf-config-mgr:5.2.0 + image: waf-config-mgr:{{< version-waf-config-mgr >}} volumes: - /opt/app_protect/bd_config:/opt/app_protect/bd_config - /opt/app_protect/config:/opt/app_protect/config diff --git a/content/waf/install/kubernetes-plm.md b/content/waf/install/kubernetes-plm.md index d127e6bc1..b53ef0998 100644 --- a/content/waf/install/kubernetes-plm.md +++ b/content/waf/install/kubernetes-plm.md @@ -11,9 +11,7 @@ nd-banner: md: /_banners/waf-early-availability.md # Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this nd-content-type: reference -# Intended for internal catalogue and search, case sensitive: -# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit -nd-product: NAP-WAF +nd-product: WAF --- There are two new features available for Kubernetes through early access: @@ -278,7 +276,7 @@ appprotect: ## The image repository of the WAF Config Mgr repository: private-registry.nginx.com/nap/waf-config-mgr ## The tag of the WAF Config Mgr image - tag: 5.9.0 + tag: {{< version-waf-config-mgr >}} ## The pull policy for the WAF Config Mgr image imagePullPolicy: IfNotPresent ## The resources of the Waf Config Manager container @@ -295,7 +293,7 @@ appprotect: ## The image repository of the WAF Enforcer repository: private-registry.nginx.com/nap/waf-enforcer ## The tag of the WAF Enforcer image - tag: 5.9.0 + tag: {{< version-waf-enforcer >}} ## The pull policy for the WAF Enforcer image imagePullPolicy: IfNotPresent ## The environment variable for enforcer port to be set on the WAF Enforcer container @@ -316,7 +314,7 @@ appprotect: ## The image repository of the WAF IP Intelligence repository: private-registry.nginx.com/nap/waf-ip-intelligence ## The tag of the WAF IP Intelligence - tag: 5.9.0 + tag: {{< version-waf-ip-intelligence >}} ## The pull policy for the WAF IP Intelligence imagePullPolicy: IfNotPresent ## The resources of the WAF IP Intelligence container @@ -336,8 +334,8 @@ appprotect: ## The image repository of the WAF Policy Controller image: repository: private-registry.nginx.com/nap/waf-policy-controller - ## The tag of the WAF Policy COntroller - tag: 5.9.0 + ## The tag of the WAF Policy Controller + tag: {{< version-waf-policy-controller >}} ## The pull policy for the WAF Policy Controller imagePullPolicy: IfNotPresent wafCompiler: @@ -345,7 +343,7 @@ appprotect: image: repository: private-registry.nginx.com/nap/waf-compiler ## The tag of the WAF Compiler image - tag: 5.9.0 + tag: {{< version-waf-compiler >}} ## Save logs before deleting a job or not enableJobLogSaving: false ## The resources of the WAF Policy Controller @@ -710,6 +708,7 @@ kubectl apply -f apple-usersig.yaml -n You can check the status of your resources using `kubectl get` or `kubectl describe`. The Policy Controller will show status information including: + - Bundle location - Compilation status - Signature update timestamps @@ -717,6 +716,7 @@ The Policy Controller will show status information including: ```shell kubectl get appolicy dataguard-blocking -n -o yaml ``` + ```yaml apiVersion: appprotect.f5.com/v1 kind: APPolicy @@ -744,6 +744,7 @@ status: ```shell kubectl describe appolicy dataguard-blocking -n ``` + ```text Name: dataguard-blocking Namespace: localenv-plm @@ -1323,7 +1324,6 @@ The Policy Controller will detect the file changes and recompile automatically. Regardless of the policy type used, you can monitor the status of your policies using standard Kubernetes commands: - ```shell kubectl get appolicy -n kubectl describe appolicy -n @@ -1358,19 +1358,19 @@ status: ## Possible issues -**Policy Controller does not start** +_Policy Controller does not start:_ - Verify the CRDs are installed: `kubectl get crds | grep appprotect.f5.com` - Check the pod logs: `kubectl logs -n ` - Ensure proper RBAC permissions are configured -**Policies fail to compile** +_Policies fail to compile:_ - Check Policy Controller logs for compilation errors - Verify the WAF compiler image is accessible - Ensure the policy syntax is valid -**Issues with bundle storage** +_Issues with bundle storage:_ - Verify the persistent volume is properly mounted - Check storage permissions (Should be 101:101) diff --git a/content/waf/install/kubernetes.md b/content/waf/install/kubernetes.md index 8bdc4e909..4318dd42f 100644 --- a/content/waf/install/kubernetes.md +++ b/content/waf/install/kubernetes.md @@ -7,9 +7,7 @@ weight: 200 toc: true # Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this nd-content-type: how-to -# Intended for internal catalogue and search, case sensitive: -# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit -nd-product: NAP-WAF +nd-product: WAF --- This page describes how to install F5 WAF for NGINX using Kubernetes. @@ -237,6 +235,7 @@ To get the Helm chart, first configure Docker for the F5 Container Registry. {{< include "waf/install-services-registry.md" >}} Then use `helm pull` to get the chart, replacing ``: + ```shell helm pull oci://private-registry.nginx.com/nap/nginx-app-protect --version --untar ``` @@ -305,6 +304,7 @@ This table lists the configurable parameters of the F5 WAF for NGINX Helm chart To understand the _mTLS Configuration_ options, view the [Secure traffic using mTLS]({{< ref "/waf/configure/secure-mtls.md" >}}) topic. {{< table >}} + | **Topic** | **Parameter** | **Description** | **Default value** | |-------------|---------|-----------------|-------------------| | **Namespace** | _namespace_ | The target Kubernetes namespace where the Helm chart will be deployed. | N/A | @@ -316,17 +316,17 @@ To understand the _mTLS Configuration_ options, view the [Secure traffic using m | | _appprotect.nginx.imagePullPolicy_ | Image pull policy. | IfNotPresent | | | _appprotect.nginx.resources_ | The resources of the NGINX container. | requests: cpu=10m,memory=16Mi | | **WAF Config Manager** | _appprotect.wafConfigMgr.image.repository_ | Docker image repository for the WAF Configuration Manager. | private-registry.nginx.com/nap/waf-config-mgr | -| | _appprotect.wafConfigMgr.image.tag_ | Docker image tag for the WAF Configuration Manager. | 5.6.0 | +| | _appprotect.wafConfigMgr.image.tag_ | Docker image tag for the WAF Configuration Manager. | {{< version-waf-config-mgr >}} | | | _appprotect.wafConfigMgr.imagePullPolicy_ | Image pull policy. | IfNotPresent | | | _appprotect.wafConfigMgr.resources_ | The resources of the WAF Config Manager container. | requests: cpu=10m,memory=16Mi | | **WAF Enforcer** | _appprotect.wafEnforcer.image.repository_ | Docker image repository for the WAF Enforcer. | private-registry.nginx.com/nap/waf-enforcer | -| | _appprotect.wafEnforcer.image.tag_ | Docker image tag for the WAF Enforcer. | 5.6.0 | +| | _appprotect.wafEnforcer.image.tag_ | Docker image tag for the WAF Enforcer. | {{< version-waf-enforcer >}} | | | _appprotect.wafEnforcer.imagePullPolicy_ | Image pull policy. | IfNotPresent | | | _appprotect.wafEnforcer.env.enforcerPort_ | Port for the WAF Enforcer. | 50000 | | | _appprotect.wafEnforcer.resources_ | The resources of the WAF Enforcer container. | requests: cpu=20m,memory=256Mi | | **WAF IP Intelligence** | _appprotect.wafIpIntelligence.enable | Enable or disable the use of the IP intelligence container | false | | | _appprotect.wafIpIntelligence.image.repository_ | Docker image repository for the WAF IP Intelligence. | private-registry.nginx.com/nap/waf-ip-intelligence | -| | _appprotect.wafIpIntelligence.image.tag_ | Docker image tag for the WAF Enforcer. | 5.6.0 | +| | _appprotect.wafIpIntelligence.image.tag_ | Docker image tag for the WAF Enforcer. | {{< version-waf-ip-intelligence >}} | | | _appprotect.wafIpIntelligence.imagePullPolicy_ | Image pull policy. | IfNotPresent | | | _appprotect.wafIpIntelligence.resources_ | The resources of the WAF Enforcer container. | requests: cpu=10m,memory=256Mi | | **Config** | _appprotect.config.name_ | The name of the ConfigMap used by the NGINX container. | nginx-config | @@ -353,6 +353,7 @@ To understand the _mTLS Configuration_ options, view the [Secure traffic using m | | _appprotect.storage.pvc.bundlesPvc.storageClass_ | Storage class for PVC. | manual | | | _appprotect.storage.pvc.bundlesPvc.storageRequest_ | Storage request size. | 2Gi | | **Docker Configuration** | _dockerConfigJson_ | A base64-encoded string representing the Docker registry credentials in JSON format. | N/A | + {{< /table >}} ## Use Manifests to install F5 WAF for NGINX @@ -538,7 +539,6 @@ spec: {{< /tabs >}} - ### Start the Manifest deployment From the folder containing the YAML files from the previous step (Suggested as `/manifests`), deploy F5 WAF for NGINX using `kubectl`: diff --git a/content/waf/policies/ip-intelligence.md b/content/waf/policies/ip-intelligence.md index 85691082c..71f8624b5 100644 --- a/content/waf/policies/ip-intelligence.md +++ b/content/waf/policies/ip-intelligence.md @@ -7,9 +7,7 @@ weight: 1600 toc: true # Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this nd-content-type: reference -# Intended for internal catalogue and search, case sensitive: -# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit -nd-product: NAP-WAF +nd-product: WAF --- F5 WAF for NGINX has an IP intelligence feature which allows you to customize enforcement based on the source IP address of a request. This allows you to limit access from specific IP addresses. @@ -106,7 +104,7 @@ Modify the _original docker-compose.yml_ file to include the IP intelligence con services: waf-enforcer: container_name: waf-enforcer - image: waf-enforcer:5.7.0 + image: waf-enforcer:{{< version-waf-enforcer >}} environment: - ENFORCER_PORT=50000 ports: @@ -122,7 +120,7 @@ services: waf-config-mgr: container_name: waf-config-mgr - image: waf-config-mgr:5.7.0 + image: waf-config-mgr:{{< version-waf-config-mgr >}} volumes: - /opt/app_protect/bd_config:/opt/app_protect/bd_config - /opt/app_protect/config:/opt/app_protect/config @@ -135,7 +133,7 @@ services: waf-ip-intelligence: container_name: waf-ip-intelligence - image: waf-ip-intelligence:5.7.0 + image: waf-ip-intelligence:{{< version-waf-ip-intelligence >}} volumes: - /var/IpRep:/var/IpRep networks: @@ -238,7 +236,6 @@ spec: claimName: nap5-bundles-pvc ``` - Once complete, you can now [Configure policies for IP intelligence](#configure-policies-for-ip-intelligence). ## Configure policies for IP intelligence diff --git a/layouts/shortcodes/version-waf-compiler.html b/layouts/shortcodes/version-waf-compiler.html new file mode 100644 index 000000000..cf5136119 --- /dev/null +++ b/layouts/shortcodes/version-waf-compiler.html @@ -0,0 +1 @@ +5.9.0 \ No newline at end of file diff --git a/layouts/shortcodes/version-waf-config-mgr.html b/layouts/shortcodes/version-waf-config-mgr.html new file mode 100644 index 000000000..cf5136119 --- /dev/null +++ b/layouts/shortcodes/version-waf-config-mgr.html @@ -0,0 +1 @@ +5.9.0 \ No newline at end of file diff --git a/layouts/shortcodes/version-waf-enforcer.html b/layouts/shortcodes/version-waf-enforcer.html new file mode 100644 index 000000000..3b867ccd7 --- /dev/null +++ b/layouts/shortcodes/version-waf-enforcer.html @@ -0,0 +1 @@ +5.7.0 \ No newline at end of file diff --git a/layouts/shortcodes/version-waf-ip-intelligence.html b/layouts/shortcodes/version-waf-ip-intelligence.html new file mode 100644 index 000000000..cf5136119 --- /dev/null +++ b/layouts/shortcodes/version-waf-ip-intelligence.html @@ -0,0 +1 @@ +5.9.0 \ No newline at end of file diff --git a/layouts/shortcodes/version-waf-policy-controller.html b/layouts/shortcodes/version-waf-policy-controller.html new file mode 100644 index 000000000..cf5136119 --- /dev/null +++ b/layouts/shortcodes/version-waf-policy-controller.html @@ -0,0 +1 @@ +5.9.0 \ No newline at end of file diff --git a/layouts/shortcodes/version-waf.html b/layouts/shortcodes/version-waf.html new file mode 100644 index 000000000..b883184b1 --- /dev/null +++ b/layouts/shortcodes/version-waf.html @@ -0,0 +1 @@ +5.9 \ No newline at end of file