Hvad er installationsscripts?

5 minutter

I dette undermodul får du mere at vide om, hvordan deploymentScripts ressource kan udvide Skabeloner til Azure Resource Manager (ARM).

ARM-skabeloner er vidunderlige ting. Du kan bruge dem til at deklarere den ønskede tilstand af din cloudinfrastruktur og lade API'erne og tjenesterne finde ud af, hvordan du kommer dertil. Du har dog nogle gange brug for at udføre handlinger, der ligger uden for det, som Azure Resource Manager leverer.

Hvad er installationsscripts?

deploymentScripts ressourcer er enten PowerShell- eller Bash-scripts, der kører i en Docker-objektbeholder som en del af din skabeloninstallation. Standardobjektbeholderbillederne har enten Azure CLI eller Azure PowerShell tilgængelige. Disse scripts kører under behandlingen af ARM-skabelonen, så du kan føje brugerdefineret funktionsmåde til installationsprocessen.

Udrulningsscripts bruger en administreret identitet til at godkende i Azure. En administreret identitet er en tjenesteprincipal, hvis legitimationsoplysninger og livscyklus administreres af Azure-platformen. Denne identitet er det, som Azure PowerShell- eller Azure CLI-kommandoerne bruger til at reagere på miljøet. Da du tildeler identiteten, styrer du omfanget af, hvad en deploymentScripts ressource kan påvirke.

Den deploymentScripts ressource producerer output, som andre ressourcer i udrulningen kan bruge. Du kan derefter søge efter oplysninger fra et eksternt system eller levere data, der er baseret på miljøets aktuelle tilstand, for at påvirke resten af installationen.

Sådan fungerer installationsscripts

En deploymentScripts ressource bruger et brugerdefineret script (enten fra skabelonen eller URI'en) og muligvis nogle understøttende scripts og kører dem i en Azure-objektbeholderforekomst. Denne objektbeholderforekomst er tildelt den administrerede identitet, du angiver. Scripts og deres output gemmes i et filshare for en Azure Storage-konto.

Når udrulningen af skabelonen kører, kontrollerer den, om der findes en eksisterende deploymentScripts ressource i den målrettede ressourcegruppe. Hvis det er tilfældet, sammenlignes egenskaberne. Hvis alt stemmer overens, sker der ikke noget nyt. Hvis ressourcen ikke findes eller er blevet ændret, opretter Azure Resource Manager en ny objektbeholderforekomst og kører installationsscriptene i den pågældende objektbeholderforekomst. Alle definerede output sendes tilbage til Azure Resource Manager til brug senere i udrulningen.

Struktur for installationsscript

Hvis du vil føje en brugerdefineret funktionsmåde til en ARM-skabelon, skal du starte med den deploymentScripts ressource. Som minimum skal du angive almindelige oplysninger som f.eks.:

En name for den deploymentScripts ressource.
Værdierne type og apiVersion.
Den placering (location værdi), hvor de supplerende ressourcer oprettes.
Et tomt properties objekt. Det kommer du snart til.

Der kræves to deploymentScripts-specifikke værdier:

kind: Den scripttype, der skal køres (enten 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 administrerede identitet, som objektbeholderforekomsten bruger. Du kan oprette den administrerede identitet på forhånd og angive den som i følgende eksempel, eller du kan oprette den i skabelonen og referere til den der (hvilket er det, du skal gøre i den næste øvelse).

{
  "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 angivet disse elementer, kan du flytte til afsnittet properties i deploymentScripts ressourcen. Hoveddelen af dette er scriptContent, som angiver det faktiske script, der skal udføres:

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

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

Bemærk, at scriptContent bruger en streng med flere linjer. I Bicep kan du angive en streng med flere linjer ved hjælp af tre anførselstegn sammen (''') før og efter strengen.

Det er almindeligt, at et installationsscript sender output tilbage til installationen. Hvis du f.eks. bruger et script til at søge efter nogle oplysninger fra en API, kan du sende oplysningerne tilbage til installationen som et output. Andre ressourcer i installationen kan derefter bruge oplysningerne i deres egne definitioner.

I forbindelse med et PowerShell-script sender du output tilbage ved at oprette en variabel med navnet $DeploymentScriptOutputs, som skal være en hashtabel. Eksempelscriptet initialiserer hashtabellen og opretter derefter et output kaldet text, som henter værdien fra den $output lokale variabel:

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

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

Drikkepenge

Du kan også skrive installationsscripts i Bash. Hvis du vil oprette output fra et Bash-script, skal du oprette en JSON-fil på en placering, der er angivet af miljøvariablen AZ_SCRIPTS_OUTPUT_PATH.

I afsnittet properties definerer du også de forskellige indstillinger, som deploymentScripts kan tage. I dette modul holder vi det enkelt og tilføjer lige nok til at få scriptet til at køre. Du skal som minimum angive den version af Azure PowerShell eller Azure CLI, der skal bruges, et script, der skal køres, og et opbevaringsinterval.

Opbevaringsintervallet er, hvor længe resultaterne skal bevares, hvis du vil beholde ressourcerne. Resultaterne fjernes som standard, når du har kørt scriptet.

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

Vores fulde skabelon ser nogenlunde sådan ud:

{
  "$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

Medtag scriptfiler

Integrering af scripts indbygget i skabeloner kan være besværligt, svært at læse og forstå og svært at ændre. Bicep bruger funktionen loadTextContent() til at integrere en ekstern tekstfil i installationen. Når Bicep oversætter din skabelon til JSON, integreres den eksterne fil i den skabelon, den udsender.

Lad os antage, at du har en PowerShell-fil med navnet myscript.ps1 i den samme mappe som din Bicep-skabelon. Du kan bede Bicep om at integrere filen på følgende måde:

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

Du kan finde alle egenskaberne for den deploymentScripts ressource i dokumentationen til ARM-skabelonreference.

Hvad er installationsscripts?