Operação hipotética de implantação do bíceps

  • Artigo

Antes de implantar um arquivo Bicep, você pode visualizar as alterações que acontecerão. O Azure Resource Manager 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 com operações do Azure PowerShell, CLI do Azure ou API REST. Hipotecas são suportadas para implantações de grupo de recursos, assinatura, grupo de gerenciamento e nível de locatário.

Durante as operações de What-If, a avaliação e a expansão do não são suportadas 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 serão visíveis nos resultados da operação Hipóteses.

Recursos de formação

Se preferir saber mais sobre a operação hipotética por meio de orientação passo a passo, consulte Visualizar alterações de implantação do Azure usando hipóteses.

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 implantar uma máquina virtual, você precisa de Microsoft.Compute/virtualMachines/write permissões Microsoft.Resources/deployments/* . A operação hipotética tem os mesmos requisitos de permissão.

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

Limites hipotéticos

E se 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 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 do Azure PowerShell

Para usar hipóteses no PowerShell, você deve 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, consulte Instalar o Azure PowerShell.

Instalar o módulo CLI do Azure

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.

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 você definir uma propriedade para uma expressão de modelo que inclua a função de referência, os relatórios hipotéticos serão alterados. 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.

Comandos hipotéticos

Azure PowerShell

Para visualizar as alterações antes de implantar um arquivo Bicep, use New-AzResourceGroupDeployment ou New-AzSubscriptionDeployment. Adicione o -Whatif parâmetro switch ao comando deployment.

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

Você pode usar o -Confirm parâmetro switch para visualizar as alterações e ser solicitado a continuar com a implantação.

  • New-AzResourceGroupDeployment -Confirm Para implantações de grupos 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ê possa inspecionar programaticamente se há alterações, use Get-AzResourceGroupDeploymentWhatIfResult ou Get-AzSubscriptionDeploymentWhatIfResult.

  • $results = Get-AzResourceGroupDeploymentWhatIfResult Para implantações de grupos de recursos
  • $results = Get-AzSubscriptionDeploymentWhatIfResult ou $results = Get-AzDeploymentWhatIfResult para implantações de nível de assinatura

CLI do Azure

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

Você pode usar o --confirm-with-what-if switch (ou seu formulário -ccurto) 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.

API REST do Azure

Para API REST, use:

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 você atingir os limites para expandir modelos aninhados, encontrará esse 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 úteis 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.

Executar operação hipotética

Configurar ambiente

Para ver como funciona o 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 por hipóteses. Faça o download de uma cópia do arquivo Bicep.

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

New-AzResourceGroup `
  -Name ExampleGroup `
  -Location centralus
New-AzResourceGroupDeployment `
  -ResourceGroupName ExampleGroup `
  -TemplateFile "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. Está faltando uma das tags originais, uma sub-rede foi removida e o prefixo do endereço foi alterado. Faça o download de uma cópia do arquivo Bicep.

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

New-AzResourceGroupDeployment `
  -Whatif `
  -ResourceGroupName ExampleGroup `
  -TemplateFile "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

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 o tipo de alterações.

Na parte inferior da saída, ele mostra que o proprietário da tag foi excluído. 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 resposta hipotética. 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.

Avalie programaticamente os resultados hipotéticos

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

$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
}

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.

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

Implementação do bíceps hipotética modo de implantação de saída de operaçã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/./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.

Clean up resources (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

SDKs

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

Próximos passos