ARM 模板部署 what-if 操作(预览版)ARM template deployment what-if operation (Preview)

在部署 Azure 资源管理器 (ARM) 模板之前,可以预览将要进行的更改。Before deploying an Azure Resource Manager (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 操作目前以预览版提供。The what-if operation is currently in preview. 在预览版中,结果有时可能会显示资源将发生更改,但实际上并不会发生更改。As a preview release, the results may sometimes show that a resource will change when actually no change will happen. 我们正在努力减少这些问题,但需要大家的帮助。We're working to reduce these issues, but we need your help. 请在 https://aka.ms/whatifissues 上报告这些问题。Please report these issues at https://aka.ms/whatifissues.

可将 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 and subscription 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.

但在安装所需模块之前,请确保安装了 PowerShell Core(6.x 或 7.x)。But, before installing the required module, make sure you have PowerShell Core (6.x or 7.x). 如果安装了 PowerShell 5.x 或更早版本,请更新 PowerShell 版本If you have PowerShell 5.x or earlier, update your version of PowerShell. 无法在 PowerShell 5.x 或更早版本上安装所需模块。You can't install the required module on PowerShell 5.x or earlier.

安装最新版本Install latest version

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

Install-Module -Name Az -Force

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

卸载 alpha 版本Uninstall alpha version

如果以前安装了 alpha 版本的 what-if 模块,请卸载该模块。If you previously installed an alpha version of the what-if module, uninstall that module. alpha 版本仅适用于注册了抢鲜预览版的用户。The alpha version was only available to users who signed up for an early preview. 如果未安装该预览版,则可跳过此部分。If you didn't install that preview, you can skip this section.

  1. 以管理员身份运行 PowerShellRun PowerShell as administrator

  2. 检查安装的 Az.Resources 模块版本。Check your installed versions of the Az.Resources module.

    Get-InstalledModule -Name Az.Resources -AllVersions | select Name,Version
    
  3. 如果已安装版本的版本号格式为 2.x.x-alpha,请卸载该版本。If you have an installed version with a version number in the format 2.x.x-alpha, uninstall that version.

    Uninstall-Module Az.Resources -RequiredVersion 2.0.1-alpha5 -AllowPrerelease
    
  4. 取消注册用于安装预览版的 what-if 存储库。Unregister the what-if repository that you used to install the preview.

    Unregister-PSRepository -Name WhatIfRepository
    

现在可以使用 what-if 了。You're ready to use what-if.

安装 Azure CLI 模块Install Azure CLI module

若要在 Azure CLI 中使用 what-if,则必须安装 Azure CLI 2.5.0 或更高版本。To use what-if in Azure CLI, you must have Azure CLI 2.5.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 命令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

若要在部署模板前预览更改,请使用 az deployment group what-ifaz deployment sub what-ifTo preview changes before deploying a template, use az deployment group what-if or az deployment sub what-if.

  • 对于资源组部署,请使用 az deployment group what-ifaz deployment group what-if for resource group deployments
  • 对于订阅级别部署,请使用 az deployment sub what-ifaz deployment sub what-if for subscription level deployments

可以使用 --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. 将此开关添加到 az deployment group createaz deployment sub createAdd this switch to az deployment group create or az deployment sub create.

  • 对于资源组部署,请使用 az deployment group create --confirm-with-what-if-caz deployment group create --confirm-with-what-if or -c for resource group deployments
  • 对于订阅级别的部署,请使用 az deployment sub create --confirm-with-what-if-caz deployment sub create --confirm-with-what-if or -c for subscription level deployments

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

  • 对于资源组部署,请使用 az deployment group what-if --no-pretty-printaz deployment group what-if --no-pretty-print for resource group deployments
  • 对于订阅级别部署,请使用 az deployment sub what-if --no-pretty-printaz deployment sub what-if --no-pretty-print for subscription level 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.

New-AzResourceGroup `
  -Name ExampleGroup `
  -Location centralus
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 actually 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, acknowledge 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:        "centralus"
      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.

后续步骤Next steps