|
| 1 | +--- |
| 2 | +title: Migrate Azure Application Gateway and Web Application Firewall from v1 to v2 |
| 3 | +description: This article shows you how to migrate Azure Application Gateway and Web Application Firewall from v1 to v2 |
| 4 | +services: application-gateway |
| 5 | +author: vhorne |
| 6 | +ms.service: application-gateway |
| 7 | +ms.topic: article |
| 8 | +ms.date: 6/1/2019 |
| 9 | +ms.author: victorh |
| 10 | +--- |
| 11 | + |
| 12 | +# Migrate Azure Application Gateway and Web Application Firewall from v1 to v2 |
| 13 | + |
| 14 | +[Azure Application Gateway and Web Application Firewall (WAF) v2](application-gateway-autoscaling-zone-redundant.md) is now available, offering additional features such as autoscaling and availability-zone redundancy. However, existing v1 gateways aren't automatically upgraded to v2. If you want to migrate from v1 to v2, follow the steps in this article. |
| 15 | + |
| 16 | +There are two stages in a migration: |
| 17 | + |
| 18 | +1. Migrate the configuration |
| 19 | +2. Migrate the client traffic |
| 20 | + |
| 21 | +This article covers configuration migration. Client traffic migration varies depending on your specific environment. However, some high-level, general recommendations [are provided](#migrate-client-traffic). |
| 22 | + |
| 23 | +## Migration overview |
| 24 | + |
| 25 | +An Azure PowerShell script is available that does the following: |
| 26 | + |
| 27 | +* Creates a new Standard_v2 or WAF_v2 gateway in a virtual network subnet that you specify. |
| 28 | +* Seamlessly copies the configuration associated with the v1 Standard or WAF gateway to the newly created Standard_V2 or WAF_V2 gateway. |
| 29 | + |
| 30 | +### Caveats\Limitations |
| 31 | + |
| 32 | +* The new v2 gateway has new public and private IP addresses. It isn't possible to move the IP addresses associated with the existing v1 gateway seamlessly to v2. However, you can allocate an existing (unallocated) public or private IP address to the new v2 gateway. |
| 33 | +* You must provide an IP address space for another subnet within your virtual network where your v1 gateway is located. The script can't create the v2 gateway in any existing subnets that already have a v1 gateway. However, if the existing subnet already has a v2 gateway, that may still work provided there's enough IP address space. |
| 34 | +* To migrate an SSL configuration, you must specify all the SSL certs used in your v1 gateway. |
| 35 | +* If you have FIPS mode enabled for your V1 gateway, it won’t be migrated to your new v2 gateway. FIPS mode isn't supported in v2. |
| 36 | +* v2 doesn't support IPv6, so IPv6 enabled v1 gateways aren't migrated. If you run the script, it may not complete. |
| 37 | +* If the v1 gateway has only a private IP address, the script creates a public IP address and a private IP address for the new v2 gateway. v2 gateways currently don't support only private IP addresses. |
| 38 | + |
| 39 | +## Download the script |
| 40 | + |
| 41 | +Download the migration script from the [PowerShell Gallery](https://www.powershellgallery.com/packages/AzureAppGWMigration). |
| 42 | + |
| 43 | +## Use the script |
| 44 | + |
| 45 | +There are two options for you depending on your local PowerShell environment setup and preferences: |
| 46 | + |
| 47 | +* If you don’t have the Azure Az modules installed, or don’t mind uninstalling the Azure Az modules, the best option is to use the `Install-Script` option to run the script. |
| 48 | +* If you need to keep the Azure Az modules, your best bet is to download the script and run it directly. |
| 49 | + |
| 50 | +To determine if you have the Azure Az modules installed, run `Get-InstalledModule -Name az`. If you don't see any installed Az modules, then you can use the `Install-Script` method. |
| 51 | + |
| 52 | +### Install using the Install-Script method |
| 53 | + |
| 54 | +To use this option, you must not have the Azure Az modules installed on your computer. If they're installed, the following command displays an error. You can either uninstall the Azure Az modules, or use the other option to download the script manually and run it. |
| 55 | + |
| 56 | +Run the script with the following command: |
| 57 | + |
| 58 | +`Install-Script -Name AzureAppGWMigration` |
| 59 | + |
| 60 | +This command also installs the required Az modules. |
| 61 | + |
| 62 | +### Install using the script directly |
| 63 | + |
| 64 | +If you do have some Azure Az modules installed and can't uninstall them (or don't want to uninstall them), you can manually download the script using the **Manual Download** tab in the script download link. The script is downloaded as a raw nupkg file. To install the script from this nupkg file, see [Manual Package Download](https://docs.microsoft.com/powershell/gallery/how-to/working-with-packages/manual-download). |
| 65 | + |
| 66 | +To run the script: |
| 67 | + |
| 68 | +1. Use `Connect-AzAccount` to connect to Azure. |
| 69 | + |
| 70 | +1. Use `Import-Module Az` to import the Az modules. |
| 71 | + |
| 72 | +1. Run `Get-Help AzureAppGWMigration.ps1` to examine the required parameters: |
| 73 | + |
| 74 | + `AzureAppGwMigration.ps1 |
| 75 | + -resourceId <v1 application gateway Resource ID> |
| 76 | + -subnetAddressRange <subnet space you want to use> |
| 77 | + -appgwName <string to use to append> |
| 78 | + -sslCertificates <comma-separated SSLCert objects as above> |
| 79 | + -trustedRootCertificates <comma-separated Trusted Root Cert objects as above> |
| 80 | + -privateIpAddress <private IP string> |
| 81 | + -publicIpResourceName <public IP name string> |
| 82 | + -validateMigration -enableAutoScale` |
| 83 | + |
| 84 | + Parameters for the script: |
| 85 | + * **resourceId: [String]: Required** - This is the Azure Resource ID for your existing Standard v1 or WAF v1 gateway. To find this string value, navigate to the Azure portal, select your application gateway or WAF resource, and click the **Properties** link for the gateway. The Resource ID is located on that page. |
| 86 | + |
| 87 | + You can also run the following Azure PowerShell commands to get the Resource ID: |
| 88 | + |
| 89 | + ```azurepowershell |
| 90 | + $appgw = Get-AzApplicationGateway -Name <v1 gateway name> -ResourceGroupName <resource group Name> |
| 91 | + $appgw.Id |
| 92 | + ``` |
| 93 | +
|
| 94 | + * **subnetAddressRange: [String]: Required** - This is the IP address space that you have allocated (or want to allocate) for a new subnet that contains your new v2 gateway. This must be specified in the CIDR notation. For example: 10.0.0.0/24. You do not need to create this subnet in advance. The script creates it for you if it doesn't exist. |
| 95 | + * **appgwName: [String]: Optional**. This is a string you specify to use as the name for the new Standard_v2 or WAF_v2 gateway. If this parameter isn't supplied, the name of your existing v1 gateway will be used with the suffix *_v2* appended. |
| 96 | + * **sslCertificates: [PSApplicationGatewaySslCertificate]: Optional**. A comma-separated list of PSApplicationGatewaySslCertificate objects that you create to represent the SSL certs from your v1 gateway must be uploaded to the new v2 gateway. For each of your SSL certs configured for your Standard v1 or WAF v1 gateway, you can create a new PSApplicationGatewaySslCertificate object via the `New-AzApplicationGatewaySslCertificate` command shown here. You need the path to your SSL Cert file and the password. |
| 97 | +
|
| 98 | + This parameter is only optional if you don’t have HTTPS listeners configured for your v1 gateway or WAF. If you have at least one HTTPS listener setup, you must specify this parameter. |
| 99 | +
|
| 100 | + ```azurepowershell |
| 101 | + $password = ConvertTo-SecureString <cert-password> -AsPlainText -Force |
| 102 | + $mySslCert1 = New-AzApplicationGatewaySslCertificate -Name "Cert01" ` |
| 103 | + -CertificateFile <Cert-File-Path-1> ` |
| 104 | + -Password $password |
| 105 | + $mySslCert2 = New-AzApplicationGatewaySslCertificate -Name "Cert02" ` |
| 106 | + -CertificateFile <Cert-File-Path-2> ` |
| 107 | + -Password $password |
| 108 | + ``` |
| 109 | +
|
| 110 | + You can pass in `$mySslCert1, $mySslCert2` (comma-separated) in the previous example as values for this parameter in the script. |
| 111 | + * **trustedRootCertificates: [PSApplicationGatewayTrustedRootCertificate]: Optional**. A comma-separated list of PSApplicationGatewayTrustedRootCertificate objects that you create to represent the [Trusted Root certificates](ssl-overview.md) for authentication of your backend instances from your v2 gateway. |
| 112 | +
|
| 113 | + To create a list of PSApplicationGatewayTrustedRootCertificate objects, see [New-AzApplicationGatewayTrustedRootCertificate](https://docs.microsoft.com/powershell/module/Az.Network/New-AzApplicationGatewayTrustedRootCertificate?view=azps-2.1.0&viewFallbackFrom=azps-2.0.0). |
| 114 | + * **privateIpAddress: [String]: Optional**. A specific private IP address that you want to associate to your new v2 gateway. This must be from the same VNet that you allocate for your new v2 gateway. If this isn't specified, the script allocates a private IP address for your v2 gateway. |
| 115 | + * **publicIpResourceId: [String]: Optional**. The resourceId of a public IP address resource in your subscription that you want to allocate to the new v2 gateway. If this is not specified, the script allocates a new public IP in the same resource group. The name is the v2 gateway’s name with *-IP* appended. |
| 116 | + * **validateMigration: [switch]: Optional**. Use this parameter if you want the script to do some basic configuration comparison validations after the v2 gateway creation and the configuration copy. By default, no validation is done. |
| 117 | + * **enableAutoScale: [switch]: Optional**. Use this parameter if you want the script to enable AutoScaling on the new v2 gateway after it is created. By default, AutoScaling is disabled. You can always manually enable it later on the newly created v2 gateway. |
| 118 | +
|
| 119 | +1. Run the script using the appropriate parameters. |
| 120 | +
|
| 121 | + **Example** |
| 122 | +
|
| 123 | + ```azurepowershell |
| 124 | + AzureAppGWMigration.ps1 ` |
| 125 | + -resourceId /subscriptions/8b1d0fea-8d57-4975-adfb-308f1f4d12aa/resourceGroups/MyResourceGroup/providers/Microsoft.Network/applicationGateways/myv1appgateway ` |
| 126 | + -subnetAddressRange 10.0.0.0/24 ` |
| 127 | + -appgwname "MynewV2gw" ` |
| 128 | + -sslCertificates $Certs ` |
| 129 | + -trustedRootCertificates $trustedCert ` |
| 130 | + -privateIpAddress "10.0.0.1" ` |
| 131 | + -publicIpResourceName "MyPublicIP" ` |
| 132 | + -validateMigration -enableAutoScale |
| 133 | + ``` |
| 134 | + |
| 135 | +## Migrate client traffic |
| 136 | + |
| 137 | +First, double check that the script successfully created a new v2 gateway with the exact configuration migrated over from your v1 gateway. You can verify this from the Azure portal. |
| 138 | + |
| 139 | +Also, send a small amount of traffic through the v2 gateway as a manual test. |
| 140 | + |
| 141 | +Here are a few scenarios where your current application gateway (Standard) may receive client traffic, and our recommendations for each one: |
| 142 | + |
| 143 | +* **A custom DNS zone (for example, contoso.com) that points to the frontend IP address (using an A record) associated with your Standard v1 or WAF v1 gateway**. |
| 144 | + |
| 145 | + You can update your DNS record to point to the frontend IP or DNS label associated with your Standard_v2 application gateway. Depending on the TTL configured on your DNS record, it may take a while for all your client traffic to migrate to your new v2 gateway. |
| 146 | +* **A custom DNS zone (for example, contoso.com) that points to the DNS label (for example: *myappgw.eastus.cloudapp.azure.com* using a CNAME record) associated with your v1 gateway**. |
| 147 | + |
| 148 | + You have two choices: |
| 149 | + |
| 150 | + * If you use public IP addresses on your application gateway, you can do a controlled, granular migration using a Traffic Manager profile to incrementally route traffic (weighted traffic routing method) to the new v2 gateway. |
| 151 | + |
| 152 | + You can do this by adding the DNS labels of both the v1 and v2 application gateways to the Traffic Manager profile, and CNAMEing your custom DNS record (for example, www.contoso.com) to the Traffic Manager domain (for example, contoso.trafficmanager.net). |
| 153 | + * Or, you can update your custom domain DNS record to point to the DNS label of the new v2 application gateway. Depending on the TTL configured on your DNS record, it may take a while for all your client traffic to migrate to your new v2 gateway. |
| 154 | +* **Your clients connect to the frontend IP address of your application gateway**. |
| 155 | + |
| 156 | + Update your clients to use the IP address(es) associated with the newly created v2 application gateway. We recommend that you don't use IP addresses directly. Consider using the DNS name label (for example, yourgateway.eastus.cloudapp.azure.com) associated with your application gateway that you can CNAME to your own custom DNS zone (for example, contoso.com). |
| 157 | + |
| 158 | +## Common questions |
| 159 | + |
| 160 | +### Are there any limitations with the Azure PowerShell script to migrate the configuration from v1 to v2? |
| 161 | + |
| 162 | +Yes. See [Caveats/Limitations](#caveatslimitations). |
| 163 | + |
| 164 | +### Is this article and the Azure PowerShell script applicable for Application Gateway WAF product as well? |
| 165 | + |
| 166 | +Yes. |
| 167 | + |
| 168 | +### Does the Azure PowerShell script also switch over the traffic from my v1 gateway to the newly created v2 gateway? |
| 169 | + |
| 170 | +No. The Azure PowerShell script only migrates the configuration. Actual traffic migration is your responsibility and in your control. |
| 171 | + |
| 172 | +### Is the new v2 gateway created by the Azure PowerShell script sized appropriately to handle all of the traffic that is currently served by my v1 gateway? |
| 173 | + |
| 174 | +The Azure PowerShell script creates a new v2 gateway with an appropriate size to handle the traffic on your existing V1 gateway. Autoscaling is disabled by default, but you can enable AutoScaling when you run the script. |
| 175 | + |
| 176 | +### I ran into some issues with using this script. How can I get help? |
| 177 | + |
| 178 | +You can send an email to [email protected], open a support case with Azure Support, or do both. |
| 179 | + |
| 180 | +## Next steps |
| 181 | + |
| 182 | +[Learn about Application Gateway v2](application-gateway-autoscaling-zone-redundant.md) |
0 commit comments