Compartilhar via

What-If do Bicep: visualizar alterações antes da implantação

Antes de implantar um arquivo Bicep, você pode visualizar as alterações que ocorrerão. O ARM (Azure Resource Manager) fornece a operação what-if para permitir que você veja como os recursos serão alterados se você implantar o arquivo Bicep. A operação what-if não faz alterações 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 de hipóteses com o Visual Studio Code, o Azure PowerShell, a CLI do Azure ou as operações da 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 as 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 por meio de 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.

Pré-requisitos

Permissões necessárias

Para implantar um arquivo Bicep ou um modelo do 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, você precisa das permissões Microsoft.Compute/virtualMachines/write e Microsoft.Resources/deployments/*. A operação do teste de hipóteses 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 a forma como o ARM valida completamente o modelo Bicep durante esse processo. Para obter mais informações, consulte comandos what-if

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

Installation

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 versão mais recente da CLI do Azure.

Limitações

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.

Curto-circuito

A operação de teste de hipóteses em implantações Bicep pode encontrar "curto-circuito", um cenário em que o serviço não consegue analisar completamente um módulo ou recurso devido à estrutura da implantação ou a dependências de estado externo. O curto-circuito de um recurso individual ocorre quando sua ID de recurso ou versão da API não pode ser calculada fora do contexto de implantação, muitas vezes devido a expressões não resolvidas ou dependências externas. Para obter mais informações, consulte expressões não avaliadas. Embora raro, o curto-circuito de módulos ou recursos de implantação aninhada também pode ocorrer, resultando na exclusão de todos os recursos no módulo dos resultados da análise de teste de hipóteses. Nesses casos, a resposta à API inclui uma mensagem de diagnóstico para indicar o problema.

Executando a operação de simulação "what-if"

O uso de uma versão recente do módulo do Az PowerShell (13.1.0 ou posterior) ou da CLI do Azure (2.75.0 ou posterior) fornecerá diagnóstico quando o what-if não puder analisar parte da implantação. As versões anteriores dessas ferramentas se comportam da mesma maneira, mas não exibem o diagnóstico. Por exemplo, se você usar a CLI versão 2.74.0, o problema ainda ocorrerá, isso ocorrerá silenciosamente.

Comandos what-if

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

A CLI do Azure versão 2.76.0 ou posterior apresenta a opção --validation-level para determinar o quanto o ARM valida completamente o modelo Bicep durante esse processo. Ele aceita os seguintes valores:

  • Provedor (padrão): executa a validação completa, incluindo sintaxe de modelo, definições de recurso, dependências e verificações de permissão para garantir que você tenha permissões suficientes para implantar todos os recursos no modelo.
  • ProviderNoRbac: executa a validação completa do modelo e dos recursos, semelhante ao Provedor, mas verifica apenas as permissões de leitura em cada recurso em vez de permissões de implantação completas. Isso é útil quando você deseja validar as configurações de recursos sem a necessidade de acesso total.
  • Modelo: executa somente validação estática, verificando a sintaxe e a estrutura do modelo ao ignorar verificações de pré-vôo (por exemplo, disponibilidade de recursos) e verificações de permissão. Isso é menos completo, potencialmente faltando problemas que podem causar falhas de implantação.

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.

Para a API REST, use:

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

Configurar o ambiente

Para ver como funciona a what-if, vamos executar alguns testes. Primeiro, implante um arquivo Bicep que crie uma rede virtual. Salve o seguinte arquivo Bicep como what-if-before.bicep:

resource vnet 'Microsoft.Network/virtualNetworks@2025-01-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:

az group create \
  --name ExampleGroup \
  --___location "Central US"
az deployment group create \
  --resource-group ExampleGroup \
  --template-file "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. Em comparação com o exemplo anterior, o exemplo a seguir perde uma das marcas originais, uma sub-rede foi removida e o prefixo de endereço foi alterado. Salve o seguinte arquivo Bicep como what-if-after.bicep:

resource vnet 'Microsoft.Network/virtualNetworks@2025-01-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:

az deployment group what-if \
  --resource-group ExampleGroup \
  --template-file "what-if-after.bicep"

A saída de teste de hipóteses é 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

    - 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"
          properties.defaultOutboundAccess:             false
          properties.privateEndpointNetworkPolicies:    "Disabled"
          properties.privateLinkServiceNetworkPolicies: "Enabled"

      ]

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.

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.

az deployment group create \
  --resource-group ExampleGroup \
  --confirm-with-what-if \
  --template-file "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/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/ExampleGroup

  ~ Microsoft.Network/virtualNetworks/vnet-001 [2024-07-01]
    - properties.privateEndpointVNetPolicies: "Disabled"
    - 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"
          properties.defaultOutboundAccess:             false
          properties.privateEndpointNetworkPolicies:    "Disabled"
          properties.privateLinkServiceNetworkPolicies: "Enabled"

      ]

Resource changes: 1 to modify.

Are you sure you want to execute the deployment? (y/n):

Você vê as alterações esperadas e pode confirmar que deseja que a implantação seja executada.

Avaliar programaticamente os resultados de hipóteses

Agora, vamos avaliar programaticamente os resultados what-if definindo o comando como uma variável.

results=$(az deployment group what-if --resource-group ExampleGroup --template-file "what-if-after.bicep" --no-pretty-print)

Entender os resultados do cenário hipotético

Exibir os 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.

Tipos de alteração

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 ou 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.
  • 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 mudadas. 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, mas as propriedades do recurso não serão mudadas. 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 mudar. A operação retorna esse tipo de alteração quando não tem informações suficientes para determinar se alguma propriedade será mudada. Você só verá essa condição quando ResultFormat estiver definido comoResourceIdOnly.

Formato do 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.

Expressões não avaliadas

Se uma expressão não avaliada aparecer na saída, isso significa que o teste de hipóteses não poderá avaliá-la fora do contexto de uma implantação. A expressão é mostrada no estado em que se encontra para indicar as informações que serão preenchidas quando a implantação for executada.

param now string = utcNow()

resource sa 'Microsoft.Storage/storageAccounts@2025-06-01' = {
  name: 'acct'
  ___location: resourceGroup().___location
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
  tags: {
    lastDeployedOn: now
    lastDeployedBy: deployer().userPrincipalName
  }
}

No exemplo anterior, o now parâmetro usa a utcNow() função para obter a data e a hora atuais. Quando você executa o teste de hipóteses, essas expressões são mostradas no estado em que se encontram porque não podem ser avaliadas fora do contexto de uma implantação. A saída de hipóteses será semelhante a:

Note: The result may contain false positive predictions (noise).
You can help us improve the accuracy of the result by opening an issue here: https://aka.ms/WhatIfIssues

Resource and property changes are indicated with this symbol:
  ~ Modify

The deployment will update the following scope:

Scope: /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/jgaotest

  ~ Microsoft.Storage/storageAccounts/acct0808 [2025-01-01]
    ~ tags.lastDeployedOn: "20250808T200145Z" => "[utcNow()]"

Resource changes: 1 to modify.

As expressões a seguir não são avaliadas durante o what-if:

  • Funções não determinísticas, como newGuid() e utcNow()
  • Qualquer referência a um valor de parâmetro seguro.
  • Referências a recursos que não são implantados no mesmo modelo.
  • Referências a propriedades de recurso que não são definidas no mesmo modelo.
  • Qualquer função de recurso, como listKeys().

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

Próximas etapas

  • Last updated on