Operazione di simulazione della distribuzione Bicep

  • Articolo

Prima di distribuire un file Bicep, è possibile visualizzare in anteprima le modifiche che verranno apportate. Azure Resource Manager fornisce l'operazione di simulazione per consentire di vedere come cambiano le risorse se si distribuisce il file Bicep. L'operazione di simulazione non modifica in alcun modo le risorse esistenti. Prevede invece le modifiche se viene distribuito il file Bicep specificato.

È possibile usare l'operazione di simulazione con le operazioni di Azure PowerShell, interfaccia della riga di comando di Azure o API REST. La simulazione è supportata per le distribuzioni a livello di gruppo di risorse, sottoscrizione, gruppo di gestione e tenant.

Durante le operazioni di simulazione, la valutazione e l'espansione di templateLink non sono supportate. Di conseguenza, tutte le risorse distribuite usando collegamenti di modello all'interno di distribuzioni nidificate, inclusi i riferimenti alle specifiche di modello, non saranno visibili nei risultati dell'operazione di simulazione.

Risorse di formazione

Se si preferisce ottenere informazioni sull'operazione di simulazione tramite istruzioni dettagliate, vedere Visualizzare in anteprima le modifiche alla distribuzione di Azure usando le operazioni di simulazione.

Autorizzazioni necessarie

Per distribuire un file Bicep o un modello di ARM, è necessario l'accesso in scrittura alle risorse distribuite e l'accesso per tutte le operazioni sul tipo di risorsa Microsoft.Resources/deployments. Ad esempio, per distribuire una macchina virtuale, sono necessarie le autorizzazioni Microsoft.Compute/virtualMachines/write e Microsoft.Resources/deployments/*. L'operazione di simulazione ha gli stessi requisiti di autorizzazione.

Per un elenco dei ruoli e delle autorizzazioni, vedere Ruoli predefiniti di Azure.

Limiti di simulazione

La simulazione espande i modelli annidati fino a raggiungere questi limiti:

  • 500 modelli annidati.
  • 800 gruppi di risorse in una distribuzione tra gruppi di risorse.
  • 5 minuti impiegato per espandere i modelli annidati.

Quando viene raggiunto uno dei limiti, il tipo di modifica delle risorse rimanenti viene impostato su Ignora.

Installare un modulo Azure PowerShell

Per usare le operazioni di simulazione in PowerShell, è necessario avere la versione 4.2 o successiva del moduloAz.

Per installare il modulo, usare:

Install-Module -Name Az -Force

Per altre informazioni sull'installazione dei moduli, vedere Installare Azure PowerShell.

Installare il modulo dell'interfaccia della riga di comando di Azure

Per usare la simulazione nell'interfaccia della riga di comando di Azure, è necessario avere l'interfaccia della riga di comando di Azure 2.14.0 o versione successiva. Se necessario, installare la versione più recente dell'interfaccia della riga di comando di Azure.

See results (Visualizza risultati)

Quando si usa la simulazione in PowerShell o nell'interfaccia della riga di comando di Azure, l'output include risultati codificati a colori che consentono di visualizzare i diversi tipi di modifiche.

Bicep deployment what-if operation fullresourcepayload and change types

L'output di testo è:

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

L'operazione di simulazione non è in grado di risolvere la funzione di riferimento. Ogni volta che si imposta una proprietà su un'espressione modello che include la funzione di riferimento, la proprietà verrà modificata. Questo comportamento si verifica perché la simulazione confronta il valore corrente della proprietà (ad esempio true o false per un valore booleano) con l'espressione modello non risolta. Ovviamente, questi valori non corrispondono. Quando si distribuisce il file Bicep, la proprietà cambia solo quando l'espressione modello viene risolta in un valore diverso.

Comandi di simulazione

Azure PowerShell

Per visualizzare in anteprima le modifiche prima della distribuzione di un file Bicep, usare New-AzResourceGroupDeployment o New-AzSubscriptionDeployment. Aggiungere il parametro switch -Whatif al comando di distribuzione.

  • New-AzResourceGroupDeployment -Whatif per le distribuzioni del gruppo di risorse
  • New-AzSubscriptionDeployment -Whatif e New-AzDeployment -Whatif per le distribuzioni a livello di sottoscrizione

È possibile usare il parametro switch -Confirm per visualizzare in anteprima le modifiche e richiedere di continuare con la distribuzione.

  • New-AzResourceGroupDeployment -Confirm per le distribuzioni del gruppo di risorse
  • New-AzSubscriptionDeployment -Confirm e New-AzDeployment -Confirm per le distribuzioni a livello di sottoscrizione

I comandi precedenti restituiscono un riepilogo di testo che è possibile esaminare manualmente. Per ottenere un oggetto che è possibile esaminare a livello di codice per le modifiche, usare Get-AzResourceGroupDeploymentWhatIfResult o Get-AzSubscriptionDeploymentWhatIfResult.

  • $results = Get-AzResourceGroupDeploymentWhatIfResult per le distribuzioni del gruppo di risorse
  • $results = Get-AzSubscriptionDeploymentWhatIfResult o $results = Get-AzDeploymentWhatIfResult per le distribuzioni a livello di sottoscrizione

Interfaccia della riga di comando di Azure

Per visualizzare in anteprima le modifiche prima di distribuire un file Bicep, usare:

È possibile utilizzare l’opzione --confirm-with-what-if (o la sua forma abbreviata -c) per visualizzare l'anteprima delle modifiche e ricevere la richiesta di continuare con la distribuzione. Aggiungere questa opzione a:

Ad esempio, usare az deployment group create --confirm-with-what-if o -c per le distribuzioni di gruppi di risorse.

I comandi precedenti restituiscono un riepilogo di testo che è possibile esaminare manualmente. Per ottenere un oggetto JSON che è possibile controllare a livello di codice per verificare la presenza di modifiche, usare l'opzione --no-pretty-print. Ad esempio, usare az deployment group what-if --no-pretty-print per le distribuzioni di gruppi di risorse.

Per restituire i risultati senza colori, aprire il file di configurazione interfaccia della riga di comando di Azure. Impostare no_color su Sì.

API REST di Azure

Per l'API REST, usare:

Tipi di modifiche

L'operazione di simulazione elenca sette tipi diversi di modifiche:

  • Crea: la risorsa non esiste attualmente ma è definita nel file Bicep. La risorsa verrà creata.
  • Elimina: questo tipo di modifica si applica solo quando si usa la modalità completa per la distribuzione di modelli JSON. La risorsa esiste, ma non è definita nel file Bicep. Con la modalità completa, la risorsa verrà eliminata. In questo tipo di modifica sono incluse solo le risorse che supportano l'eliminazione in modalità completa.
  • Ignora: la risorsa esiste, ma non è definita nel file Bicep. La risorsa non verrà distribuita o modificata. Quando si raggiungono i limiti per l'espansione dei modelli annidati, si verifica questo tipo di modifica. Vedere Limiti di simulazione.
  • NoChange: la risorsa esiste ed è definita nel file Bicep. La risorsa verrà ridistribuita, ma le sue proprietà non verranno modificate. Questo tipo di modifica viene restituito quando ResultFormat è impostato su FullResourcePayloads, ovvero il valore predefinito.
  • NoEffect: la proprietà è pronta e verrà ignorata dal servizio. Ad esempio, la proprietà sku.tier è sempre impostata in modo che corrisponda a sku.name nello spazio dei nomi Microsoft.ServiceBus.
  • Modifica: la risorsa esiste ed è definita nel file Bicep. La risorsa verrà ridistribuita e le sue proprietà verranno modificate. Questo tipo di modifica viene restituito quando ResultFormat è impostato su FullResourcePayloads, ovvero il valore predefinito.
  • Distribuisci: la risorsa esiste ed è definita nel file Bicep. La risorsa verrà ridistribuita. Le proprietà della risorsa possono essere modificate o meno. L'operazione restituisce questo tipo di modifica quando non ha informazioni sufficienti per determinare se una o più proprietà verranno modificate. Questa condizione viene visualizzata solo quando ResultFormat è impostato su ResourceIdOnly.

Formato del risultato

È possibile controllare il livello di dettaglio restituito sulle modifiche stimate. è possibile procedere in due modi:

  • FullResourcePayloads: restituisce un elenco di risorse che modificheranno e dettagli sulle proprietà che modificheranno
  • ResourceIdOnly: restituisce un elenco di risorse che cambieranno

Il valore predefinito è FullResourcePayloads.

Per i comandi di distribuzione di PowerShell, usare il parametro -WhatIfResultFormat. Nei comandi dell'oggetto programmatico usare il parametro ResultFormat.

Per l'interfaccia della riga di comando di Azure, usare il parametro --result-format.

I risultati seguenti mostrano i due diversi formati di output:

  • Payload completi delle risorse

    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.

  • Solo ID risorsa

    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.

Eseguire l'operazione di simulazione

Set up environment (Configurare l'ambiente)

Per informazioni sul funzionamento di simulazione, verranno eseguiti alcuni test. Distribuire prima di tutto un file Bicep che crea una rete virtuale. Questa rete virtuale verrà usata per testare il modo in cui le modifiche vengono segnalate da simulazione. Scaricare una copia del file 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'
        }
      }
    ]
  }
}

Per distribuire il file Bicep, usare:

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

Modifica di test

Al termine della distribuzione, è possibile testare l'operazione di simulazione. Questa volta si distribuisce un file Bicep che modifica la rete virtuale. Manca uno dei tag originali, è stata rimossa una subnet e il prefisso dell'indirizzo è stato modificato. Scaricare una copia del file 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'
        }
      }
    ]
  }
}

Per visualizzare le modifiche, usare:

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

L'output della simulazione è simile a:

Bicep deployment what-if operation output

L'output di testo è:

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.

Si noti che nella parte superiore dell'output i colori sono definiti per indicare il tipo di modifiche.

Nella parte inferiore dell'output viene visualizzato il tag Proprietario eliminato. Il prefisso dell'indirizzo è stato modificato da 10.0.0.0/16 a 10.0.0.0/15. La subnet denominata subnet001 è stata eliminata. Tenere presente che queste modifiche non sono state distribuite. Viene visualizzata un'anteprima delle modifiche che verranno apportate se si distribuisce il file Bicep.

Alcune delle proprietà elencate come eliminate non cambieranno effettivamente. Le proprietà possono essere segnalate erroneamente come eliminate quando non si trovano nel file Bicep, ma vengono impostate automaticamente durante la distribuzione come valori predefiniti. Questo risultato è considerato "rumore" nella risposta di simulazione. La risorsa distribuita finale avrà i valori impostati per le proprietà. Con la maturità dell'operazione di simulazione, queste proprietà verranno filtrate in base al risultato.

Valutare a livello di codice i risultati di simulazione

A questo punto, si valuterà a livello di codice i risultati di simulazione impostando il comando su una variabile.

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

È possibile visualizzare un riepilogo di ogni modifica.

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

Conferma eliminazione

Per visualizzare in anteprima le modifiche prima di distribuire un file Bicep, usare il parametro confirm switch con il comando di distribuzione. Se le modifiche sono come previsto, rispondere che si vuole completare la distribuzione.

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

Bicep deployment what-if operation output deployment mode complete

L'output di testo è:

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"):

Vengono visualizzate le modifiche previste e si può confermare l'esecuzione della distribuzione.

Pulire le risorse

Quando le risorse di esempio non sono più necessarie, usare l'interfaccia della riga di comando di Azure o Azure PowerShell per eliminare il gruppo di risorse.

az group delete --name ExampleGroup

SDK

È possibile usare l'operazione di simulazione tramite gli SDK di Azure.

Passaggi successivi