Operação de hipóteses de implementação do Bicep

Artigo
09/06/2023

Antes de implementar um ficheiro Bicep, pode pré-visualizar as alterações que irão ocorrer. O Azure Resource Manager fornece a operação what-if para lhe permitir ver como os recursos serão alterados se implementar o ficheiro Bicep. A operação what-if não faz alterações aos recursos existentes. Em vez disso, prevê as alterações se o ficheiro Bicep especificado for implementado.

Pode utilizar a operação de hipóteses com operações Azure PowerShell, CLI do Azure ou API REST. O what-if é suportado para o grupo de recursos, subscrição, grupo de gestão e implementações ao nível do inquilino.

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

Recursos de preparação

Se preferir saber mais sobre a operação de hipóteses através da documentação de orientação passo a passo, veja Pré-visualizar as alterações de implementação do Azure com o what-if.

Permissões obrigatórias

Para implementar um ficheiro Bicep ou modelo do ARM, precisa de acesso de escrita nos recursos que está a implementar e acesso a todas as operações no tipo de recurso Microsoft.Resources/deployments. Por exemplo, para implementar uma máquina virtual, precisa Microsoft.Compute/virtualMachines/write e Microsoft.Resources/deployments/* permissões. A operação what-if tem os mesmos requisitos de permissão.

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

Limites de hipóteses

O what-if expande os modelos aninhados até que estes limites sejam atingidos:

500 modelos aninhados.
800 grupos de recursos numa implementação entre grupos de recursos.
5 minutos necessários 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 Azure PowerShell

Para utilizar o what-if no PowerShell, tem de ter a versão 4.2 ou posterior do módulo Az.

Para instalar o módulo, utilize:

Install-Module -Name Az -Force

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

Instalar o módulo da CLI do Azure

Para utilizar o what-if na CLI do Azure, tem de 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 utiliza o what-if no PowerShell ou na CLI do Azure, a saída inclui resultados codificados por cores que o ajudam a ver os diferentes tipos de alterações.

Tipo de alteração e carregamento completos da operação de hipóteses da implementação do Bicep

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 what-if não consegue resolver a função de referência. Sempre que definir uma propriedade para uma expressão de modelo que inclua a função de referência, o what-if comunica que a propriedade será alterada. Este comportamento acontece porque compara o valor atual da propriedade (por true exemplo, ou false para um valor booleano) com a expressão de modelo não resolvida. Obviamente, estes valores não corresponderão. Quando implementar o ficheiro Bicep, a propriedade só será alterada quando a expressão do modelo for resolvida para um valor diferente.

Comandos de hipótese

Azure PowerShell

Para pré-visualizar as alterações antes de implementar um ficheiro Bicep, utilize New-AzResourceGroupDeployment ou New-AzSubscriptionDeployment. Adicione o -Whatif parâmetro switch ao comando de implementação.

New-AzResourceGroupDeployment -Whatif para implementações de grupos de recursos
New-AzSubscriptionDeployment -Whatif e New-AzDeployment -Whatif para implementações ao nível da subscrição

Pode utilizar o -Confirm parâmetro switch para pré-visualizar as alterações e ser-lhe pedido para continuar com a implementação.

New-AzResourceGroupDeployment -Confirm para implementações de grupos de recursos
New-AzSubscriptionDeployment -Confirm e New-AzDeployment -Confirm para implementações ao nível da subscrição

Os comandos anteriores devolvem um resumo de texto que pode inspecionar manualmente. Para obter um objeto que pode inspecionar programaticamente para obter alterações, utilize Get-AzResourceGroupDeploymentWhatIfResult ou Get-AzSubscriptionDeploymentWhatIfResult.

$results = Get-AzResourceGroupDeploymentWhatIfResult para implementações de grupos de recursos
$results = Get-AzSubscriptionDeploymentWhatIfResult ou $results = Get-AzDeploymentWhatIfResult para implementações ao nível da subscrição

CLI do Azure

Para pré-visualizar as alterações antes de implementar um ficheiro Bicep, utilize:

az deployment group what-if para implementações de grupos de recursos
az deployment sub what-if para implementações ao nível da subscrição
az deployment mg what-if para implementações de grupos de gestão
az deployment tenant what-if for tenant deployments

Pode utilizar o comutador (ou o --confirm-with-what-if respetivo formulário -ccurto) para pré-visualizar as alterações e ser-lhe pedido para continuar com a implementação. Adicione este comutador a:

Por exemplo, utilize az deployment group create --confirm-with-what-if ou -c para implementações de grupos de recursos.

Os comandos anteriores devolvem um resumo de texto que pode inspecionar manualmente. Para obter um objeto JSON que pode inspecionar programaticamente para ver se existem alterações, utilize o --no-pretty-print comutador. Por exemplo, utilize az deployment group what-if --no-pretty-print para implementações de grupos de recursos.

Se quiser devolver os resultados sem cores, abra o ficheiro de configuração da CLI do Azure . Defina no_color como sim.

API REST do Azure

Para a API REST, utilize:

Implementações – What If for resource group deployments (E se para implementações de grupos de recursos)
Implementações – E se no Âmbito da Subscrição para implementações de subscrições
Implementações – What If At Management Group Scope for management group deployments (E se no Âmbito do Grupo de Gestão para implementações de grupos de gestão)
Implementações – What If No Âmbito do Inquilino para implementações de inquilinos.

Tipos de alterações

A operação what-if lista sete tipos diferentes de alterações:

Criar: o recurso não existe atualmente, mas está definido no ficheiro Bicep. O recurso será criado.
Eliminar: este tipo de alteração só se aplica ao utilizar o modo completo para a implementação do modelo JSON. O recurso existe, mas não está definido no ficheiro Bicep. Com o modo completo, o recurso será eliminado. Apenas os recursos que suportam a eliminação completa do modo estão incluídos neste tipo de alteração.
Ignorar: o recurso existe, mas não está definido no ficheiro Bicep. O recurso não será implementado ou modificado. Quando atingir os limites para expandir modelos aninhados, encontrará este tipo de alteração. Veja Limites de hipóteses.
NoChange: o recurso existe e é definido no ficheiro Bicep. O recurso será novamente implementado, mas as propriedades do recurso não mudam. Este tipo de alteração é devolvido quando ResultFormat está definido como FullResourcePayloads, que é o valor predefinido.
NoEffect: a propriedade está pronta apenas e será ignorada pelo serviço. Por exemplo, a sku.tier propriedade está sempre definida para corresponder sku.name no Microsoft.ServiceBus espaço de nomes.
Modificar: o recurso existe e é definido no ficheiro Bicep. O recurso será novamente implementado e as propriedades do recurso mudam. Este tipo de alteração é devolvido quando ResultFormat está definido como FullResourcePayloads, que é o valor predefinido.
Implementar: o recurso existe e é definido no ficheiro 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. Só verá esta condição quando ResultFormat estiver definido como ResourceIdOnly.

Formato dos resultados

Controla o nível de detalhe devolvido sobre as alterações previstas. Tem duas opções:

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

O valor predefinido é FullResourcePayloads.

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

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

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

Payloads de recursos completos

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 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 a operação what-if

Configurar o ambiente

Para ver como funciona o what-if, vamos executar alguns testes. Primeiro, implemente um ficheiro Bicep que cria uma rede virtual. Irá utilizar esta rede virtual para testar a forma como as alterações são comunicadas pelo what-if. Transfira uma cópia do ficheiro 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'
        }
      }
    ]
  }
}

Para implementar o ficheiro Bicep, utilize:

PowerShell
CLI do Azure

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

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 implementação, está pronto para testar a operação what-if. Desta vez, vai implementar um ficheiro Bicep que altera a rede virtual. Falta uma das etiquetas originais, uma sub-rede foi removida e o prefixo de endereço foi alterado. Transfira uma cópia do ficheiro 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'
        }
      }
    ]
  }
}

Para ver as alterações, utilize:

PowerShell
CLI do Azure

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

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

O resultado de what-if é semelhante a:

Resultado da operação what-if da implementação 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.

Repare na parte superior do resultado que as cores estão definidas para indicar o tipo de alterações.

Na parte inferior do resultado, mostra que a etiqueta Proprietário foi eliminada. O prefixo de endereço foi alterado de 10.0.0.0/16 para 10.0.0.0/15. A sub-rede denominada sub-rede001 foi eliminada. Lembre-se de que estas alterações não foram implementadas. Verá uma pré-visualização das alterações que ocorrerão se implementar o ficheiro Bicep.

Algumas das propriedades listadas como eliminadas não serão realmente alteradas. As propriedades podem ser comunicadas incorretamente como eliminadas quando não estão no ficheiro Bicep, mas são definidas automaticamente durante a implementação como valores predefinidos. Este resultado é considerado "ruído" na resposta what-if. O recurso implementado final terá os valores definidos para as propriedades. À medida que a operação what-if amadurece, estas propriedades serão filtradas do resultado.

Avaliar programaticamente os resultados de hipóteses

Agora, vamos avaliar programaticamente os resultados de hipótese ao definir o comando como uma variável.

PowerShell
CLI do Azure

$results = Get-AzResourceGroupDeploymentWhatIfResult `
  -ResourceGroupName ExampleGroup `
  --template-file "what-if-after.bicep"

Pode ver um resumo de cada alteração.

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

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

Confirmar eliminação

Para pré-visualizar as alterações antes de implementar um ficheiro Bicep, utilize o parâmetro confirmar comutador com o comando de implementação. Se as alterações forem as esperadas, responda que pretende que a implementação seja concluída.

PowerShell
CLI do Azure

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

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

Implementação bicep modo de implementação de saída de operação what-if concluído