Dela via

Bicep What-If: Förhandsversionsändringar före distribution

Innan du distribuerar en Bicep-fil kan du förhandsgranska de ändringar som kommer att ske. Azure Resource Manager (ARM) tillhandahåller konsekvensåtgärden så att du kan se hur resurserna ändras om du distribuerar Bicep-filen. Tänk om-operationen gör inga ändringar på befintliga resurser. I stället förutsäger den ändringarna om den angivna Bicep-filen distribueras.

Du kan använda konsekvensåtgärden med Visual Studio Code-, Azure PowerShell-, Azure CLI- eller REST API-åtgärder. What-if stöds för distributioner på resursgrupp, prenumeration, hanteringsgrupp och klientorganisationsnivå.

Under Vad-om-operationer stöds inte utvärdering och expansion av templateLink. Det innebär att alla resurser som distribueras med hjälp av malllänkar i kapslade distributioner, inklusive mallspecifikationsreferenser, inte visas i resultatet av åtgärden What-If.

Förutsättningar

Behörigheter som krävs

För att distribuera en Bicep-fil eller EN ARM-mall (Azure Resource Manager) behöver du skrivåtkomst till de resurser som du distribuerar och åtkomst till alla åtgärder i Microsoft.Resources/deployments resurstypen. Om du till exempel vill distribuera en virtuell dator behöver du Microsoft.Compute/virtualMachines/write och Microsoft.Resources/deployments/* behörigheter. What-if-operationen har samma behörighetskrav.

Azure CLI version 2.76.0 eller senare och Azure PowerShell version 13.4.0 eller senare introducerar ValidationLevel-växeln för att fastställa hur noggrant ARM validerar Bicep-mallen under den här processen. Mer information finns i What-if-kommandon

Det finns en lista med roller och behörigheter i Inbyggda roller i Azure.

Installation

Om du vill använda konsekvens i Azure CLI måste du ha Azure CLI 2.14.0 eller senare. Installera den senaste versionen av Azure CLI om det behövs.

Begränsningar

What-if expanderar kapslade mallar tills dessa gränser har nåtts:

  • 500 kapslade mallar.
  • 800 resursgrupper i en distribution över resursgrupper.
  • 5 minuter för att expandera de kapslade mallarna.

När en av gränserna har nåtts är de återstående resursernas ändringstyp inställd på Ignorera.

Kortslutning

Vad-händer-om operationen i Bicep-distributioner kan stöta på "snabbavbrott", ett scenario där tjänsten inte helt kan analysera en modul eller resurs på grund av distributionens struktur eller beroenden på extern tillstånd. Kortslutning av en enskild resurs sker när dess resurs-ID eller API-version inte kan beräknas utanför distributionskontexten, ofta på grund av olösta uttryck eller externa beroenden. Mer information finns i Ej värderade uttryck. Även om det är ovanligt kan kortslutning av moduler eller kapslade distributionsresurser också ske, vilket resulterar i att alla resurser i modulen undantas från resultatet av konsekvensanalysen. I sådana fall innehåller API-svaret ett diagnostikmeddelande som anger problemet.

Köra konsekvensåtgärden

Om du använder en ny version av Az PowerShell-modulen (13.1.0 eller senare) eller Azure CLI (2.75.0 eller senare) får du diagnostik när det inte går att analysera en del av distributionen. Tidigare versioner av dessa verktyg fungerar på samma sätt, men de visar inte diagnostiken. Om du till exempel använder CLI version 2.74.0 uppstår problemet fortfarande – det sker bara tyst.

Hypotetiska kommandon

Om du vill förhandsgranska ändringar innan du distribuerar en Bicep-fil använder du:

Azure CLI version 2.76.0 eller senare introducerar växeln --validation-level för att fastställa hur noggrant ARM validerar Bicep-mallen under den här processen. Den accepterar följande värden:

  • Provider (standard): Utför fullständig validering, inklusive mallsyntax, resursdefinitioner, beroenden och behörighetskontroller för att säkerställa att du har tillräcklig behörighet för att distribuera alla resurser i mallen.
  • ProviderNoRbac: Utför fullständig validering av mallen och resurserna, ungefär som Provider, men söker bara efter läsbehörigheter för varje resurs i stället för fullständiga distributionsbehörigheter. Detta är användbart när du vill verifiera resurskonfigurationer utan att kräva fullständig åtkomst.
  • Mall: Utför endast statisk validering, kontrollerar mallsyntaxen och strukturen medan du hoppar över förinställda kontroller (t.ex. resurstillgänglighet) och behörighetskontroller. Det här är mindre omfattande, potentiellt saknade problem som kan orsaka distributionsfel.

Du kan använda växeln --confirm-with-what-if (eller dess korta formulär -c) för att förhandsgranska ändringarna och uppmanas att fortsätta med distributionen. Lägg till den här växeln till:

Du kan till exempel använda az deployment group create --confirm-with-what-if eller -c för resursgruppsdistributioner.

Föregående kommandon returnerar en textsammanfattning som du kan granska manuellt. Om du vill hämta ett JSON-objekt som du programmatiskt kan kontrollera efter ändringar använder du växeln --no-pretty-print . Du kan till exempel använda az deployment group what-if --no-pretty-print för resursgruppsdistributioner.

Om du vill returnera resultatet utan färger öppnar du Azure CLI-konfigurationsfilen . Ställ in no_color på Ja.

För REST API använder du:

Du kan använda konsekvensåtgärden via Azure SDK:er.

Konfigurera miljö

Om du vill se hur "what-if"-scenarier fungerar, låt oss köra några tester. Distribuera först en Bicep-fil som skapar ett virtuellt nätverk. Spara följande Bicep-fil som 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'
        }
      }
    ]
  }
}

Om du vill distribuera Bicep-filen använder du:

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

Teständring

När distributionen är klar är du redo att testa "vad händer om"-operationen. Den här gången distribuerar du en Bicep-fil som ändrar det virtuella nätverket. Om du jämför med föregående exempel missar följande exempel en av de ursprungliga taggarna, ett undernät har tagits bort och adressprefixet har ändrats. Spara följande Bicep-fil som 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'
        }
      }
    ]
  }
}

Om du vill visa ändringarna använder du:

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

Utdata för hypotetiska scenarier ser ut ungefär så här:

Utdata för Bicep-distribution – hypotetisk åtgärd

Textutdata är:

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.

Observera överst i utdata att färger har definierats för att ange typ av ändringar.

Längst ned i utdata visas taggen Ägare har tagits bort. Adressprefixet ändrades från 10.0.0.0/16 till 10.0.0.0/15. Undernätet med namnet subnet001 togs bort. Kom ihåg att dessa ändringar inte har distribuerats. Du ser en förhandsgranskning av de ändringar som kommer att ske om du distribuerar Bicep-filen.

Vissa av de egenskaper som visas som borttagna ändras inte. Egenskaper kan rapporteras felaktigt som borttagna när de inte finns i Bicep-filen, men anges automatiskt under distributionen som standardvärden. Det här resultatet anses vara "brus" i konsekvenssvaret. Den sista distribuerade resursen har värdena inställda för egenskaperna. När vad-om-operationen mognar filtreras dessa egenskaper bort från resultatet.

Bekräfta borttagning

Om du vill förhandsgranska ändringar innan du distribuerar en Bicep-fil använder du parametern confirm switch med distributionskommandot. Om ändringarna är som förväntat svarar du att du vill att distributionen ska slutföras.

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

Distributionsläget för Bicep-distribution – konsekvens när åtgärdens utdata har slutförts

Textutdata är:

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

Du ser de förväntade ändringarna och kan bekräfta att du vill att distributionen ska köras.

Utvärdera hypotetiska resultat programmatiskt

Nu ska vi programmatiskt utvärdera vad-om-resultaten genom att tilldela kommandot till en variabel.

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

Förstå vad-händer-om-resultat

Visa resultat

När du använder what-if i PowerShell eller Azure CLI innehåller utdata färgkodade resultat som hjälper dig att se de olika typerna av ändringar.

Bicep-utrullning

Textutdata är:

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.

Kommentar

Simuleringsoperationen kan inte lösa referensfunktionen. Varje gång du anger en egenskap till ett malluttryck som innehåller referensfunktionen ändras konsekvensrapporter för egenskapen. Det här beteendet inträffar eftersom what-if jämför det nuvarande värdet av egenskapen (till exempel true eller false för ett booleskt värde) med det olösta malluttrycket. Det är uppenbart att dessa värden inte matchar. När du distribuerar Bicep-filen förändras egenskapen endast när uttrycket i mallen löses till ett annat värde.

Ändringstyper

Tänk om-operationen listar sju olika typer av förändringar.

  • Skapa: Resursen finns för närvarande inte men definieras i Bicep-filen. Resursen skapas.
  • Ta bort: Den här ändringstypen gäller endast när du använder fullständigt läge för JSON-malldistribution. Resursen finns, men definieras inte i Bicep-filen. I fullständigt läge tas resursen bort. Det är bara resurser med stöd för fullständigt borttagningsläge som ingår i den här ändringstypen.
  • Ignorera: Resursen finns men definieras inte i Bicep-filen. Resursen kommer inte att distribueras eller ändras. När du når gränserna för att expandera kapslade mallar visas den här ändringstypen. Se Vad händer om-gränser.
  • NoChange: Resursen finns och definieras i Bicep-filen. Resursen distribueras på nytt, men egenskaperna ändras inte. Den här ändringstypen returneras när ResultFormat är inställt på FullResourcePayloads, vilket är standardvärdet.
  • NoEffect: Egenskapen är endast klar och ignoreras av tjänsten. Till exempel är egenskapen sku.tier alltid inställd på att matcha sku.name i Microsoft.ServiceBus namnrymden.
  • Ändra: Resursen finns och definieras i Bicep-filen. Resursen distribueras på nytt och resursens egenskaper ändras. Den här ändringstypen returneras när ResultFormat är inställt på FullResourcePayloads, vilket är standardvärdet.
  • Distribuera: Resursen finns och definieras i Bicep-filen. Resursen distribueras på nytt. Egenskaperna för resursen kan förändras eller inte. Åtgärden returnerar den här ändringstypen när det inte finns tillräckligt med information för att avgöra om några egenskaper kommer att ändras. Du ser bara det här villkoret när ResultFormat är inställt på ResourceIdOnly.

Resultatformat

Du styr detaljnivån som returneras om de förutsagda ändringarna. Du har två alternativ:

  • FullResourcePayloads – returnerar en lista över resurser som kommer att ändras och information om de egenskaper som kommer att ändras
  • ResourceIdOnly – returnerar en lista över resurser som kommer att ändras

Standardvärdet är FullResourcePayloads.

Använd parametern för PowerShell-distributionskommandon -WhatIfResultFormat . Använd parametern i de programmatiska objektkommandona ResultFormat .

Använd --result-format-parametern för Azure CLI.

Följande resultat visar de två olika utdataformaten:

  • Fullständiga resursnyttolaster

    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.

  • Endast resurs-ID

    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.

Ej värderade uttryck

Om ett ovärderat uttryck visas i utdata innebär det att what-if inte kan utvärdera det utanför kontexten för en distribution. Uttrycket visas as-is för att ange den information som ska fyllas i när distributionen körs.

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

I föregående exempel använder parametern nowutcNow() funktionen för att hämta aktuellt datum och tid. När du kör what-if visas dessa uttryck as-is eftersom de inte kan utvärderas utanför kontexten för en distribution. Scenarioanalysutdata kommer att se ut ungefär så här:

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.

Följande uttryck utvärderas inte under konsekvensanalys:

  • Icke-deterministiska funktioner, till exempel newGuid() och utcNow()
  • Alla referenser till ett säkert parametervärde.
  • Referenser till resurser som inte distribueras i samma mall.
  • Referenser till resursegenskaper som inte har definierats i samma mall.
  • Alla resursfunktioner, till exempel listKeys().

Rensa resurser

När du inte längre behöver exempelresurserna använder du Azure CLI eller Azure PowerShell för att ta bort resursgruppen.

az group delete --name ExampleGroup

Nästa steg