Partilhar via

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

Antes de implantar um arquivo Bicep, você pode visualizar as alterações que acontecerão. O Azure Resource Manager (ARM) fornece a operação hipotética 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 aos recursos existentes. Em vez disso, ele prevê as alterações se o arquivo Bicep especificado for implantado.

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

Durante as operações de What-If, a avaliação e a expansão de templateLink não são suportadas. Como resultado, quaisquer recursos implantados através de ligações de modelos em implantações aninhadas, incluindo referências a especificações de modelos, não serão visíveis nos resultados da operação What-If.

Pré-requisitos

Permissões obrigató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 hipotética 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.

Installation

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.

Limitações

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.

Curto-circuito

A operação hipotética em implantações do Bicep pode encontrar "curto-circuito", um cenário em que o serviço não pode analisar completamente um módulo ou recurso devido à estrutura da implantação ou dependências do 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, geralmente 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 aninhados também pode acontecer, resultando em todos os recursos dentro do módulo sendo excluídos dos resultados da análise hipotética. Nesses casos, a resposta da API inclui uma mensagem de diagnóstico para indicar o problema.

Executando a operação hipotética

Usar uma versão recente do módulo Az PowerShell (13.1.0 ou posterior) ou da CLI do Azure (2.75.0 ou posterior) fornecerá diagnósticos quando não for possível 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á — apenas acontece silenciosamente.

Comandos hipotéticos

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

A CLI do Azure versão 2.76.0 ou posterior introduz o --validation-level switch para determinar quão completamente o ARM valida o modelo Bicep durante esse processo. Aceita os seguintes valores:

  • Provedor (padrão): executa a validação completa, incluindo sintaxe do modelo, definições de recursos, 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 Provider, mas verifica apenas se há permissões de leitura em cada recurso, em vez de permissões de implantação completas. Isso é útil quando você deseja validar configurações de recursos sem exigir acesso total.
  • Modelo: Executa apenas a validação estática, verificando a sintaxe e a estrutura do modelo enquanto ignora as verificações de comprovação (por exemplo, disponibilidade de recursos) e as verificações de permissão. Isso é menos completo, potencialmente faltando problemas que podem causar falhas de implantação.

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.

Para API REST, use:

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

Configurar ambiente

Para ver como funciona o 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@2024-07-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'
        }
      }
    ]
  }
}

Para implantar o arquivo Bicep, use:

az group create \
  --name ExampleGroup \
  --___location "Central US"
az deployment group create \
  --resource-group ExampleGroup \
  --template-file "what-if-before.bicep"

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 arquivo Bicep que altera a rede virtual. Comparando com o exemplo anterior, o exemplo a seguir perde uma das tags originais, uma sub-rede foi removida e o prefixo do endereço foi alterado. Salve o seguinte arquivo Bicep como what-if-after.bicep:

resource vnet 'Microsoft.Network/virtualNetworks@2024-07-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'
        }
      }
    ]
  }
}

Para visualizar as alterações, use:

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

O resultado de what-if é semelhante a:

Saída da operação hipotética de implantação do bíceps

A saída do 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 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 arquivo Bicep.

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 arquivo Bicep, 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.

Confirmar eliminação

Para visualizar as alterações antes de implantar um arquivo Bicep, 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.

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

Saída da operação de simulação da implementação do Bicep no modo de implementação concluída

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/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 quer que a implementação prossiga.

Avalie programaticamente os resultados hipotéticos

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

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

Entenda os resultados hipotéticos

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.

Implantação do bíceps operação hipotética fullresourcepayload 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.

Nota

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 arquivo Bicep, a propriedade só será alterada quando a expressão do modelo for resolvida para um valor diferente.

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 arquivo Bicep. O recurso será criado.
  • Excluir: esse tipo de alteração só se aplica ao usar o modo completo para implantação de modelo JSON. O recurso existe, mas não está definido no arquivo Bicep. 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 arquivo Bicep. O recurso não será implementado ou modificado. Quando atingires os limites para expandir templates aninhados, enfrentarás este tipo de alteração. Consulte Limites hipotéticos.
  • NoChange: O recurso existe e é definido no arquivo Bicep. 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 arquivo Bicep. O recurso será novamente implementado e as propriedades do recurso mudam. Esse tipo de alteração é retornado quando ResultFormat é definido como FullResourcePayloads, que é o valor padrão.
  • Implantar: o recurso existe e é definido no arquivo Bicep. O recurso será novamente implementado. As propriedades do recurso podem ou não ser alteradas. A operação devolve este tipo de alteração quando não tiver informações suficientes para determinar se há propriedades que vão mudar. 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.

Expressões não avaliadas

Se uma expressão não avaliada aparecer na saída, isso significa que não é possível avaliá-la fora do contexto de uma implantação. A expressão é mostrada as-is 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-01-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 hora atuais. Quando você executa hipóteses, essas expressões são mostradas as-is porque não podem ser avaliadas fora do contexto de uma implantação. A saída hipotética 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 seguintes expressões não são avaliadas durante o período hipotético:

  • 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 recursos que não estão definidas no mesmo modelo.
  • Qualquer função de recurso, como listKeys().

Limpar recursos

Quando não precisar mais dos recursos de exemplo, use a CLI do Azure ou o Azure PowerShell para excluir o grupo de recursos.

az group delete --name ExampleGroup

Próximos passos