ARM 模板部署 What-if 操作ARM template deployment what-if operation

在部署 Azure 资源管理器模板(ARM 模板)之前,可以预览将要进行的更改。Before deploying an Azure Resource Manager template (ARM template), you can preview the changes that will happen. Azure 资源管理器提供 what-if(假设)操作,让你在部署模板时了解资源发生的更改。Azure Resource Manager provides the what-if operation to let you see how resources will change if you deploy the template. what-if 操作不会对现有资源进行任何更改,The what-if operation doesn't make any changes to existing resources. 而是预测在部署指定的模板时发生的更改。Instead, it predicts the changes if the specified template is deployed.

可将 what-if 操作与 Azure PowerShell、Azure CLI 或 REST API 操作配合使用。You can use the what-if operation with Azure PowerShell, Azure CLI, or REST API operations. 资源组、订阅、管理组合租户级部署支持 What-if。What-if is supported for resource group, subscription, management group, and tenant level deployments.

安装 Azure PowerShell 模块Install Azure PowerShell module

若要在 PowerShell 中使用 what-if,则必须安装 Az 模块 4.2 或更高版本。To use what-if in PowerShell, you must have version 4.2 or later of the Az module.

若要安装该模块,请使用:To install the module, use:

Install-Module -Name Az -Force

若要详细了解如何安装模块,请参阅安装 Azure PowerShellFor more information about installing modules, see Install Azure PowerShell.

安装 Azure CLI 模块Install Azure CLI module

若要在 Azure CLI 中使用 what-if,则必须安装 Azure CLI 2.14.0 或更高版本。To use what-if in Azure CLI, you must have Azure CLI 2.14.0 or later. 如果需要,请安装 Azure CLI 的最新版本If needed, install the latest version of Azure CLI.

查看结果See results

在 PowerShell 或 Azure CLI 中使用 what-if 时,输出包含进行了颜色编码的结果,方便你查看不同类型的更改。When you use what-if in PowerShell or Azure CLI, the output includes color-coded results that help you see the different types of changes.

资源管理器模板部署 what-if 操作 fullresourcepayloads 和更改类型

文本输出如下:The text output is:

Resource and property changes are indicated with these symbols:
  - Delete
  + Create
  ~ Modify

The deployment will update the following scope:

Scope: /subscriptions/./resourceGroups/ExampleGroup

  ~ Microsoft.Network/virtualNetworks/vnet-001 [2018-10-01]
    - tags.Owner: "Team A"
    ~ properties.addressSpace.addressPrefixes: [
      - 0: "10.0.0.0/16"
      + 0: "10.0.0.0/15"
      ]
    ~ properties.subnets: [
      - 0:

          name:                     "subnet001"
          properties.addressPrefix: "10.0.0.0/24"

      ]

Resource changes: 1 to modify.

备注

What-if 操作无法解析引用函数The what-if operation can't resolve the reference function. 每次将属性设置为包含引用函数的模板表达式时,What-if 都会报告属性将改变。Every time you set a property to a template expression that includes the reference function, what-if reports the property will change. 发生此行为的原因是,What-if 将属性的当前值(如布尔值 truefalse)与未解析的模板表达式进行比较。This behavior happens because what-if compares the current value of the property (such as true or false for a boolean value) with the unresolved template expression. 很明显,这些值不匹配。Obviously, these values will not match. 部署模板时,只有在模板表达式解析为其他值时,属性才会更改。When you deploy the template, the property will only change when the template expression resolves to a different value.

what-if 命令What-if commands

Azure PowerShellAzure PowerShell

若要在部署模板前预览更改,请使用 New-AzResourceGroupDeploymentNew-AzSubscriptionDeploymentTo preview changes before deploying a template, use New-AzResourceGroupDeployment or New-AzSubscriptionDeployment. -Whatif 开关参数添加到部署命令。Add the -Whatif switch parameter to the deployment command.

  • 对于资源组部署,请使用 New-AzResourceGroupDeployment -WhatifNew-AzResourceGroupDeployment -Whatif for resource group deployments
  • 对于订阅级别的部署,请使用 New-AzSubscriptionDeployment -WhatifNew-AzDeployment -WhatifNew-AzSubscriptionDeployment -Whatif and New-AzDeployment -Whatif for subscription level deployments

可使用 -Confirm 开关参数来预览所做的更改,让系统显示是否继续部署的提示。You can use the -Confirm switch parameter to preview the changes and get prompted to continue with the deployment.

  • 对于资源组部署,请使用 New-AzResourceGroupDeployment -ConfirmNew-AzResourceGroupDeployment -Confirm for resource group deployments
  • 对于订阅级别的部署,请使用 New-AzSubscriptionDeployment -ConfirmNew-AzDeployment -ConfirmNew-AzSubscriptionDeployment -Confirm and New-AzDeployment -Confirm for subscription level deployments

上述命令返回适用于手动检查的文本摘要。The preceding commands return a text summary that you can manually inspect. 若要获取可通过编程方式检查更改的对象,请使用 Get-AzResourceGroupDeploymentWhatIfResultGet-AzSubscriptionDeploymentWhatIfResultTo get an object that you can programmatically inspect for changes, use Get-AzResourceGroupDeploymentWhatIfResult or Get-AzSubscriptionDeploymentWhatIfResult.

  • 对于资源组部署,请使用 $results = Get-AzResourceGroupDeploymentWhatIfResult$results = Get-AzResourceGroupDeploymentWhatIfResult for resource group deployments
  • 对于订阅级别的部署,请使用 $results = Get-AzSubscriptionDeploymentWhatIfResult$results = Get-AzDeploymentWhatIfResult$results = Get-AzSubscriptionDeploymentWhatIfResult or $results = Get-AzDeploymentWhatIfResult for subscription level deployments

Azure CLIAzure CLI

若要在部署模板前预览更改,请使用:To preview changes before deploying a template, use:

可以使用 --confirm-with-what-if 开关(或其缩写形式 -c)预览更改,并让系统显示是否继续部署的提示。You can use the --confirm-with-what-if switch (or its short form -c) to preview the changes and get prompted to continue with the deployment. 将此开关添加到:Add this switch to:

例如,对于资源组部署,请使用 az deployment group create --confirm-with-what-if-cFor example, use az deployment group create --confirm-with-what-if or -c for resource group deployments.

上述命令返回适用于手动检查的文本摘要。The preceding commands return a text summary that you can manually inspect. 若要获取可通过编程方式检查更改的 JSON 对象,请使用 --no-pretty-print 开关。To get a JSON object that you can programmatically inspect for changes, use the --no-pretty-print switch. 例如,对于资源组部署,请使用 az deployment group what-if --no-pretty-printFor example, use az deployment group what-if --no-pretty-print for resource group deployments.

若要返回没有颜色的结果,请打开 Azure CLI 配置文件。If you want to return the results without colors, open your Azure CLI configuration file. 将“no_color”设置为“yes”。Set no_color to yes.

Azure REST APIAzure REST API

对于 REST API,请使用:For REST API, use:

更改类型Change types

what-if 操作列出六种不同的更改类型:The what-if operation lists six different types of changes:

  • 创建:资源当前不存在,但已在模板中定义。Create: The resource doesn't currently exist but is defined in the template. 将创建该资源。The resource will be created.

  • 删除:仅当为部署使用 完整模式时,此更改类型才适用。Delete: This change type only applies when using complete mode for deployment. 资源存在,但未在模板中定义。The resource exists, but isn't defined in the template. 使用完整模式时,将删除该资源。With complete mode, the resource will be deleted. 此更改类型仅包括支持完整模式删除的资源。Only resources that support complete mode deletion are included in this change type.

  • 忽略:资源存在,但未在模板中定义。Ignore: The resource exists, but isn't defined in the template. 不会部署或修改资源。The resource won't be deployed or modified.

  • 无更改:资源存在,且已在模板中定义。NoChange: The resource exists, and is defined in the template. 将重新部署资源,但资源的属性不会更改。The resource will be redeployed, but the properties of the resource won't change. ResultFormat 设置为 FullResourcePayloads(默认值)时,将返回此更改类型。This change type is returned when ResultFormat is set to FullResourcePayloads, which is the default value.

  • 修改:资源存在,且已在模板中定义。Modify: The resource exists, and is defined in the template. 将重新部署资源,且资源的属性会更改。The resource will be redeployed, and the properties of the resource will change. ResultFormat 设置为 FullResourcePayloads(默认值)时,将返回此更改类型。This change type is returned when ResultFormat is set to FullResourcePayloads, which is the default value.

  • 部署:资源存在,且已在模板中定义。Deploy: The resource exists, and is defined in the template. 将重新部署资源。The resource will be redeployed. 资源的属性可能会更改,也可能不会更改。The properties of the resource may or may not change. 当没有足够的信息来确定是否有任何属性发生更改时,操作将返回此更改类型。The operation returns this change type when it doesn't have enough information to determine if any properties will change. 仅当 ResultFormat 设置为 ResourceIdOnly 时,才会看到此状况。You only see this condition when ResultFormat is set to ResourceIdOnly.

结果格式Result format

控制返回的有关预测更改的详细信息级别。You control the level of detail that is returned about the predicted changes. 可以使用两个选项:You have two options:

  • FullResourcePayloads - 返回将会更改的资源的列表,以及将会更改的属性的相关详细信息。FullResourcePayloads - returns a list of resources that will change and details about the properties that will change
  • ResourceIdOnly - 返回将会更改的资源列表ResourceIdOnly - returns a list of resources that will change

默认值为 FullResourcePayloads。The default value is FullResourcePayloads.

对于 PowerShell 部署命令,请使用 -WhatIfResultFormat 参数。For PowerShell deployment commands, use the -WhatIfResultFormat parameter. 在编程对象命令中,使用 ResultFormat 参数。In the programmatic object commands, use the ResultFormat parameter.

对于 Azure CLI,请使用 --result-format 参数。For Azure CLI, use the --result-format parameter.

以下结果显示了两种不同的输出格式:The following results show the two different output formats:

  • 完整资源有效负载Full resource payloads

    Resource and property changes are indicated with these symbols:
      - Delete
      + Create
      ~ Modify
    
    The deployment will update the following scope:
    
    Scope: /subscriptions/./resourceGroups/ExampleGroup
    
      ~ Microsoft.Network/virtualNetworks/vnet-001 [2018-10-01]
        - tags.Owner: "Team A"
        ~ properties.addressSpace.addressPrefixes: [
          - 0: "10.0.0.0/16"
          + 0: "10.0.0.0/15"
          ]
        ~ properties.subnets: [
          - 0:
    
            name:                     "subnet001"
            properties.addressPrefix: "10.0.0.0/24"
    
          ]
    
    Resource changes: 1 to modify.
    
  • 仅限资源 IDResource ID only

    Resource and property changes are indicated with this symbol:
      ! Deploy
    
    The deployment will update the following scope:
    
    Scope: /subscriptions/./resourceGroups/ExampleGroup
    
      ! Microsoft.Network/virtualNetworks/vnet-001
    
    Resource changes: 1 to deploy.
    

运行 what-if 操作Run what-if operation

设置环境Set up environment

为了了解 what-if 的工作原理,让我们运行一些测试。To see how what-if works, let's runs some tests. 首先,部署一个用于创建虚拟网络的模板First, deploy a template that creates a virtual network. 将使用此虚拟网络来测试 what-if 如何报告更改。You'll use this virtual network to test how changes are reported by what-if.

备注

当我们使用以 https://raw.githubusercontent.com/ 开头的指定模板文件 URI 部署资源时,控制台有时会生成错误,如 Unable to download deployment contentWhen we deploy resource with specified template file URI that starts with https://raw.githubusercontent.com/, the console will run in error like Unable to download deployment content sometime.

可以执行以下操作来解决相应问题。We can follow the actions below to resolve the corresponding issue.

  1. 复制模板 URI,通过更改前缀、中缀和模板文件名来转换 URI。Copy the template URI, convert the URI by changing the prefix, infix, and tempalte file name. 例如,源 URI 是 https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/101-cosmosdb-sql-autoscale/azuredeploy.jsonFor exsample: the origin URI is https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/101-cosmosdb-sql-autoscale/azuredeploy.json

    类别Category 原始值Original value 转换后的值Converted value 操作Action
    前缀Prefix https://raw.githubusercontent.com https://github.com 更新Update
    中辍Infix blob mastermain 之前添加分支名称Add before master or main branch name
    模板文件名Template file name azuredeploy.jsonazuredeploy.json 你的下载模板文件名your download tempalte file name updateupdate

    修改后,转换后的 URI 看起来将类似于 https://github.com/Azure/azure-quickstart-templates/blob/master/101-cosmosdb-sql-autoscale/azuredeploy.jsonAfter modified, the converted URI will show like https://github.com/Azure/azure-quickstart-templates/blob/master/101-cosmosdb-sql-autoscale/azuredeploy.json.

    请注意,某些模板 URI 已移至 https://github.com/Azure/azure-quickstart-template/quickstarts/{Microsoft_Resource_Provider_Name}/ ,你可以按照相应的路径规定来更新原始 URI。Please be kindly noticed that some templates URI have been moved to https://github.com/Azure/azure-quickstart-template/quickstarts/{Microsoft_Resource_Provider_Name}/, you can follow the corresponding path regulation to update the original URI.

  2. 复制转换后的 URI,并在 Internet 浏览器中手动下载特定的模板内容。Copy the converted URI and download the specific template content in Internet browsers manully.

  3. 修改从 GitHub 存储库下载或引用的模板,以适应 Azure 中国云环境。Modify the templates you downloaded or referenced from the GitHub Repo in order to fit in the Azure China Cloud Environment. 例如,替换某些终结点(将“blob.core.windows.net”替换为“blob.core.chinacloudapi.cn”,将“cloudapp.azure.com”替换为“chinacloudapp.cn”);必要时更改某些不受支持的位置、VM 映像、VM 大小、SKU 以及资源提供程序的 API 版本。For example, replace some endpoints -- "blob.core.windows.net" by "blob.core.chinacloudapi.cn", "cloudapp.azure.com" by "chinacloudapp.cn"; change some unsupported Location,VM images, VM sizes, SKU, and resource-provider's API Version when necessary.

  4. TemplateUri 的参数替换为 TemplateFile,然后用下载的实际文件名更新指定的 URI,并再次运行该脚本。Replace the parameter of TemplateUri with TemplateFile, then update the specified URI with the downloaded actual file name and run the script again.

    语言类别Language category 参考链接Reference link 操作Action
    PowerShellPowerShell New-AzResourceGroupDeployment -TemplateUri 替换为 -TemplateFileReplace -TemplateUri with -TemplateFile
    如有必要,请按照前面的步骤下载 --TemplateParameterUri 内容并在 cmdlet 中替换为 --TemplateParameterFileFollow the previous steps to download the --TemplateParameterUri content and repalce with --TemplateParameterFile in cmdlet when necessary.
    Azure CLIAzure CLI az deployment group create --template-uri 替换为 --template-file Replace --template-uri with --template-file
New-AzResourceGroup `
  -Name ExampleGroup `
  -Location chinaeast
New-AzResourceGroupDeployment `
  -ResourceGroupName ExampleGroup `
  -TemplateUri "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/azure-resource-manager/what-if/what-if-before.json"

测试修改Test modification

部署完成后,即可测试 what-if 操作。After the deployment completes, you're ready to test the what-if operation. 这一次,将部署一个用于更改虚拟网络的模板This time you deploy a template that changes the virtual network. 该模板中缺少一个原始标记,已删除了一个子网,并且已更改了地址前缀。It's missing one the original tags, a subnet has been removed, and the address prefix has changed.

New-AzResourceGroupDeployment `
  -Whatif `
  -ResourceGroupName ExampleGroup `
  -TemplateUri "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/azure-resource-manager/what-if/what-if-after.json"

what-if 输出类似于:The what-if output appears similar to:

资源管理器模板部署 what-if 操作输出

文本输出如下:The text output is:

Resource and property changes are indicated with these symbols:
  - Delete
  + Create
  ~ Modify

The deployment will update the following scope:

Scope: /subscriptions/./resourceGroups/ExampleGroup

  ~ Microsoft.Network/virtualNetworks/vnet-001 [2018-10-01]
    - tags.Owner: "Team A"
    ~ properties.addressSpace.addressPrefixes: [
      - 0: "10.0.0.0/16"
      + 0: "10.0.0.0/15"
      ]
    ~ properties.subnets: [
      - 0:

        name:                     "subnet001"
        properties.addressPrefix: "10.0.0.0/24"

      ]

Resource changes: 1 to modify.

请注意,输出顶部的颜色用于指示更改类型。Notice at the top of the output that colors are defined to indicate the type of changes.

输出的底部显示了“已删除所有者”标记。At the bottom of the output, it shows the tag Owner was deleted. 地址前缀已从 10.0.0.0/16 更改为 10.0.0.0/15。The address prefix changed from 10.0.0.0/16 to 10.0.0.0/15. 已删除名为 subnet001 的子网。The subnet named subnet001 was deleted. 请记住,这些更改并未部署。Remember these changes weren't deployed. 如果部署该模板,则可预览会发生的更改。You see a preview of the changes that will happen if you deploy the template.

列出为已删除的某些属性实际上不会更改。Some of the properties that are listed as deleted won't actually change. 当属性不在模板中时,它们可能被错误地报告为已删除,但在部署过程中会自动设置为默认值。Properties can be incorrectly reported as deleted when they aren't in the template, but are automatically set during deployment as default values. 此结果在 what-if 响应中被视为“干扰信息”。This result is considered "noise" in the what-if response. 最终部署的资源将具有为属性设置的值。The final deployed resource will have the values set for the properties. 当 what-if 操作成熟时,将从结果中筛选出这些属性。As the what-if operation matures, these properties will be filtered out of the result.

以编程方式评估 what-if 结果Programmatically evaluate what-if results

现在,让我们将命令设置为变量,以编程方式评估 what-if 结果。Now, let's programmatically evaluate the what-if results by setting the command to a variable.

$results = Get-AzResourceGroupDeploymentWhatIfResult `
  -ResourceGroupName ExampleGroup `
  -TemplateUri "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/azure-resource-manager/what-if/what-if-after.json"

可以看到每项更改的摘要。You can see a summary of each change.

foreach ($change in $results.Changes)
{
  $change.Delta
}

确认删除Confirm deletion

what-if 操作支持使用部署模式The what-if operation supports using deployment mode. 设置为完整模式时,将删除不在模板中的资源。When set to complete mode, resources not in the template are deleted. 以下示例部署一个处于完整模式的未定义任何资源的模板The following example deploys a template that has no resources defined in complete mode.

若要在部署模板之前预览所做的更改,请在部署命令中使用 confirm 开关参数。To preview changes before deploying a template, use the confirm switch parameter with the deployment command. 如果更改符合预期,请确认你想要完成此部署。If the changes are as you expected, respond that you want the deployment to complete.

New-AzResourceGroupDeployment `
  -ResourceGroupName ExampleGroup `
  -Mode Complete `
  -Confirm `
  -TemplateUri "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/empty-template/azuredeploy.json"

由于该模板中未定义任何资源,且部署模式设置为完成,因此会删除虚拟网络。Because no resources are defined in the template and the deployment mode is set to complete, the virtual network will be deleted.

资源管理器模板部署 what-if 操作输出 - 完整部署模式

文本输出如下:The text output is:

Resource and property changes are indicated with this symbol:
  - Delete

The deployment will update the following scope:

Scope: /subscriptions/./resourceGroups/ExampleGroup

  - Microsoft.Network/virtualNetworks/vnet-001

      id:
"/subscriptions/./resourceGroups/ExampleGroup/providers/Microsoft.Network/virtualNet
works/vnet-001"
      location:        "chinaeast"
      name:            "vnet-001"
      tags.CostCenter: "12345"
      tags.Owner:      "Team A"
      type:            "Microsoft.Network/virtualNetworks"

Resource changes: 1 to delete.

Are you sure you want to execute the deployment?
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"):

你会看到预期的更改,并且可以确认你想要运行此部署。You see the expected changes and can confirm that you want the deployment to run.

SDKSDKs

可以通过 Azure SDK 使用 What-if 操作。You can use the what-if operation through the Azure SDKs.

后续步骤Next steps