Update Azure Web Application Firewall on Application Gateway for Containers with the Gateway API

[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."
  }
}

[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 6b6d708:

⚠️ Validation status: warnings

File	Status	Preview URL	Details
articles/application-gateway/for-containers/how-to-waf-gateway-api.md	⚠️Warning		Details

articles/application-gateway/for-containers/how-to-waf-gateway-api.md

• Line 35, Column 250: [Warning: hard-coded-locale - See documentation] Link 'https://learn.microsoft.com/en-us/cli/azure/network/application-gateway/waf-policy?view=azure-cli-latest' contains locale code 'en-us'. For localizability, remove 'en-us' from links to most Microsoft sites.
• Line 35, Column 250: [Suggestion: docs-link-absolute - See documentation] Absolute link 'https://learn.microsoft.com/en-us/cli/azure/network/application-gateway/waf-policy?view=azure-cli-latest' will be broken in isolated environments. Replace with a relative link.
• Line 35, Column 250: [Suggestion: preserve-view-not-set - See documentation] You've pinned this link to a specific version of content with the view parameter. It's recommended not to pin a version unless that version is A) not the default view and B) the context is about that version specifically. To proceed with pinning a version add the &preserve-view=true to the URL. Otherwise, remove the view parameter. URL: https://learn.microsoft.com/en-us/cli/azure/network/application-gateway/waf-policy?view=azure-cli-latest

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

[learn-build-service-prod]

Learn Build status updates of commit 7f5a24e:

✅ Validation status: passed

File	Status	Preview URL	Details
articles/application-gateway/for-containers/how-to-waf-gateway-api.md	✅Succeeded

For more details, please refer to the build report.

[Copilot]

Pull request overview

This PR enhances the Azure Web Application Firewall documentation for Application Gateway for Containers by adding critical prerequisites and troubleshooting guidance that were previously missing. The changes address a common deployment failure where WAF policies cannot be assigned due to missing permissions or non-existent resources.

• Adds two essential prerequisites: pre-existing WAF policy requirement and ALB Controller identity permissions
• Introduces a new troubleshooting section to help users diagnose and resolve 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 43fa6cc:

✅ Validation status: passed

File	Status	Preview URL	Details
articles/application-gateway/for-containers/how-to-waf-gateway-api.md	✅Succeeded

For more details, please refer to the build report.

[learn-build-service-prod]

Learn Build status updates of commit ea2e84e:

✅ Validation status: passed

File	Status	Preview URL	Details
articles/application-gateway/for-containers/how-to-waf-gateway-api.md	✅Succeeded

For more details, please refer to the build report.