Vad är distributionsskript?

5 minuter

I den här lektionen får du lära dig hur resursen deploymentScripts kan utöka ARM-mallar (Azure Resource Manager).

ARM-mallar är underbara saker. Du kan använda dem för att deklarera önskat tillstånd för din molninfrastruktur och låta API:erna och tjänsterna ta reda på hur du tar dig dit. Ibland måste du dock utföra åtgärder som ligger utanför vad Azure Resource Manager tillhandahåller.

Vad är distributionsskript?

deploymentScripts resurser är antingen PowerShell- eller Bash-skript som körs i en Docker-container som en del av malldistributionen. Standardcontaineravbildningarna har antingen Azure CLI eller Azure PowerShell tillgängliga. Dessa skript körs under ARM-mallbearbetningen, så att du kan lägga till anpassat beteende i distributionsprocessen.

Distributionsskript använder en hanterad identitet för att autentisera till Azure. En hanterad identitet är ett huvudnamn för tjänsten vars autentiseringsuppgifter och livscykel hanteras av Azure-plattformen. Den här identiteten är vad Azure PowerShell- eller Azure CLI-kommandona använder för att agera i miljön. Eftersom du tilldelar identiteten styr du omfånget för vad en deploymentScripts resurs kan påverka.

Resursen deploymentScripts genererar utdata som andra resurser i distributionen kan använda. Du kan sedan söka efter information från ett externt system eller ange data baserat på miljöns aktuella tillstånd för att påverka resten av distributionen.

Så här fungerar distributionsskript

En deploymentScripts resurs tar ett användarangivet skript (antingen från mallen eller via URI) och eventuellt några stödskript och kör dem i en Azure-containerinstans. Containerinstansen tilldelas den hanterade identitet som du anger. Skripten och deras utdata lagras i en filresurs för ett Azure Storage-konto.

När malldistributionen körs kontrollerar den om det finns en befintlig deploymentScripts resurs i målresursgruppen. I så fall jämförs egenskaperna. Om allt matchar händer inget nytt. Om resursen inte finns eller har ändrats skapar Azure Resource Manager en ny containerinstans och kör distributionsskripten i containerinstansen. Alla definierade utdata skickas tillbaka till Azure Resource Manager för användning senare i distributionen.

Distributionsskriptstruktur

Om du vill lägga till ett anpassat beteende i en ARM-mall börjar du med resursen deploymentScripts . Du måste minst ange gemensam information som:

A name för resursen deploymentScripts .
Värdena type och apiVersion .
Platsen (location värdet) där de stödresurser som ska skapas.
Ett tomt properties objekt. Du kommer snart till det.

Två deploymentScriptsspecifika värden krävs:

kind: Typ av skript som ska köras (antingen AzurePowerShell eller AzureCLI).

{
  "type": "Microsoft.Resources/deploymentScripts",
  "apiVersion": "2020-10-01",
  "name": "myFirstDeploymentScript",
  "location": "[resourceGroup().location]",
  "kind": "AzurePowerShell",
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourcegroups/deploymenttest/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myscriptingid": {}
    }
  }
}

resource myFirstDeploymentScript 'Microsoft.Resources/deploymentScripts@2020-10-01' = {
  name: 'myFirstDeploymentScript'
  location: resourceGroup().location
  kind: 'AzurePowerShell'
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourcegroups/deploymenttest/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myscriptingid': {}
    }
  }
}

identity: Den hanterade identitet som containerinstansen ska använda. Du kan skapa den hanterade identiteten i förväg och ange den som i följande exempel, eller så kan du skapa den i mallen och referera till den där (vilket är vad du ska göra i nästa övning).

{
  "type": "Microsoft.Resources/deploymentScripts",
  "apiVersion": "2020-10-01",
  "name": "myFirstDeploymentScript",
  "location": "[resourceGroup().location]",
  "kind": "AzurePowerShell",
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourcegroups/deploymenttest/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myscriptingid": {}
    }
  }
}

resource myFirstDeploymentScript 'Microsoft.Resources/deploymentScripts@2020-10-01' = {
  name: 'myFirstDeploymentScript'
  location: resourceGroup().location
  kind: 'AzurePowerShell'
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourcegroups/deploymenttest/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myscriptingid': {}
    }
  }
}

När du har angett dessa element kan du gå vidare till properties resursavsnittet deploymentScripts . Huvuddelen av detta är scriptContent, som anger det faktiska skriptet som ska köras:

"properties": {
  "scriptContent": "
      $output = 'Hello Learner!'
      Write-Output $output
      $DeploymentScriptOutputs = @{}
      $DeploymentScriptOutputs['text'] = $output
  ",
}

properties: {
  scriptContent: '''
    $output = 'Hello Learner!'
    Write-Output $output
    $DeploymentScriptOutputs = @{}
    $DeploymentScriptOutputs['text'] = $output
  '''
}

Observera att scriptContent använder en sträng med flera rader. I Bicep kan du ange en sträng med flera rader genom att använda tre citattecken tillsammans (''') före och efter strängen.

Det är vanligt att ett distributionsskript skickar utdata tillbaka till distributionen. Om du till exempel använder ett skript för att söka efter information från ett API kan du skicka tillbaka informationen till distributionen som utdata. Andra resurser i distributionen kan sedan använda informationen i sina egna definitioner.

För ett PowerShell-skript skickar du tillbaka utdata genom att skapa en variabel med namnet $DeploymentScriptOutputs, som måste vara en hash-tabell. Exempelskriptet initierar hash-tabellen och skapar sedan utdata med namnet text, som tar dess värde från den $output lokala variabeln:

$output = 'Hello Learner!'
Write-Output $output
$DeploymentScriptOutputs = @{}
$DeploymentScriptOutputs['text'] = $output

$output = 'Hello Learner!'
Write-Output $output
$DeploymentScriptOutputs = @{}
$DeploymentScriptOutputs['text'] = $output

Dricks

Du kan också skriva distributionsskript i Bash. Om du vill skapa utdata från ett Bash-skript måste du skapa en JSON-fil på en plats som anges av AZ_SCRIPTS_OUTPUT_PATH miljövariabeln.

I avsnittet properties definierar du också de olika alternativ som deploymentScripts kan användas. I den här modulen ska vi hålla det enkelt och lägga till tillräckligt för att få skriptet att köras. Du måste minst ange den version av Azure PowerShell eller Azure CLI som ska användas, ett skript som ska köras och ett kvarhållningsintervall.

Kvarhållningsintervallet är hur länge resultatet ska behållas om du vill behålla resurserna. Som standard tas resultatet bort när du har kört skriptet.

"properties": {
  "azPowerShellVersion": "3.0",
  "scriptContent": "
      $output = 'Hello Learner!'
      Write-Output $output
      $DeploymentScriptOutputs = @{}
      $DeploymentScriptOutputs['text'] = $output
  ",
  "retentionInterval": "P1D"
}

properties: {
  azPowerShellVersion: '3.0'
  scriptContent: '''
    $output = 'Hello Learner!'
    Write-Output $output
    $DeploymentScriptOutputs = @{}
    $DeploymentScriptOutputs['text'] = $output
  '''
  retentionInterval: 'P1D'
}

Vår fullständiga mall skulle se ut ungefär så här:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.1",
  "apiProfile": "",
  "parameters": {},
  "variables": {},
  "functions": [],
  "resources": [
    {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2020-10-01",
      "name": "myFirstDeploymentScript",
      "location": "[resourceGroup().location]",
      "kind": "AzurePowerShell",
      "identity": {
        "type": "UserAssigned",
        "userAssignedIdentities": {
          "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourcegroups/deploymenttest/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myscriptingid": {}
        }
      },
      "properties": {
        "azPowerShellVersion": "3.0",
        "scriptContent": "
            $output = 'Hello Learner!'
            Write-Output $output
            $DeploymentScriptOutputs = @{}
            $DeploymentScriptOutputs['text'] = $output
        ",
        "retentionInterval": "P1D"
      }
    }
  ],
  "outputs": {
    "scriptResult": {
      "type": "string",
      "value": "[reference('myFirstDeploymentScript').outputs.text]"
    }
  }
}

resource myFirstDeploymentScript 'Microsoft.Resources/deploymentScripts@2020-10-01' = {
  name: 'myFirstDeploymentScript'
  location: resourceGroup().location
  kind: 'AzurePowerShell'
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourcegroups/deploymenttest/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myscriptingid': {}
    }
  }
  properties: {
    azPowerShellVersion: '3.0'
    scriptContent: '''
      $output = 'Hello Learner!'
      Write-Output $output
      $DeploymentScriptOutputs = @{}
      $DeploymentScriptOutputs['text'] = $output
    '''
    retentionInterval: 'P1D'
  }
}

output scriptResult string = myFirstDeploymentScript.properties.outputs.text

Inkludera skriptfiler

Inbäddning av skript infogade i mallar kan vara besvärligt, svårt att läsa och förstå och svårt att ändra. Bicep använder loadTextContent() funktionen för att bädda in en extern textfil i distributionen. När Bicep överför mallen till JSON bäddas den externa filen in i mallen som den genererar.

Anta att du har en PowerShell-fil med namnet myscript.ps1 i samma mapp som din Bicep-mall. Du kan be Bicep att bädda in filen så här:

properties: {
  azPowerShellVersion: '3.0'
  scriptContent: loadTextContent('myscript.ps1')
  retentionInterval: 'P1D'
}

Du hittar alla egenskaper för resursen deploymentScripts i referensdokumentationen för ARM-mallen.

Vad är distributionsskript?