Update Azure Web Application Firewall on Application Gateway for Containers

[WolfgangOfner]

Following the documentation in its current state will lead to a non functional WAF policy assignment. The documentation is missing two key components:

1. The WAF policy you want assign must already exist
2. The service principal of the ALB Controller needs the right permission on the WAF policy to assign it.

This PR aims to provide more guidance on how to setup everything and what to do in case something went wrong.

Technical details

Assigning an existing WAF policy as described in the documentation will not work. The statue of the deployment is False which can be checked with kubectl get WebApplicationFirewallPolicy $WafPolicy -n $InfrastructureNamespace. The state of the WebApplicationFirewallPolicy can be checked with kubectl describe WebApplicationFirewallPolicy $WafPolicy -n $InfrastructureNamespace. In the output, you will see an error message that looks something like:

RESPONSE 403: 403 Forbidden
ERROR CODE: LinkedAuthorizationFailed
--------------------------------------------------------------------------------
{
  "error": {
    "code": "LinkedAuthorizationFailed",
    "message": "The client '747751ee-7816-4be2-9d18-c75d579ddfae' with object id 'e100d827-3bbf-4332-957c-880818145fc8' has permission to perform action 'Microsoft.ServiceNetworking/trafficControllers/securityPolicies/write' on scope '/subscriptions/e347e896-c1d2-4aea-b63d-2c7f5f6acc7e/resourceGroups/mc_app-gateway-container-rg_app-gateway-container-aks_canadacentral/providers/Microsoft.ServiceNetworking/trafficControllers/alb-b9cf67d1/securityPolicies/sp-87c60681-45cb3d470fd3d292887df0fc9d43ede061f35cbf'; however, it does not have permission to perform action(s) 'microsoft.network/applicationgatewaywebapplicationfirewallpolicies/join/action' on the linked scope(s) '/subscriptions/e347e896-c1d2-4aea-b63d-2c7f5f6acc7e/resourcegroups/app-gateway-container-rg/providers/microsoft.network/applicationgatewaywebapplicationfirewallpolicies/waf-policy' (respectively) or the linked scope(s) are invalid."
  }
}

[learn-build-service-prod]

Learn Build status updates of commit 3669656:

✅ Validation status: passed

File	Status	Preview URL	Details
articles/application-gateway/for-containers/web-application-firewall.md	✅Succeeded

For more details, please refer to the build report.

[WolfgangOfner]

@microsoft-github-policy-service agree

[prmerger-automator]

@WolfgangOfner : Thanks for your contribution! The author(s) and reviewer(s) have been notified to review your proposed change.

[learn-build-service-prod]

Learn Build status updates of commit 3669656:

✅ Validation status: passed

File	Status	Preview URL	Details
articles/application-gateway/for-containers/web-application-firewall.md	✅Succeeded

For more details, please refer to the build report.

[Copilot]

Pull request overview

This PR enhances the Azure Web Application Firewall (WAF) documentation for Application Gateway for Containers by adding critical prerequisites and troubleshooting guidance. The documentation previously lacked essential information that would lead to non-functional WAF policy assignments.

Key changes:

• Added prerequisites section explaining required WAF policy existence and service principal permissions
• Added troubleshooting section with commands to diagnose common deployment issues

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[ttorble]

@JackStromberg

Can you review the proposed changes?

IMPORTANT: When the changes are ready for publication, adding a #sign-off comment is the best way to signal that the PR is ready for the review team to merge.

#label:"aq-pr-triaged"
@MicrosoftDocs/public-repo-pr-review-team

[learn-build-service-prod]

Learn Build status updates of commit b1fafc6:

✅ Validation status: passed

File	Status	Preview URL	Details
articles/application-gateway/for-containers/web-application-firewall.md	✅Succeeded

For more details, please refer to the build report.