Partilhar via

Operação hipotética de implantação de modelo ARM

Antes de implantar um modelo do Azure Resource Manager (modelo ARM), você pode visualizar as alterações que acontecerão. O Azure Resource Manager fornece a operação hipotética para permitir que você veja como os recursos serão alterados se você implantar o modelo. A operação hipotética não faz alterações nos recursos existentes. Em vez disso, prevê as alterações se o modelo especificado for implementado.

Você pode usar a operação hipotética com operações do Azure PowerShell, CLI do Azure ou API REST. O What-if é suportado para implantações a nível de grupo de recursos, assinatura, grupo de gestão e inquilino.

Recursos de formação

Para saber mais sobre hipóteses e para obter orientação prática, consulte Visualizar alterações de implantação do Azure usando hipóteses.

Pré-requisitos

Permissões necessárias

Para implantar um arquivo Bicep ou um modelo ARM (Azure Resource Manager), você precisa de acesso de gravação nos recursos que está implantando e acesso a todas as operações no Microsoft.Resources/deployments tipo de recurso. Por exemplo, para implantar uma máquina virtual, é necessário ter permissões Microsoft.Compute/virtualMachines/write e Microsoft.Resources/deployments/*. A operação "what-if" tem os mesmos requisitos de permissão.

A CLI do Azure versão 2.76.0 ou posterior e o Azure PowerShell versão 13.4.0 ou posterior introduzem a opção ValidationLevel para determinar quão completamente o ARM valida o modelo Bicep durante esse processo. Para obter mais informações, consulte Comandos hipotéticos

Para obter uma lista de funções e permissões, veja Funções incorporadas do Azure.

Limites hipotéticos

What-if expande os modelos aninhados até que esses limites sejam atingidos.

  • 500 modelos aninhados.
  • 800 grupos de recursos em uma implantação entre grupos de recursos.
  • Foram necessários 5 minutos para expandir os modelos aninhados.

Quando um dos limites é atingido, o tipo de alteração dos recursos restantes é definido como Ignorar.

Instalar o módulo do Azure PowerShell

Para usar hipóteses no PowerShell, você deve ter a versão 4.2 ou posterior do módulo Az.

Para instalar o módulo, use:

Install-Module -Name Az -Force

Para obter mais informações sobre como instalar módulos, consulte Instalar o Azure PowerShell.

Instalar o módulo CLI do Azure

Para usar hipóteses na CLI do Azure, você deve ter a CLI do Azure 2.14.0 ou posterior. Se for necessário, instale a versão mais recente da CLI do Azure.

Ver resultados

Quando você usa hipóteses no PowerShell ou na CLI do Azure, a saída inclui resultados codificados por cores que ajudam você a ver os diferentes tipos de alterações.

Captura de tela da operação hipotética de implantação de modelo do Gerenciador de Recursos com carga útil completa de recursos e tipos de alteração.

A saída do texto é:

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.

Observação

A operação hipotética não pode resolver a função de referência. Sempre que uma propriedade é atribuída a uma expressão de modelo que inclua a função de referência, os relatórios de simulação indicam que a propriedade irá alterar-se. Esse comportamento acontece porque o what-if compara o valor atual da propriedade (como true ou false para um valor booleano) com a expressão de modelo não resolvida. Obviamente, estes valores não corresponderão. Quando você implanta o modelo, a propriedade só será alterada quando a expressão do modelo for resolvida para um valor diferente.

Comandos hipotéticos

Azure PowerShell

Para visualizar as alterações antes de implantar um modelo, use New-AzResourceGroupDeployment ou New-AzSubscriptionDeployment. Adicione o parâmetro de switch -Whatif ao comando de deployment.

  • New-AzResourceGroupDeployment -Whatif Para implantações de grupos de recursos

  • New-AzSubscriptionDeployment -Whatif e New-AzDeployment -Whatif para implantações em nível de assinatura

Pode usar o parâmetro switch -Confirm para visualizar as alterações e receberá uma solicitação para continuar com a implementação.

  • New-AzResourceGroupDeployment -Confirm Para implantações de grupos de recursos
  • New-AzSubscriptionDeployment -Confirm e New-AzDeployment -Confirm para implantações em nível de assinatura

Os comandos anteriores retornam um resumo de texto que você pode inspecionar manualmente. Para obter um objeto que você possa inspecionar programaticamente se há alterações, use Get-AzResourceGroupDeploymentWhatIfResult ou Get-AzSubscriptionDeploymentWhatIfResult.

  • $results = Get-AzResourceGroupDeploymentWhatIfResult Para implantações de grupos de recursos
  • $results = Get-AzSubscriptionDeploymentWhatIfResult ou $results = Get-AzDeploymentWhatIfResult para implantações de nível de assinatura

Azure CLI (Interface de Linha de Comando da Azure)

Para visualizar as alterações antes de implantar um modelo, use:

Você pode usar o --confirm-with-what-if switch (ou sua forma abreviada -c) para visualizar as alterações e ser solicitado a continuar com a implantação. Adicione esta opção a:

Por exemplo, use az deployment group create --confirm-with-what-if ou -c para implantações de grupo de recursos.

Os comandos anteriores retornam um resumo de texto que você pode inspecionar manualmente. Para obter um objeto JSON que você pode inspecionar programaticamente se há alterações, use o --no-pretty-print switch. Por exemplo, use az deployment group what-if --no-pretty-print para implantações de grupos de recursos.

Se você quiser retornar os resultados sem cores, abra o arquivo de configuração da CLI do Azure. Defina no_color para sim.

Azure REST API

Para API REST, use:

Tipos de alterações

A operação hipotética lista sete tipos diferentes de alterações:

  • Criar: o recurso não existe atualmente, mas está definido no modelo. O recurso será criado.
  • Excluir: esse tipo de alteração só se aplica ao usar o modo completo para implantação. O recurso existe, mas não está definido no modelo. Com o modo completo, o recurso será eliminado. Apenas os recursos que suportem a eliminação do modo completo são incluídos neste tipo de alteração.
  • Ignorar: o recurso existe, mas não está definido no modelo. O recurso não será implementado ou modificado. Quando você atingir os limites para expandir modelos aninhados, encontrará esse tipo de alteração. Consulte Limites hipotéticos.
  • NoChange: O recurso existe e é definido no modelo. O recurso será novamente implementado, mas as propriedades do recurso não mudam. Esse tipo de alteração é retornado quando ResultFormat é definido como FullResourcePayloads, que é o valor padrão.
  • NoEffect: A propriedade está pronta e será ignorada pelo serviço. Por exemplo, a sku.tier propriedade é sempre definida para corresponder sku.name no Microsoft.ServiceBus namespace.
  • Modificar: o recurso existe e é definido no modelo. O recurso será reimplantado e as propriedades do recurso serão alteradas. Esse tipo de alteração é retornado quando ResultFormat é definido como FullResourcePayloads, que é o valor padrão.
  • Implantar: o recurso existe e é definido no modelo. O recurso será redistribuído. As propriedades do recurso podem ou não ser alteradas. A operação retorna esse tipo de alteração quando não tem informações suficientes para determinar se alguma propriedade será alterada. Você só vê essa condição quando ResultFormat está definido como ResourceIdOnly.

Formato dos resultados

Você controla o nível de detalhe que é retornado sobre as alterações previstas. Tem duas opções:

  • FullResourcePayloads - retorna uma lista de recursos que serão alterados e detalhes sobre as propriedades que serão alteradas
  • ResourceIdOnly - retorna uma lista de recursos que serão alterados

O valor padrão é FullResourcePayloads.

Para comandos de implantação do PowerShell, use o -WhatIfResultFormat parâmetro. Nos comandos de objeto programático, use o ResultFormat parâmetro.

Para a CLI do Azure, use o --result-format parâmetro.

Os resultados a seguir mostram os dois formatos de saída diferentes:

  • Cargas completas de recursos

    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.

  • Apenas ID de recurso

    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.

Executar operação hipotética

Configurar ambiente

Para ver como funciona o what-if, vamos executar alguns testes. Primeiro, implante um modelo que crie uma rede virtual. Você usará essa rede virtual para testar como as alterações são relatadas por hipóteses.

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"

Modificação do ensaio

Após a conclusão da implantação, você estará pronto para testar a operação hipotética. Desta vez, você implanta um modelo que altera a rede virtual. Está faltando uma das tags originais, uma sub-rede foi removida e o prefixo do endereço foi alterado.

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"

O resultado de what-if é semelhante a:

Captura de tela da saída da operação hipotética de implantação do modelo do Gerenciador de Recursos mostrando alterações.

A saída do texto é:

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.

Observe na parte superior da saída que as cores são definidas para indicar o tipo de alterações.

Na parte inferior da saída, mostra que a tag Owner foi excluída. O prefixo do endereço foi alterado de 10.0.0.0/16 para 10.0.0.0/15. A sub-rede chamada subnet001 foi excluída. Lembre-se de que essas alterações não foram implantadas. Você verá uma visualização das alterações que acontecerão se você implantar o modelo.

Algumas das propriedades listadas como excluídas não serão alteradas. As propriedades podem ser relatadas incorretamente como excluídas quando não estão no modelo, mas são definidas automaticamente durante a implantação como valores padrão. Este resultado é considerado "ruído" na análise de cenários hipotéticos. O recurso implantado final terá os valores definidos para as propriedades. À medida que a operação hipotética amadurece, essas propriedades serão filtradas do resultado.

Avalie programaticamente os resultados hipotéticos

Agora, vamos avaliar programaticamente os resultados hipotéticos atribuindo o comando a uma variável.

$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"

Pode ver um resumo de cada alteração.

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

Confirmar eliminação

A operação hipotética suporta o uso do modo de implantação. Quando definido para o modo de conclusão, os recursos que não estão no modelo são excluídos. O exemplo a seguir implanta um modelo que não tem recursos definidos no modo completo.

Para visualizar as alterações antes de implantar um modelo, use o parâmetro confirm switch com o comando deployment. Se as alterações forem as esperadas, responda que deseja que a implantação seja concluída.

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

Como nenhum recurso é definido no modelo e o modo de implantação está definido para ser concluído, a rede virtual será excluída.

Captura de tela da saída da operação hipotética de implantação do modelo do Gerenciador de Recursos no modo de implantação concluída.

A saída do texto é:

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"):

Você vê as alterações esperadas e pode confirmar que quer que a implementação prossiga.

SDKs

Você pode usar a operação hipotética através dos SDKs do Azure.

Próximos passos