Merge pull request #235746 from vhorne/waf-upgrade

add upgrade waf policy

Author: JamesJBarnett

articles/web-application-firewall/ag/create-waf-policy-ag.md

@@ -20,7 +20,7 @@ If your Application Gateway has an associated policy, and then you associated a
    > [!NOTE]
    > Once a Firewall Policy is associated to a WAF, there must always be a policy associated to that WAF. You may overwrite that policy, but disassociating a policy from the WAF entirely isn't supported. 
 
-All new Web Application Firewall's WAF settings (custom rules, managed ruleset configurations, exclusions, etc.) live inside of a WAF Policy. If you have an existing WAF, these settings may still exist in your WAF config. For steps on how to move to the new WAF Policy, see [Migrate your WAF Config to a WAF Policy](#migrate) later in this article. 
+All new Web Application Firewall's WAF settings (custom rules, managed ruleset configurations, exclusions, etc.) live inside of a WAF Policy. If you have an existing WAF, these settings may still exist in your WAF config. For steps on how to move to the new WAF Policy, see [Upgrade your WAF Config to a WAF Policy](#upgrade) later in this article. 
 
 ## Create a policy
 
@@ -65,7 +65,7 @@ To create a custom rule, select **Add custom rule** under the **Custom rules** t
 
 [ ![Edit custom rule](../media/create-waf-policy-ag/edit-custom-rule.png) ](../media/create-waf-policy-ag/edit-custom-rule-lrg.png#lightbox)
 
-## <a name="migrate"></a>Migrate your WAF Config to a WAF Policy
+## <a name="upgrade"></a>Upgrade your WAF Config to a WAF Policy
 
 If you have an existing WAF, you may have noticed some changes in the portal. First you need to identify what kind of Policy you've enabled on your WAF. There are three potential states:
 
@@ -85,15 +85,15 @@ If it also shows Policy Settings and Managed Rules, then it's a full Web Applica
 
 ![WAF policy settings](../media/create-waf-policy-ag/waf-policy-settings.png)
 
-## Migrate to WAF Policy
+## Upgrade to WAF Policy
 
 If you have a Custom Rules only WAF Policy, then you may want to move to the new WAF Policy. Going forward, the firewall policy will support WAF policy settings, managed rulesets, exclusions, and disabled rule-groups. Essentially, all the WAF configurations that were previously done inside the Application Gateway are now done through the WAF Policy. 
 
-Edits to the custom rule only WAF policy are disabled. To edit any WAF settings such as disabling rules, adding exclusions, etc. you have to migrate to a new top-level firewall policy resource.
+Edits to the custom rule only WAF policy are disabled. To edit any WAF settings such as disabling rules, adding exclusions, etc. you have to upgrade to a new top-level firewall policy resource.
 
 To do so, create a *Web Application Firewall Policy* and associate it to your Application Gateway(s) and listener(s) of choice. This new Policy must be exactly the same as the current WAF config, meaning every custom rule, exclusion, disabled rule, etc. must be copied into the new Policy you're creating. Once you have a Policy associated with your Application Gateway, then you can continue to make changes to your WAF rules and settings. You can also do this with Azure PowerShell. For more information, see [Associate a WAF policy with an existing Application Gateway](associate-waf-policy-existing-gateway.md).
 
-Optionally, you can use a migration script to migrate to a WAF policy. For more information, see [Migrate Web Application Firewall policies using Azure PowerShell](migrate-policy.md).
+Optionally, you can use a migration script to upgrade to a WAF policy. For more information, see [Upgrade Web Application Firewall policies using Azure PowerShell](migrate-policy.md).
 
 ## Force mode
 

articles/web-application-firewall/ag/migrate-policy.md

@@ -1,6 +1,6 @@
 ---
-title: Migrate WAF policies for Azure Application Gateway
-description: Learn how to migrate Azure Web Application Firewall policies using Azure PowerShell.
+title: Upgrade WAF policies for Azure Application Gateway
+description: Learn how to upgrade Azure Web Application Firewall policies using Azure PowerShell.
 services: web-application-firewall
 ms.topic: how-to
 author: vhorne
@@ -10,13 +10,13 @@ ms.author: victorh
 ms.custom: devx-track-azurepowershell
 ---
 
-# Migrate Web Application Firewall policies using Azure PowerShell
+# Upgrade Web Application Firewall policies using Azure PowerShell
 
-This script makes it easy to transition from a WAF config or a custom rules-only WAF policy to a full WAF policy. You may see a warning in the portal that says *migrate to WAF policy*, or you may want the new WAF features such as Geomatch custom rules, per-site WAF policy, and per-URI WAF policy (preview), or the bot mitigation ruleset. To use any of these features, you need a full WAF policy associated to your application gateway. 
+This script makes it easy to transition from a WAF config or a custom rules-only WAF policy to a full WAF policy. You may see a warning in the portal that says *upgrade to WAF policy*, or you may want the new WAF features such as Geomatch custom rules, per-site WAF policy, and per-URI WAF policy, or the bot mitigation ruleset. To use any of these features, you need a full WAF policy associated to your application gateway. 
 
-For more information about creating a new WAF policy, see [Create Web Application Firewall policies for Application Gateway](create-waf-policy-ag.md). For information about migrating, see [Migrate to WAF policy](create-waf-policy-ag.md#migrate-to-waf-policy).
+For more information about creating a new WAF policy, see [Create Web Application Firewall policies for Application Gateway](create-waf-policy-ag.md). For information about migrating, see [upgrade to WAF policy](create-waf-policy-ag.md#upgrade-to-waf-policy).
 
-## To migrate to WAF policy using the migration script
+## To upgrade to WAF policy using the migration script
 
 Use the following steps to run the migration script: 
 
@@ -35,7 +35,7 @@ Use the following steps to run the migration script:
 ```azurepowershell-interactive
 <#PSScriptInfo
 .DESCRIPTION
-Will be used to migrate to the application-gateway to a top level waf policy experience.
+Will be used to upgrade to the application-gateway to a top level waf policy experience.
 
 .VERSION 1.0
 
@@ -90,7 +90,7 @@ function ValidateInput ($appgwName, $resourceGroupName) {
             foreach ($disabled in $appgw.WebApplicationFirewallConfiguration.DisabledRuleGroups) {
                 if ($disabled.Rules.Count -eq 0) {
                     $ruleGroupName = $disabled.RuleGroupName
-                    Write-Error "The ruleGroup '$ruleGroupName' is disabled. Currently we can't migrate to a firewall policy when an entire ruleGroup is disabled. This feature will be delivered shortly. To continue, kindly ensure the entire rulegroups are not disabled. "
+                    Write-Error "The ruleGroup '$ruleGroupName' is disabled. Currently we can't upgrade to a firewall policy when an entire ruleGroup is disabled. This feature will be delivered shortly. To continue, kindly ensure the entire rulegroups are not disabled. "
                     return $false
                 }
             }
@@ -100,7 +100,7 @@ function ValidateInput ($appgwName, $resourceGroupName) {
         if ($appgw.WebApplicationFirewallConfiguration.Exclusions) {
             foreach ($excl in $appgw.WebApplicationFirewallConfiguration.Exclusions) {
                 if ($null -ne $excl.MatchVariable -and $null -eq $excl.SelectorMatchOperator -and $null -eq $excl.Selector) {
-                    Write-Error " You have an exclusion entry(s) with the 'Equals any' operator. Currently we can't migrate to a firewall policy with 'Equals Any' operator. This feature will be delivered shortly. To continue, kindly ensure exclusion entries with 'Equals Any' operator is not present. "
+                    Write-Error " You have an exclusion entry(s) with the 'Equals any' operator. Currently we can't upgrade to a firewall policy with 'Equals Any' operator. This feature will be delivered shortly. To continue, kindly ensure exclusion entries with 'Equals Any' operator is not present. "
                     return $false
                 }
             }

articles/web-application-firewall/ag/upgrade-ag-waf-policy.md

@@ -0,0 +1,73 @@
+---
+title: Upgrade to Azure Application Gateway WAF policy
+description: Learn how to upgrade Azure Application Gateway WAF policy.
+services: web-application-firewall
+ms.topic: how-to
+author: vhorne
+ms.service: web-application-firewall
+ms.date: 04/25/2023
+ms.author: lunowak
+ms.custom: devx-track-azurepowershell
+---
+
+# Upgrade to Azure Application Gateway WAF policy
+
+Azure Web Application Firewall (WAF) provides centralized protection of your web applications from common exploits and vulnerabilities. Web Application Firewall Policies contain all the WAF settings and configurations. This includes exclusions, custom rules, managed rules, and so on. These policies are then associated with an application gateway (global), a listener (per-site), or a path-based rule (per-URI) for them to take effect.
+
+Azure Application Gateway WAF v2 natively supports WAF policy. You should upgrade your legacy WAF configuration to WAF policies.
+
+- Policies offer a richer set of advanced features. This includes newer managed rule sets, custom rules, per rule exclusions, bot protection, and the next generation of WAF engine. These advanced features are available to you at no extra cost.
+- WAF policies provide higher scale and better performance.
+- Unlike legacy WAF configuration, WAF policies can be defined once and shared across multiple gateways, listeners, and URL paths. This simplifies the management and deployment experience.
+- The latest features and future enhancements are only available via WAF policies. 
+
+> [!IMPORTANT]
+> No further investments will be made on legacy WAF configuration. You are strongly encouraged to upgrade from legacy WAF configuration to WAF Policy for easier management, better scale, and a richer feature set at no additional cost.
+
+## Upgrade Application Gateway Standard v2 to Application Gateway WAF v2
+
+1. Locate the Application Gateway in the Azure portal. Select the Application Gateway and the select **Configuration** from the **Settings** menu on the left side.
+1. Under **Tier**, select **WAF V2**.
+1. Select **Save** to complete the upgrade from Application Gateway Standard to Application Gateway WAF.
+
+## Upgrade WAF v2 with legacy WAF configuration to WAF policy
+
+You can upgrade existing Application Gateways with WAF v2 from WAF legacy configuration to WAF policy directly without any downtime. You can upgrade using either using the portal, Firewall Manager, or Azure PowerShell.
+
+# [Portal](#tab/portal)
+
+1. Sign in to the Azure portal and select the Application Gateway WAF v2 that has a legacy WAF configuration.
+1. Select **Web Application Firewall** from the left menu, then select **Upgrade from WAF configuration**.
+1. Provide a name for the new WAF Policy and then select **Upgrade**. This creates a new WAF Policy based on the WAF configuration. You can also choose to associate a pre-existing WAF Policy instead of creating a new one.
+1. When the upgrade finishes, a new WAF Policy incorporating the previous WAF configuration and rules is created. 
+
+# [Firewall Manager](#tab/fwm)
+
+See [Configure WAF policies using Azure Firewall Manager](../shared/manage-policies.md).
+
+# [PowerShell](#tab/powershell)
+
+See [Upgrade Web Application Firewall policies using Azure PowerShell](migrate-policy.md).
+
+---
+
+## Upgrade Application Gateway v1 to WAF v2 with WAF policy
+
+Application Gateway v1 doesn't support WAF policy. Upgrading to WAF policy is a two step process:
+
+- Upgrade Application Gateway v1 to v2 version.
+- Upgrade legacy WAF configuration to WAF policy.
+
+1. Upgrade from v1 to v2 Application Gateway.
+
+   For more information, see [Upgrade Azure Application Gateway and Web Application Firewall from v1 to v2](../../application-gateway/migrate-v1-v2.md).
+
+   When you complete the upgrade of v1 to v2, the Application Gateway v2 has a legacy WAF configuration.
+2. Upgrade to Application Gateway WAF v2 with WAF Policy.
+
+   - If in Step 1 you upgraded from Application Gateway Standard v1 to v2, see the previous section [Upgrade Application Gateway Standard v2 to Application Gateway WAF v2](#upgrade-application-gateway-standard-v2-to-application-gateway-waf-v2).
+   - If in Step 1, you upgraded from Application Gateway WAF v1 to Application Gateway WAF v2 with legacy configuration, see the previous section [Upgrade WAF v2 with legacy WAF configuration to WAF policy](#upgrade-waf-v2-with-legacy-waf-configuration-to-waf-policy) to migrate to Application Gateway WAF v2 SKU with WAF policy.
+
+## Next steps
+
+For more information about WAF on Application Gateway policy, see [Azure Web Application Firewall (WAF) policy overview](policy-overview.md).

articles/web-application-firewall/toc.yml

@@ -114,10 +114,14 @@
          href: ./ag/tutorial-restrict-web-traffic-powershell.md
        - name: Azure CLI
          href: ./ag/tutorial-restrict-web-traffic-cli.md
+     - name: Upgrade WAF
+       items:
+       - name: Upgrade to WAF policy
+         href: ./ag/upgrade-ag-waf-policy.md
+       - name: Upgrade using PowerShell
+         href: ./ag/migrate-policy.md
      - name: Per-site policies
        href: ./ag/per-site-policies.md
-     - name: Migrate WAF policy
-       href: ./ag/migrate-policy.md
      - name: Customize WAF rules
        items:
        - name: Azure portal