Operação de hipótese de implantação do Bicep

  • Artigo

Antes de implantar um arquivo Bicep, você pode visualizar as alterações que ocorrerão. O Azure Resource Manager oferece a operação de hipótese para que você veja como os recursos serão alterados ao implantar o arquivo Bicep. A operação what-if não faz nenhuma alteração nos recursos existentes. Em vez disso, ela prevê as alterações resultantes da implantação do arquivo Bicep especificado.

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.

Durante operações de teste de hipóteses, não há suporte para a avaliação e a expansão do templateLink. Como resultado, todos os recursos implantados usando links de modelo em implantações aninhadas, incluindo referências de especificação de modelo, não ficarão visíveis nos resultados da operação de teste de hipóteses.

Recursos de treinamento

Se preferir saber mais sobre a operação de teste de hipóteses por meio de diretrizes passo a passo, consulte Versão prévia de 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.

Tipos de alteração e a operação de hipótese de implantação fullresourcepayload

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 arquivo Bicep, 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 arquivo Bicep, 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 visualizar as alterações antes de implantar um arquivo Bicep, 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 arquivo Bicep. O recurso será criado.
  • Excluir: esse tipo de alteração só se aplica ao usar o modo completo para a implantação de modelo JSON. O recurso existe, mas não está definido no arquivo Bicep. 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 arquivo Bicep. 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. Confira Limites de teste de hipóteses.
  • Sem alterações: o recurso existe e está definido no arquivo Bicep. 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 arquivo Bicep. 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 arquivo Bicep. 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 arquivo Bicep que crie uma rede virtual. Você usará essa rede virtual para testar como as alterações são relatadas pela what-if. Baixe uma cópia do arquivo Bicep.

resource vnet 'Microsoft.Network/virtualNetworks@2021-02-01' = {
  name: 'vnet-001'
  location: resourceGroup().location
  tags: {
    CostCenter: '12345'
    Owner: 'Team A'
  }
  properties: {
    addressSpace: {
      addressPrefixes: [
        '10.0.0.0/16'
      ]
    }
    enableVmProtection: false
    enableDdosProtection: false
    subnets: [
      {
        name: 'subnet001'
        properties: {
          addressPrefix: '10.0.0.0/24'
        }
      }
      {
        name: 'subnet002'
        properties: {
          addressPrefix: '10.0.1.0/24'
        }
      }
    ]
  }
}

Vamos implantar o arquivo Bicep. Use o:

New-AzResourceGroup `
  -Name ExampleGroup `
  -Location centralus
New-AzResourceGroupDeployment `
  -ResourceGroupName ExampleGroup `
  -TemplateFile "what-if-before.bicep"

Modificação de teste

Após a conclusão da implantação, você estará pronto para testar a operação what-if. Agora, implante um arquivo Bicep que altere a rede virtual. Falta uma marca original, uma sub-rede foi removida e o prefixo de endereço foi alterado. Baixe uma cópia do arquivo Bicep.

resource vnet 'Microsoft.Network/virtualNetworks@2021-02-01' = {
  name: 'vnet-001'
  location: resourceGroup().location
  tags: {
    CostCenter: '12345'
  }
  properties: {
    addressSpace: {
      addressPrefixes: [
        '10.0.0.0/15'
      ]
    }
    enableVmProtection: false
    enableDdosProtection: false
    subnets: [
      {
        name: 'subnet002'
        properties: {
          addressPrefix: '10.0.1.0/24'
        }
      }
    ]
  }
}

Visualizar as alterações. Use o:

New-AzResourceGroupDeployment `
  -Whatif `
  -ResourceGroupName ExampleGroup `
  -TemplateFile "what-if-after.bicep"

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

Saída da operação de hipótese de implantação do Bicep

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.enableVmProtection: false
    ~ 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á as alterações que ocorrerão ao implantar o arquivo Bicep.

Algumas das propriedades listadas como excluídas não serão realmente alteradas. As propriedades podem ser relatadas incorretamente como excluídas quando não estão no arquivo Bicep, mas são definidas como valores padrão de maneira automática durante a implantaçã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 `
  --template-file "what-if-after.bicep"

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

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

Confirmar exclusão

Para visualizar as alterações antes de implantar um arquivo Bicep, use o parâmetro de confirmação de alternância 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 `
  -Confirm `
  -TemplateFile "what-if-after.bicep"

Modo completo de implantação de saída da operação de hipótese de implantação de arquivo Bicep

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.enableVmProtection: false
    ~ 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.

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.

Limpar os recursos

PQuando não precisar mais dos recursos de exmplo, use a CLI do Azure ou o Azure PowerShell para exclur o grupo de recursos.

az group delete --name ExampleGroup

SDKs

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

Próximas etapas