Använda distributionsskript för att kontrollera resursegenskaper

Den här artikeln beskriver hur du använder Bicep och ett distributionsskript för att pausa en distribution tills en resursegenskap returnerar ett specifikt värde. Du kan använda den här tekniken för att säkerställa att en distribution lyckas om den distribuerade resursen rapporterar till Azure Resource Manager att den är klar, men de underliggande resurserna inte är det. I det här fallet är den distribuerade resursen ännu inte redo att interagera med resten av distributionen, vilket innebär att en paus krävs.

Den här artikeln använder ett Azure Virtual WAN scenario för att demonstrera tekniken. Följande filer innehåller en resurskontroll och pausar implementeringen:

• orchestration.bicep
• azResourceStateCheck.bicep
• Invoke-AzResourceStateCheck.ps1

Du kan anpassa filerna för distributionen. För att hjälpa dig parametriseras modulen azResourceStateCheck.bicep. Egenskapen dependsOn används i orchestration.bicep för att säkerställa att distributionen av vwanvhcs.bicep-modulen är beroende av distributionen av modulen azResourceStateCheck.bicep.

Architecture

Diagram som visar distributionsarkitekturen uppdelad i två huvudområden. På vänster sida visas de Azure resurser som skapats inom en prenumerationsgräns. Gränsen innehåller en resursgrupp som innehåller Azure Virtual WAN. Virtual WAN innehåller en virtuell hubb, tre virtuella nätverk med undernät, virtuella hubbanslutningar och en användartilldelad hanterad identitet med en Azure rollbaserad åtkomstkontroll (Azure RBAC) Reader-rolltilldelning. Distributionsskriptresursen har en dubbelriktad anslutning till den användartilldelade hanterade identiteten och till de tre virtuella hubbanslutningarna, och den skickas till den virtuella hubben. Till höger visas Bicep modulfilstruktur, som innehåller orchestration.bicep, med anslutningar till modulmappen och till skriptmappen. Mappen modules innehåller vnet.bicep, vwan.bicep, vwanhub.bicep, vwanvhcs.bicep och azResourceStateCheck.bicep. Skriptmappen innehåller Invoke-AzResourceStateCheck.ps1.

Ladda ned en Visio-fil av den här arkitekturen.

Granska och ladda ned kodexemplen i GitHub för den här arkitekturen.

1. Skicka orchestration.bicep-filen för distribution till Resource Manager i prenumerationsomfånget.

   Note

   Du kan hämta den här Bicep filen och de andra filerna som används för det här exemplet från katalogen infra/samples/deployment-scripts-property-check. En partiell organisation av filerna på lagringsplatsen visas till höger i arkitekturdiagrammet.

2. Orchestration.bicep-filen skapar en resursgrupp i prenumerationsomfånget.

3. Orchestration.bicep-filen distribuerar Virtual WAN och de spoke-virtuella nätverken.

   • orchestration.bicep distribuerar modulen vwan.bicep, som distribuerar Virtual WAN i resursgruppens omfång.

   • orchestration.bicep distribuerar modulen vnet.bicep som distribuerar de virtuella nätverken i resursgruppens omfång.

   De virtuella Virtual WAN- och ekernätverken distribueras parallellt eftersom Bicep betraktar dem som oberoende av varandra. Beroenden avgör implementeringsordningen i Bicep. En resurs distribueras innan någon resurs som är beroende av den. Mer information om resursberoenden i Bicep, inklusive explicita och implicita beroenden, finns i Resursberoenden i Bicep.

4. Orchestration.bicep-filen distribuerar modulen vwanhub.bicep som distribuerar Virtual WAN hubben i resursgruppens omfång. Hubben är implicit beroende av Virtual WAN, vilket innebär att hubbdistributionen sker först när Virtual WAN distributionen har slutförts.

5. Orchestration.bicep-filen distribuerar modulen azResourceStateCheck.bicep, som skapar en användartilldelad hanterad identitet och tilldelar Azure rollbaserade åtkomstkontroll (RBAC) Läsare-rollen till resursgruppen.

6. Modulen azResourceStateCheck.bicep distribuerar distributionsskriptresursen.

7. Distributionsskriptresursen använder den användartilldelade hanterade identiteten för Resource Manager autentisering. Resursen kör sedan PowerShell-distributionsskriptet Invoke-AzResourceStateCheck.ps1. Mer information om distributionsskript finns i Använda distributionsskript i Bicep.

   Skriptet avsöker egenskapen Virtual WAN hub routingState för att avgöra om värdet är Provisioned:

   1. Om egenskapsvärdet inte Provisionedär pausas skriptet under en varaktighet som anges av en parameteruppsättning i filen orchestration.bicep och skickas till modulen azResourceStateCheck.bicep. Skriptet kontrollerar sedan egenskapsvärdet routingState igen.

      Skriptet upprepar paus- och kontrollcykeln. En parameter i filen orchestration.bicep avgör det maximala antalet iterationer. Om egenskapsvärdet inte är Provisioned efter det maximala antalet iterationer genererar skriptet ett undantag och avslutar, vilket gör att resten av Bicep distribution stoppas och misslyckas.

   2. Om egenskapsvärdet är Provisionedavslutas distributionsskriptet med en lyckad kod (0).

8. Om distributionsskriptet lyckas distribuerar filen orchestration.bicep modulen vwanvhcs.bicep, som skapar anslutningarna mellan de virtuella ekernätverken och Virtual WAN hubben.

   Definitionen av modulen vwanvhcs.bicep som finns i orchestration.bicep har en dependsOn sats som gör att vwanvhcs.bicep uttryckligen beror på att modulen azResourceStateCheck.bicep har slutförts. Därför skapas anslutningarna endast om egenskapen routingState är Provisioned.

   Modulen vwanvhcs.bicep distribuerar Virtual WAN hubbanslutningar sekventiellt i stället för parallellt, eftersom parallell distribution inte stöds för en enda Virtual WAN hubb. För att ställa in batchstorleken på 1 använder modulen Bicep batchSize dekoratör, @batchSize(1). Den här dekoratören ser till att anslutningarna distribueras en i taget.

Scenarioinformation

De viktigaste delarna i den här arkitekturen är modulen azResourceStateCheck.bicep, som distribuerar distributionsskriptresursen och det associerade distributionsskriptet Invoke-AzResourceStateCheck.ps1, som är en PowerShell-fil. Modulen använder distributionsskriptet för att kontrollera värdet för en resursegenskap. I det här exemplet är resursen en Virtual WAN-hubb.

Du kan använda dependsOn för att göra en modul explicit beroende av en annan eftersom den här miljön distribueras från en enda fil som använder Bicep moduler. I det här exemplet dependsOn gör modulen vwanvhcs.bicep beroende av modulen azResourceStateCheck.bicep.

I följande utdrag från orchestration.bicep används dependsOn.

@description('The API version of the Azure Resource you need to use to check the state of a property.')
param parAzResourceApiVersion string = '2022-01-01'

@description('The property of the resource that you need to check. This is a property inside the `properties` bag of the resource that's captured from a GET call to the Resource ID.')
param parAzResourcePropertyToCheck string = 'routingState'

@description('The value of the property of the resource that you need to check.')
param parAzResourceDesiredState string = 'Provisioned'

@description('The duration that the deployment script waits between check or polling requests to check the property and its state, if it is not in its desired state. The duration defaults to `30` seconds.')
param parWaitInSecondsBetweenIterations int = 30

module modVWANHub 'modules/vwanHub.bicep' = {
  scope: rsg
  name: 'deployVWANHub'
  params: {
    region: region
    regionNamePrefix: regionNamePrefix
    defaultTags: defaultTags
    vwanHubCIDR: vwanHubCIDR
    vwanName: modVWAN.outputs.vwanName
  }
}

module modVWANHubRouterCheckerDeploymentScript 'modules/azResourceStateCheck.bicep' = {
  scope: rsg
  name: 'deployVWANHubRouterChecker'
  params: {
    parLocation: region
    parAzResourceId: modVWANHub.outputs.outVwanVHubId
    parAzResourceApiVersion: parAzResourceApiVersion
    parAzResourcePropertyToCheck: parAzResourcePropertyToCheck
    parAzResourceDesiredState: parAzResourceDesiredState
    parMaxIterations: parMaxIterations
    parWaitInSecondsBetweenIterations: parWaitInSecondsBetweenIterations
  }
}

module modVWanVhubVnetConnections 'modules/vwanVhcs.bicep' = {
  dependsOn: [
    modVWANHubRouterCheckerDeploymentScript
  ]
  scope: rsg
  name: 'deployConnectVnetsToVWANVHub'
  params: {
    vnets: vnets
    regionNamePrefix: regionNamePrefix
  }
}

Resurskontrollen krävs eftersom distribuerade Virtual WAN hubbar inte är redo att användas förrän egenskapen routingState har värdet Provisioned. Virtual WAN hubbar rapporterar lyckad distribution till Resource Manager så att distributionsmotorn fortsätter distributionen. En ny Virtual WAN-hubb tas i drift efter att Virtual WAN-hubbroutern har installerats i den skapade hubben. Den här processen tar cirka 15 minuter. Det här beteendet visas i följande skärmbild av en ny Virtual WAN hubb. Skärmbilden visar en hubbstatus för Succeeded men en routningsstatus för Provisioning.

Om du försöker distribuera modulen vwanvhcs.bicep innan routingState värdet är Provisionedmisslyckas anslutningen och den övergripande distributionen misslyckas. Tills routern har provisionerats misslyckas även försöken att omdistribuera.

Följande skärmbild visar ett exempel på distributionsskriptloggen under routingState kontroller av Virtual WAN hubben. Loggen visar upprepade kontroller av egenskapen som returnerar ett annat värde än Provisioned.

Följande skärmbild visar att värdet ändras till Provisioned.

Om värdet inte ändras till Provisioned efter det maximala antalet iterationer genererar skriptet ett undantag, vilket signalerar skriptresursens fel till Resource Manager. Den Resource Manager distributionsmotorn misslyckas och stoppar distributionen eftersom undantaget tyder på att det finns ett problem med den Azure resurs som kräver felsökning. Mer information finns i följande Invoke-AzResourceStateCheck.ps1 skript.

[CmdletBinding()]
param (
  [string]
  $azResourceResourceId,

  [string]
  $apiVersion = "2022-05-01",

  [string]
  $azResourcePropertyToCheck = "provisioningState",

  [string]
  $azResourceDesiredState = "Provisioned",

  [int]
  $waitInSecondsBetweenIterations = 30,

  [int]
  $maxIterations = 30
)

$totalTimeoutCalculation = $waitInSecondsBetweenIterations * $maxIterations

$azResourcePropertyExistenceCheck = Invoke-AzRestMethod -Method GET -Path "$($azResourceResourceId)?api-version=$($apiVersion)"

if ($azResourcePropertyExistenceCheck.StatusCode -ne "200") {
  $DeploymentScriptOutputs["azResourcePropertyState"] = "Not Found"
  throw "Unable to get Azure Resource - $($azResourceResourceId). Likely it doesn't exist. Status code: $($azResourcePropertyExistenceCheck.StatusCode) Error: $($azResourcePropertyExistenceCheck.Content)"
}

$azResourcePropertyStateResult = "Unknown"
$iterationCount = 0

do {
  $azResourcePropertyStateGet = Invoke-AzRestMethod -Method GET -Path "$($azResourceResourceId)?api-version=$($apiVersion)"
  $azResourcePropertyStateJsonConverted = $azResourcePropertyStateGet.Content | ConvertFrom-Json -Depth 10
  $azResourcePropertyStateResult = $azResourcePropertyStateJsonConverted.properties.$($azResourcePropertyToCheck)

  if ($azResourcePropertyStateResult -ne $azResourceDesiredState) {
    Write-Host "Azure Resource Property ($($azResourcePropertyToCheck)) is not in $($azResourceDesiredState) state. Waiting $($waitInSecondsBetweenIterations) seconds before checking again. Iteration count: $($iterationCount)"
    Start-Sleep -Seconds $waitInSecondsBetweenIterations
    $iterationCount++
  }
} while (
  $azResourcePropertyStateResult -ne $azResourceDesiredState -and $iterationCount -ne $maxIterations
)

if ($azResourcePropertyStateResult -eq $azResourceDesiredState) {
  Write-Host "Azure Resource Property ($($azResourcePropertyToCheck)) is now in $($azResourceDesiredState) state."
  $DeploymentScriptOutputs["azResourcePropertyState"] = "$($azResourceDesiredState)"
}

if ($iterationCount -eq $maxIterations -and $azResourcePropertyStateResult -ne $azResourceDesiredState) {
  $DeploymentScriptOutputs["azResourcePropertyState"] = "Azure Resource Property ($($azResourcePropertyToCheck)) is still not in desired state of $($azResourceDesiredState). Timeout reached of $($totalTimeoutCalculation) seconds."
  throw "Azure Resource Property ($($azResourcePropertyToCheck)) is still not in $($azResourceDesiredState) state after $($totalTimeoutCalculation) seconds."
}

Contributors

Microsoft ansvarar för den här artikeln. Följande bidragsgivare skrev den här artikeln.

Huvudförfattare:

• Jack Tracey | Senior molnlösningsarkitekt

Annan deltagare:

• Gary McMahon - Sverige | Senior arkitekt för molnlösningar

Om du vill se linkedin-profiler som inte är offentliga loggar du in på LinkedIn.

Nästa steg

• Filer för exemplet i Azure/CAE-Bits-förvaret
• Använda distributionsskript i Bicep
• Learn-modul: Utöka Bicep- och ARM-mallar med hjälp av distributionsskript
• Allt du ville veta om undantag
• Migrera till Virtual WAN
• Resursberoenden i Bicep
• Dokumentation om Bicep

Relaterade resurser

• Nätverkstopologi för hub-spoke med Virtual WAN
• Arkitekturmetoder för distribution och konfiguration av lösningar för flera klientorganisationer
• Utveckling, säkerhet och åtgärder för infrastruktur som kod