Operação teste de hipóteses de implantação do modelo do ARM

  • Artigo

Antes de implantar um modelo do Azure Resource Manager (modelo ARM), você pode visualizar as alterações que ocorrerão. O Azure Resource Manager permite que você veja como os recursos serão alterados se você implantar o modelo. A operação what-if não faz nenhuma alteração nos recursos existentes. Em vez disso, ela prevê as alterações se o modelo especificado é implantado.

Você pode usar a operação what-if com as operações de Azure PowerShell, CLI do Azure ou API REST. O what-if tem suporte para implantações de grupo de recursos, de assinatura, de grupo de gerenciamento e de nível de locatário.

Recursos de treinamento

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

Permissões necessárias

Para implantar um arquivo Bicep ou um modelo do ARM, você precisa de acesso de gravação nos recursos que está implantando e acesso a todas as operações no tipo de recurso Microsoft.Resources/implantações. Por exemplo, para implantar uma máquina virtual, você precisa Microsoft.Compute/virtualMachines/write e permissões Microsoft.Resources/deployments/*. A operação do teste de hipóteses tem os mesmos requisitos de permissão.

Para ver uma lista de funções e permissões, consulte Funções interna do Azure.

Limites de teste de hipóteses

O teste de hipóteses expande modelos aninhados até que esses limites sejam atingidos:

  • 500 modelos aninhados.
  • 800 grupos de recursos em uma implantação entre grupos de recursos.
  • 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 o comando what-if no PowerShell, você precisará 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, confira Instalar o Azure PowerShell.

Instalar o módulo da CLI do Azure

Para usar o what-if na CLI do Azure, você precisará ter a CLI do Azure 2.14.0 ou posterior. Se necessário, instale a última versão da CLI do Azure.

Ver resultados

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

Captura de tela da operação hipotética de implantação do modelo do Resource Manager com carga total de recursos e tipos de alteração.

A saída de 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 what-if não pode resolver a função de referência. Sempre que você definir uma propriedade para uma expressão de modelo que inclui a função de referência, os relatórios what-if serão alterados pela propriedade. Esse comportamento ocorre porque o what-if compara o valor atual da propriedade (como true ou false para um valor booliano) com a expressão de modelo não resolvida. Obviamente, esses valores não serão correspondentes. Quando você implanta o modelo, a propriedade só será alterada quando a expressão do modelo for resolvida para um valor diferente.

Comandos what-if

Azure PowerShell

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

  • New-AzResourceGroupDeployment -Whatif para implantação de grupo de recursos

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

Você pode usar o parâmetro de opção -Confirm para visualizar as alterações e receber uma solicitação para continuar com a implantação.

  • New-AzResourceGroupDeployment -Confirm para implantações de grupo 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ê pode inspecionar para alterações programaticamente, use Get-AzResourceGroupDeploymentWhatIfResult ou Get-AzSubscriptionDeploymentWhatIfResult.

  • $results = Get-AzResourceGroupDeploymentWhatIfResult para implantações de grupo de recursos
  • $results = Get-AzSubscriptionDeploymentWhatIfResult e $results = Get-AzDeploymentWhatIfResult para implantações em nível de assinatura

CLI do Azure

Para pré-visualizar mudanças antes de implantar um modelo, use:

Você pode usar a opção --confirm-with-what-if (ou sua forma encurtada -c) para visualizar as alterações e receber uma solicitação para 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 para alterações programaticamente, use a opção --no-pretty-print. Por exemplo, use az deployment group what-if --no-pretty-print para implantações de grupo de recursos.

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

API REST do Azure

Para a API REST, use:

Alterar tipos

A operação de teste de hipóteses 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á excluído. Somente os recursos que dão suporte à exclusão pelo modo completo são incluídos nesse tipo de alteração.
  • Ignorar: o recurso existe, mas não está definido no modelo. O recurso não será implantado nem modificado. Ao atingir os limites de expansão de modelos aninhados, você encontrará esse tipo de alteração. Consulte Limites de teste de hipóteses.
  • NoChange: o recurso existe e está definido no modelo. O recurso será reimplantado, mas as propriedades do recurso não serão alteradas. Esse tipo de alteração é retornado quando ResultFormat é definido como FullResourcePayloads, que é o valor padrão.
  • NoEffect: A propriedade é somente leitura e será ignorada pelo serviço. Por exemplo, a propriedade sku.tier é sempre definida para corresponder sku.name no namespace Microsoft.ServiceBus.
  • Modificar: o recurso existe e está 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 está definido no modelo. O recurso será reimplantado. 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 as propriedades serão alteradas. Você só vê essa condição quando ResultFormat é definido como ResourceIdOnly.

Formato de resultado

Você controla o nível de detalhe que é retornado sobre as alterações previstas. Você 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 parâmetro -WhatIfResultFormat. Nos comandos de objeto programático, use o parâmetro ResultFormat.

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

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

  • Cargas de recursos completas

    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.

  • Somente ID do 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 what-if

Configurar o ambiente

Para ver como funciona a what-if, vamos executar alguns testes. Primeiro, implante um modelo que cria uma rede virtual. Você usará essa rede virtual para testar como as alterações são relatadas pela 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"

Modificação de teste

Após a conclusão da implantação, você estará pronto para testar a operação what-if. Desta vez, você implantará um modelo que altera a rede virtual. Falta uma marca original, uma sub-rede foi removida e o prefixo de 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"

A saída de what-if é semelhante a:

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

A saída de 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 os tipos de alterações.

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

Algumas das propriedades listadas como excluídas não serão realmente alteradas. As propriedades podem ser incorretamente relatadas como excluídas quando não estão no modelo, mas são definidas de maneira automática durante a implantação como valores padrão. Esse resultado é considerado "ruído" na resposta what-if. O recurso implantado final terá os valores definidos para as propriedades. A medida em que a operação what-if se desenvolve, essas propriedades serão filtradas do resultado.

Avaliar programaticamente os resultados de hipóteses

Agora, vamos avaliar programaticamente os resultados what-if definindo o comando como 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"

Você pode ver um resumo de cada alteração.

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

Confirmar exclusão

A operação what-if dá suporte ao uso do modo de implantação. Quando a opção é definida como modo completo, 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 confirmar opção com o comando de implantação. Se as alterações forem as esperadas, confirme que você deseja concluir a implantação.

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 está definido no modelo e o modo de implantação está definido como 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 Resource Manager no modo de implantação concluída.

A saída de 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 deseja que a implantação seja executada.

SDKs

Você pode usar a operação what-if por meio dos SDKs do Azure.

Próximas etapas