Konsekvensåtgärd för Bicep-distribution

Innan du distribuerar en Bicep-fil kan du förhandsgranska de ändringar som kommer att ske. Azure Resource Manager tillhandahåller konsekvensåtgärden så att du kan se hur resurser ändras om du distribuerar Bicep-filen. Konsekvensgranskningen ändrar inga befintliga resurser. I stället förutsäger den ändringarna om den angivna Bicep-filen distribueras.

Du kan använda konsekvensåtgärden med åtgärder för Azure PowerShell, Azure CLI eller REST API. Konsekvenshantering stöds för distributioner på resursgrupps-, prenumerations-, hanteringsgrupp- och klientorganisationsnivå.

Under What-If åtgärder stöds inte utvärdering och utökning av templateLink . Därför visas inte resurser som distribueras med hjälp av malllänkar i kapslade distributioner, inklusive mallspecifikationsreferenser, i What-If åtgärdsresultat.

Träningsresurser

Om du hellre vill lära dig mer om konsekvensgranskningen via stegvisa anvisningar kan du läsa Förhandsversion av Azure-distributionsändringar med hjälp av konsekvensgranskning.

Behörigheter som krävs

Om du vill distribuera en Bicep-fil eller en ARM-mall måste du ha skrivåtkomst till de resurser som du distribuerar och åtkomst till alla åtgärder i resurstypen Microsoft.Resources/deployments. Om du till exempel vill distribuera en virtuell dator behöver Microsoft.Compute/virtualMachines/write du och Microsoft.Resources/deployments/* behörigheter. Konsekvensåtgärden har samma behörighetskrav.

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

Konsekvensbegränsningar

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

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

När en av gränserna nås ställs de återstående resursernas ändringstyp in på Ignorera.

Installera Azure PowerShell modul

Om du vill använda konsekvens i PowerShell måste du ha version 4.2 eller senare av Az-modulen.

Om du vill installera modulen använder du:

Install-Module -Name Az -Force

Mer information om hur du installerar moduler finns i Installera Azure PowerShell.

Installera Azure CLI-modulen

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.

Visa resultat

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

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.

Anteckning

Konsekvensåtgärden kan inte matcha referensfunktionen. Varje gång du anger en egenskap till ett malluttryck som innehåller referensfunktionen ändras konsekvensrapporter för egenskapen. Det här beteendet beror på att konsekvensgranskning jämför det aktuella värdet för egenskapen (till exempel true eller false för ett booleskt värde) med det olösta malluttrycket. Dessa värden matchar uppenbarligen inte. När du distribuerar Bicep-filen ändras egenskapen bara när malluttrycket matchas till ett annat värde.

Konsekvenskommandon

Azure PowerShell

Om du vill förhandsgranska ändringar innan du distribuerar en Bicep-fil använder du New-AzResourceGroupDeployment eller New-AzSubscriptionDeployment. Lägg till växelparametern -Whatif i distributionskommandot.

• New-AzResourceGroupDeployment -Whatif för resursgruppsdistributioner
• New-AzSubscriptionDeployment -Whatif och New-AzDeployment -Whatif för distributioner på prenumerationsnivå

Du kan använda växelparametern -Confirm för att förhandsgranska ändringarna och uppmanas att fortsätta med distributionen.

• New-AzResourceGroupDeployment -Confirm för resursgruppsdistributioner
• New-AzSubscriptionDeployment -Confirm och New-AzDeployment -Confirm för distributioner på prenumerationsnivå

Föregående kommandon returnerar en textsammanfattning som du kan granska manuellt. Om du vill hämta ett objekt som du programmatiskt kan granska efter ändringar använder du Get-AzResourceGroupDeploymentWhatIfResult eller Get-AzSubscriptionDeploymentWhatIfResult.

• $results = Get-AzResourceGroupDeploymentWhatIfResult för resursgruppsdistributioner
• $results = Get-AzSubscriptionDeploymentWhatIfResult eller $results = Get-AzDeploymentWhatIfResult för distributioner på prenumerationsnivå

Azure CLI

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

• az deployment group what-if för resursgruppsdistributioner
• az deployment sub what-if för distributioner på prenumerationsnivå
• az deployment mg what-if för hanteringsgruppsdistributioner
• az deployment tenant what-if för klientdistributioner

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

• az deployment group create
• az deployment sub create.
• az deployment mg create
• az deployment tenant create

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. Använd växeln --no-pretty-print för att hämta ett JSON-objekt som du programmatiskt kan granska efter ändringar. Använd till exempel 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.

REST-API för Azure

För REST API använder du:

• Distributioner – Vad händer om för resursgruppsdistributioner
• Distributioner – Vad händer om prenumerationsomfånget för prenumerationsdistributioner
• Distributioner – Vad händer om vid hanteringsgruppsomfång för distributioner av hanteringsgrupper
• Distributioner – Vad händer om det finns klientorganisationsomfång för klientdistributioner.

Ändringstyper

Konsekvensåtgärden visar sju olika typer av ä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 distribution av JSON-mallar. Resursen finns men definieras inte i Bicep-filen. I fullständigt läge tas resursen bort. Endast resurser som stöder borttagning i fullständigt läge 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 Konsekvensbegränsningar.
• 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. Egenskapen är till exempel sku.tier alltid inställd på Microsoft.ServiceBus att matcha sku.name i namnområdet.
• Ä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 ändras eventuellt. Å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 kan välja mellan 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 parametern för --result-format 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.
  

Köra konsekvensåtgärd

Konfigurera miljö

Om du vill se hur konsekvens fungerar ska vi köra några tester. Distribuera först en Bicep-fil som skapar ett virtuellt nätverk. Du använder det här virtuella nätverket för att testa hur ändringar rapporteras med konsekvens. Ladda ned en kopia av Bicep-filen.

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

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

PowerShell

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

Azure CLI

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 konsekvensåtgärden. Den här gången distribuerar du en Bicep-fil som ändrar det virtuella nätverket. Den saknar en av de ursprungliga taggarna, ett undernät har tagits bort och adressprefixet har ändrats. Ladda ned en kopia av Bicep-filen.

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

Om du vill visa ändringarna använder du:

PowerShell

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

Azure CLI

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

Utdata från konsekvensgranskningen bör se ut ungefär så här:

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

Observera överst i utdata att färger har definierats för att ange typen 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 slutliga distribuerade resursen har värdena angivna för egenskaperna. När konsekvensåtgärden mognar filtreras dessa egenskaper bort från resultatet.

Utvärdera konsekvensresultat programmatiskt

Nu ska vi utvärdera konsekvensresultatet programmässigt genom att ställa in kommandot på en variabel.

PowerShell

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

Du kan se en sammanfattning av varje ändring.

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

Azure CLI

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

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.

PowerShell

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

Azure CLI

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

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

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

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.

CLI

az group delete --name ExampleGroup

PowerShell

Remove-AzResourceGroup -Name ExampleGroup

SDK:er

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

• För Python använder du konsekvens.

• För Java använder du DeploymentWhatIf Class.

• För .NET använder du DeploymentWhatIf Class.

Nästa steg

• Information om hur du använder konsekvensåtgärden i en pipeline finns i Testa ARM-mallar med What-If i en pipeline.
• Om du ser felaktiga resultat från konsekvensåtgärden kan du rapportera problemen på https://aka.ms/whatifissues.
• En Learn-modul som visar hur du använder what-if finns i Förhandsgranska ändringar och verifiera Azure-resurser med hjälp av what-if och testverktyget för ARM-mallar.