Was sind Bereitstellungsskripts?

5 Minuten

In dieser Lerneinheit erfahren Sie, wie die deploymentScripts-Ressource Azure Resource Manager (ARM)-Vorlagen erweitern kann.

ARM-Vorlagen lassen sich hervorragend nutzen. Mit ihnen können sie den gewünschten Zustand Ihrer Cloudinfrastruktur deklarieren und die APIs und Dienste ermitteln lassen, wie Sie dorthin gelangen. Sie müssen jedoch gelegentlich Aktionen außerhalb des Leistungsumfangs von Azure Resource Manager ausführen.

Was sind Bereitstellungsskripts?

deploymentScripts-Ressourcen sind entweder PowerShell- oder Bash-Skripts, die im Rahmen Ihrer Vorlagenbereitstellung in einem Docker-Container ausgeführt werden. Für die Standardcontainerimages ist entweder die Azure CLI oder Azure PowerShell verfügbar. Diese Skripts werden während der Verarbeitung der ARM-Vorlage ausgeführt, sodass Sie dem Bereitstellungsprozess benutzerdefiniertes Verhalten hinzufügen können.

Bereitstellungsskripts verwenden eine verwaltete Identität für die Authentifizierung bei Azure. Eine verwaltete Identität ist ein Dienstprinzipal, dessen Anmeldeinformationen und Lebenszyklus von der Azure-Plattform verwaltet werden. Diese Identität wird von den Azure PowerShell- oder Azure CLI-Befehlen zur Ausführung von Aktionen für die Umgebung verwendet. Da Sie die Identität zuweisen, steuern Sie den Umfang, auf den sich eine deploymentScripts-Ressource auswirken kann.

Die deploymentScripts-Ressource erzeugt eine Ausgabe, die andere Ressourcen in der Bereitstellung verwenden können. Sie können dann Informationen aus einem externen System suchen oder Daten basierend auf dem aktuellen Zustand Ihrer Umgebung bereitstellen, um den Rest der Bereitstellung zu beeinflussen.

Funktionsweise von Bereitstellungsskripts

Eine deploymentScripts-Ressource verwendet ein vom Benutzer bereitgestelltes Skript (entweder aus der Vorlage oder per URI) und möglicherweise einige unterstützende Skripts und führt sie in einer Azure-Containerinstanz aus. Dieser Containerinstanz wird die verwaltete Identität zugewiesen, die Sie bereitstellen. Die Skripts und ihre Ausgabe werden in einer Dateifreigabe für ein Azure-Speicherkonto gespeichert.

Wenn die Vorlagenbereitstellung ausgeführt wird, wird überprüft, ob einedeploymentScripts-Ressource in der Zielressourcengruppe vorhanden ist. Wenn ja, werden die Eigenschaften verglichen. Wenn alles übereinstimmt, geschieht nichts Neues. Wenn die Ressource nicht vorhanden ist oder geändert wurde, erstellt Azure Resource Manager eine neue Containerinstanz und führt die Bereitstellungsskripts in dieser Containerinstanz aus. Jede definierte Ausgabe wird zur späteren Verwendung in der Bereitstellung an Azure Resource Manager übergeben.

Struktur des Bereitstellungsskripts

Zum Hinzufügen eines benutzerdefinierten Verhaltens zu einer ARM-Vorlage beginnen Sie mit der deploymentScripts-Ressource. Sie müssen mindestens allgemeine Details angeben, z. B.:

Ein name für die deploymentScripts-Ressource.
Die type- und apiVersion-Werte.
Der Ort (location-Wert), an dem die unterstützenden Ressourcen erstellt werden.
Ein leeres properties-Objekt. Darauf wird in Kürze eingegangen.

Zwei deploymentScripts-spezifische Werte sind erforderlich:

kind: Der Typ des auszuführenden Skripts (entweder AzurePowerShell oder 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: Die verwaltete Identität, die von der Containerinstanz verwendet wird. Sie können die verwaltete Identität im Voraus erstellen und wie im folgenden Beispiel angeben, oder sie in der Vorlage erstellen und dort darauf verweisen (was Sie in der nächsten Übung tun werden).

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

Nachdem Sie diese Elemente festgelegt haben, können Sie in den properties-Abschnitt der deploymentScripts-Ressource wechseln. Der Hauptteil davon ist scriptContent, der das auszuführende Skript angibt:

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

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

Beachten Sie, dass scriptContent eine mehrzeilige Zeichenfolge verwendet. In Bicep können Sie eine mehrzeilige Zeichenfolge angeben, indem Sie vor und nach Ihrer Zeichenfolge drei Anführungszeichen (''') verwenden.

Es ist üblich, dass ein Bereitstellungsskript Ausgaben zurück an die Bereitstellung übergibt. Wenn Sie beispielsweise ein Skript verwenden, um informationen aus einer API zu suchen, können Sie die Informationen als Ausgabe an die Bereitstellung zurückgeben. Andere Ressourcen in der Bereitstellung können dann die Informationen in ihren eigenen Definitionen verwenden.

Bei einem PowerShell-Skript übergeben Sie Ausgaben zurück, indem Sie eine Variable namens $DeploymentScriptOutputs erstellen, die eine Hashtabelle sein muss. Das Beispielskript initialisiert die Hashtabelle und erstellt dann eine Ausgabe namens text, die ihren Wert aus der lokalen Variablen $output übernimmt:

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

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

Tipp

Sie können auch Bereitstellungsskripts in Bash schreiben. Zum Erstellen von Ausgaben aus einem Bash-Skript müssen Sie eine JSON-Datei an einem Speicherort erstellen, der von der AZ_SCRIPTS_OUTPUT_PATH-Umgebungsvariablen angegeben wird.

Innerhalb des Abschnitts properties definieren Sie auch die verschiedenen Optionen, die von deploymentScripts genutzt werden können. In diesem Modul halten wir es einfach und fügen nur so viel hinzu, was zur Ausführung des Skripts notwendig ist. Sie müssen mindestens die Version von Azure PowerShell oder die zu verwendende Azure CLI, ein auszuführendes Skript und ein Aufbewahrungsintervall angeben.

Das Aufbewahrungsintervall gibt an, wie lange die Ergebnisse beibehalten werden sollen, wenn Sie die Ressourcen beibehalten möchten. Standardmäßig werden die Ergebnisse entfernt, nachdem Sie das Skript ausgeführt haben.

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

Unsere vollständige Vorlage sieht in etwa wie folgt aus:

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

Einschließen von Skriptdateien

Das Inlineeinbetten von Skripts in Vorlagen kann umständlich sein, und sie können schwer zu lesen und zu verstehen und schwierig zu ändern sein. Bicep verwendet die loadTextContent()-Funktion, um eine externe Textdatei in Ihre Bereitstellung einzubetten. Wenn Bicep Ihre Vorlage in JSON transpiliert, wird die externe Datei in die ausgegebene Vorlage eingebettet.

Angenommen, Sie verfügen über eine PowerShell-Datei mit dem Namen myscript.ps1 im selben Ordner wie Ihre Bicep-Vorlage. Sie können Bicep anweisen, die Datei wie folgt einzubetten:

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

Alle Eigenschaften für die deploymentScripts-Ressource finden Sie in der Referenzdokumentation zu ARM-Vorlagen.

Was sind Bereitstellungsskripts?