Condividi tramite

Simulazione Bicep: Anteprima delle modifiche prima della distribuzione

Prima di distribuire un file Bicep, è possibile visualizzare in anteprima le modifiche che verranno apportate. Azure Resource Manager (ARM) fornisce l'operazione 'what-if' per consentire di vedere come cambieranno 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 Visual Studio Code, di Azure PowerShell, dell'interfaccia della riga di comando di Azure o dell'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 a modelli all'interno di distribuzioni annidate, inclusi i riferimenti alle specifiche di modello, non saranno visibili nei risultati dell'operazione di simulazione.

Prerequisiti

Autorizzazioni necessarie

Per distribuire un file Bicep o un modello di Azure Resource Manager (ARM), è necessario l'accesso in scrittura alle risorse distribuite e l'accesso a tutte le operazioni sul Microsoft.Resources/deployments tipo di risorsa. 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.

L'interfaccia della riga di comando di Azure versione 2.76.0 o successiva e Azure PowerShell versione 13.4.0 o successiva introduce l'opzione ValidationLevel per determinare in che modo ARM convalida accuratamente il modello Bicep durante questo processo. Per altre informazioni, vedere Comandi di simulazione

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

Installation

Per usare la simulazione nell'interfaccia della riga di comando di Azure, devi 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.

Limitazioni

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.

Corto circuito

L'operazione di simulazione nelle distribuzioni Bicep può riscontrare un "corto circuito", uno scenario in cui il servizio non può analizzare completamente un modulo o una risorsa a causa della struttura o delle dipendenze della distribuzione dallo stato esterno. Il corto circuito di una singola risorsa si verifica quando l'ID risorsa o la versione dell'API non può essere calcolata all'esterno del contesto di distribuzione, spesso a causa di espressioni non risolte o dipendenze esterne. Per altre informazioni, vedere Espressioni non valutate. Anche se raro, il corto circuito dei moduli o delle risorse di distribuzione annidata può verificarsi, determinando l'esclusione di tutte le risorse all'interno del modulo dai risultati dell'analisi di simulazione. In questi casi, la risposta dell'API include un messaggio di diagnostica per indicare il problema.

Esecuzione dell'operazione di simulazione

L'uso di una versione recente del modulo Az PowerShell (13.1.0 o versione successiva) o dell'interfaccia della riga di comando di Azure (2.75.0 o versione successiva) fornirà la diagnostica quando il componente di simulazione non è in grado di analizzare parte della distribuzione. Le versioni precedenti di questi strumenti si comportano allo stesso modo, ma non visualizzano la diagnostica. Ad esempio, se si usa l'interfaccia della riga di comando versione 2.74.0, il problema si verifica ancora, ma si verifica in modo invisibile all'utente.

Comandi di simulazione

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

L'interfaccia della riga di comando di Azure versione 2.76.0 o successiva introduce l'opzione --validation-level per determinare in che modo ARM convalida accuratamente il modello Bicep durante questo processo. Accetta i valori seguenti:

  • Provider (impostazione predefinita): esegue la convalida completa, inclusa la sintassi del modello, le definizioni delle risorse, le dipendenze e i controlli delle autorizzazioni per assicurarsi di disporre di autorizzazioni sufficienti per distribuire tutte le risorse nel modello.
  • ProviderNoRbac: esegue la convalida completa del modello e delle risorse, simile al provider, ma controlla solo le autorizzazioni di lettura per ogni risorsa anziché le autorizzazioni di distribuzione complete. Ciò è utile quando si desidera convalidare le configurazioni delle risorse senza richiedere l'accesso completo.
  • Modello: esegue solo la convalida statica, verifica la sintassi e la struttura del modello ignorando i controlli preliminari (ad esempio, disponibilità delle risorse) e controlli delle autorizzazioni. Si tratta di problemi meno accurati e potenzialmente mancanti che potrebbero causare errori di distribuzione.

Puoi 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 puoi controllare a livello di codice per verificare la presenza di modifiche, usa 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, apri il file di configurazione interfaccia della riga di comando di Azure. Imposta no_color su Sì.

Per l'API REST, usa:

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

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. Salvare il file Bicep seguente come 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'
        }
      }
    ]
  }
}

Per distribuire il file Bicep, usare:

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

Testare la modifica

Al termine della distribuzione, è possibile testare l'operazione di simulazione. Questa volta si distribuisce un file Bicep che modifica la rete virtuale. Rispetto all'esempio precedente, nell'esempio seguente viene ignorato uno dei tag originali, è stata rimossa una subnet e il prefisso dell'indirizzo è stato modificato. Salvare il file Bicep seguente come 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'
        }
      }
    ]
  }
}

Per visualizzare le modifiche, usare:

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

L'output della simulazione è simile a:

Output dell'operazione di simulazione della distribuzione Bicep

L'output di testo è:

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.

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.

Confermare l'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.

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

Distribuzione Bicep - Modalità di distribuzione dell'output dell'operazione di simulazione completata

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

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

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=$(az deployment group what-if --resource-group ExampleGroup --template-file "what-if-after.bicep" --no-pretty-print)

Informazioni sui risultati di simulazione

Visualizza risultati

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

Distribuzione Bicep operazione di simulazione fullresourcepayload e tipi di modifica

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.

Note

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.

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. Vedi 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à è di sola lettura 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. Sono disponibili due opzioni:

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

Il valore predefinito è FullResourcePayloads.

Per i comandi di distribuzione di PowerShell, usa 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.

Espressioni non valutate

Se nell'output viene visualizzata un'espressione non valutata, significa che non è possibile valutarla all'esterno del contesto di una distribuzione. L'espressione viene mostrata così com'è per indicare le informazioni che verranno inserite quando verrà eseguita la distribuzione.

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

Nell'esempio precedente il parametro now usa la funzione utcNow() per ottenere la data e l'ora correnti. Quando si esegue la simulazione, queste espressioni vengono visualizzate così come sono perché non possono essere valutate all'esterno del contesto di una distribuzione. L'output di simulazione sarà simile al seguente:

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.

Le espressioni seguenti non vengono valutate durante le operazioni di simulazione:

  • Funzioni non deterministiche, ad esempio newGuid() e utcNow()
  • Qualsiasi riferimento a un valore di parametro sicuro.
  • Riferimenti alle risorse non distribuite nello stesso modello.
  • Riferimenti alle proprietà delle risorse non definite nello stesso modello.
  • Qualsiasi funzione di risorsa, ad esempio listKeys().

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

Passaggi successivi

  • Last updated on