Update WAF v5 docs for v4.1.0 release

[shaun-nx]

Overview

As a user of NGINX App Protect WAF and NGINX Ingress Controller
I want clarity around what NGINX App Protect WAF is capable of
So I can use it without confusion

Details

This request comes from Aviv Dahan, the PM for NGINX App Protect WAF:

"F5 recommends compiling/recompiling your NGINX AppProtect WAF Policy Bundles"- A bundle itself isn't compiled; rather, you compile a policy, which then generates a bundle.
i found it confusing, users might not understand that the intention is for JSON policies.

We are stating an irrelevant limitation that adds operational complexity “F5 recommends compiling ...with each release of NGINX Ingress Controller”. This limitation should be removed.
The note feels more oriented with 'upgrade' procedure (it mentions 'with each release') rather on fresh deployment.
Instead, i would expect to see it under the 'Enable NGINX App Protect WAF v5' section, with clear steps to eliminate confusion.

This feedback concerns the NGINX App Protect WAF V5 section.

Tasks

• Update the WAF v5 documentation to highlight that policies no longer require recompilation during upgrade after NIC 4.1
• Remove the word "bundle" from documentation, which creates ambiguity around the policies
• Add or move the steps to compile/recompile a bundle under the "Enable NGINX App Protect WAF v5" section
• Check if any of the changes should also affect the v4 documentation

Acceptance criteria

• The user has clarity on what F5 recommends as standard practice
• The user understands what limitations exist for the software
• The user is presented important information at the contextually appropriate time

[github-actions]

Hi @shaun-nx thanks for reporting!

Be sure to check out the docs and the Contributing Guidelines while you wait for a human to take a look at this 🙂

Cheers!

[ADubhlaoich]

@shaun-nx I will probably edit your original issue to refine it. There's some missing detail from an e-mail thread about it, and there's no acceptance criteria: that is a list of tasks, not fulfilled user needs.

[ADubhlaoich]

Issue refined, starting the work now. It'll be a PR branched from main, per the release process (Which I am thankful the engineers have reminded me of)

[ADubhlaoich]

I've moved the compatibility table up to the "Before you begin" section since it's important for a user to know at the start what versions of things work together. This itself will likely need updating: I'm going to turn this into an include in anticipation of future re-use.

[ADubhlaoich]

Reading farther into the issue, I've removed the entire note about compiling policies from the build document, and moved it in the configuration document down to the section about bundles.

In the former case, the focus of the topic is building NIC and NAP together: it's not an upgrade instruction, so mentioning that policies should be recompiled with upgrades is an irrelevant detail.

In the latter case, the relevant text is juxtaposed to the section most relevant, but I'm also under the impression the recommendation might not be needed anymore.

[ADubhlaoich]

Linked a pull request: there's further work to be done here.

From investigating this ticket, there's essentially no information anywhere about what it means to upgrade NAP WAF.

It doesn't exist in the NIC docset, and the closest we get within NAP itself is a document on upgrading NAP instances if you're using NIM.

This is a big problem area that requires its own discrete ticket.