Teilen über

Verwenden von Bereitstellungsskripts in ARM-Vorlagen

  • Artikel

Hier wird beschrieben, wie Sie Bereitstellungsskripts in ARM-Vorlagen (Azure Resource Manager) verwenden. Mithilfe der deploymentScripts-Ressource können Benutzer*innen Skripts in ARM-Bereitstellungen ausführen und die Ausführungsergebnisse überprüfen.

Tipp

Wir empfehlen Bicep, weil es dieselben Funktionen wie ARM-Vorlagen bietet und die Syntax einfacher zu verwenden ist. Weitere Informationen finden Sie unter Bereitstellungsskript.

Diese Skripts können zum Ausführen benutzerdefinierter Schritte wie der folgenden verwendet werden:

  • Hinzufügen von Benutzern zu einem Verzeichnis
  • Ausführen von Vorgängen auf Datenebene (z. B. Kopieren von Blobs oder Ausführen von Datenbankseeding)
  • Suchen und Überprüfen eines Lizenzschlüssels
  • Erstellen Sie ein selbstsigniertes Zertifikat.
  • Erstellen Sie ein Objekt in Microsoft Entra ID.
  • Suchen von IP-Adressblöcken eines benutzerdefinierten Systems

Vorteile von Bereitstellungsskripts:

  • Einfach zu codieren, zu verwenden und zu debuggen. Sie können Bereitstellungsskripts in Ihren bevorzugten Entwicklungsumgebungen entwickeln. Die Skripts können in Vorlagen oder in externe Skriptdateien eingebettet werden.
  • Sie können die Skriptsprache und die Plattform angeben. Derzeit werden Azure PowerShell- und Azure CLI-Bereitstellungsskripts in der Linux-Umgebung unterstützt.
  • Sie können Befehlszeilenargumente an das Skript übergeben.
  • Sie können Skriptausgaben angeben und an die Bereitstellung zurückgeben.

Die Bereitstellungsskriptressource ist nur in den Regionen verfügbar, in denen Azure Container Instances verfügbar ist. Informationen dazu finden Sie unter Ressourcenverfügbarkeit für Azure Container Instances in Azure-Regionen. Derzeit verwendet das Bereitstellungsskript nur öffentliche Netzwerke.

Wichtig

Der Bereitstellungsskriptdienst erfordert zwei Unterstützungsressourcen für die Skriptausführung und Problembehandlung: ein Speicherkonto und eine Containerinstanz. Sie können ein vorhandenes Speicherkonto angeben, andernfalls erstellt der Skriptdienst eines für Sie. Die beiden automatisch erstellten Ressourcen zur Unterstützung werden normalerweise vom Skriptdienst gelöscht, wenn die Ausführung des Bereitstellungsskripts beendet ist. Die Unterstützungsressourcen werden Ihnen in Rechnung gestellt, bis sie gelöscht werden. Preisinformationen finden Sie unter Container Instances – Preise und Azure Storage – Preise. Weitere Informationen finden Sie unter Bereinigen von Bereitstellungsskriptressourcen.

Hinweis

Wiederholungslogik für die Azure-Anmeldung ist jetzt in das Wrapperskript integriert. Wenn Sie Berechtigungen in derselben Vorlage wie Ihre Bereitstellungsskripts erteilen, wiederholt der Bereitstellungsskriptdienst die Anmeldung 10 Minuten lang mit einem Intervall von 10 Sekunden, bis die Rollenzuweisung für verwaltete Identitäten repliziert wird.

Schulungsressourcen

Wenn Sie die Bereitstellungsskripts lieber anhand einer Schritt-für-Schritt-Anleitung kennenlernen möchten, lesen Sie Erweitern von ARM-Vorlagen mithilfe von Bereitstellungsskripts.

Konfigurieren der mindestens erforderlichen Berechtigungen

Für die Bereitstellungsskript-API-Version 2020-10-01 oder höher sind zwei Prinzipale an der Ausführung des Bereitstellungsskripts beteiligt:

  • Bereitstellungsprinzipal (dar zur Bereitstellung der Vorlage genutzte Prinzipal): Dieser Prinzipal wird verwendet, um zugrunde liegende Ressourcen, die für die Ausführung der Bereitstellungsskriptressource erforderlich sind – ein Speicherkonto und eine Azure-Containerinstanz zu erstellen. Weisen Sie dem Bereitstellungsprinzipal eine benutzerdefinierte Rolle mit den folgenden Eigenschaften zu, um die Berechtigungen mit den geringsten Rechten zu konfigurieren:

    {
  "roleName": "deployment-script-minimum-privilege-for-deployment-principal",
  "description": "Configure least privilege for the deployment principal in deployment script",
  "type": "customRole",
  "IsCustom": true,
  "permissions": [
    {
      "actions": [
        "Microsoft.Storage/storageAccounts/*",
        "Microsoft.ContainerInstance/containerGroups/*",
        "Microsoft.Resources/deployments/*",
        "Microsoft.Resources/deploymentScripts/*"
      ],
    }
  ],
  "assignableScopes": [
    "[subscription().id]"
  ]
}

    Wenn die Azure Storage- und die Azure Container Instance-Ressourcenanbieter nicht registriert sind, müssen Sie auch Microsoft.Storage/register/action und Microsoft.ContainerInstance/register/action hinzufügen.

  • Bereitstellungsskriptprinzipal: Dieser Prinzipal ist nur erforderlich, wenn sich das Bereitstellungsskript bei Azure authentifizieren und Azure CLI PowerShell aufrufen muss. Es gibt zwei Möglichkeiten, den Bereitstellungsskriptprinzipal anzugeben:

    • Spezifizieren Sie eine benutzerseitig zugewiesene verwaltete Identität in der identity Eigenschaft (siehe Stichprobenvorlagen). Wenn angegeben, ruft der Skriptdienst Connect-AzAccount -Identity auf, bevor das Bereitstellungsskript aufruft. Die verwaltete Identität muss über den erforderlichen Zugriff verfügen, um den Vorgang im Skript abzuschließen. Zurzeit wird nur eine benutzerseitig zugewiesene verwaltete Identität für die identity Eigenschaft unterstützt. Verwenden Sie die zweite Methode in dieser Liste, um sich mit einer anderen Identität anzumelden.
    • Übergeben Sie die Anmeldeinformationen für den Dienstprinzipal als sichere Umgebungsvariablen, und rufen Sie dann Connect-AzAccount oder az login im Bereitstellungsskript auf.

    Wenn eine verwaltete Identität verwendet wird, muss für den Bereitstellungsprinzipal die Rolle Operator für verwaltete Identität (eine integrierte Rolle) der Ressource der verwalteten Identität zugewiesen sein.

Beispielvorlagen

Nachfolgend finden Sie ein JSON-Beispiel. Weitere Informationen finden Sie im neuesten Vorlagenschema.

{
  "type": "Microsoft.Resources/deploymentScripts",
  "apiVersion": "2020-10-01",
  "name": "runPowerShellInline",
  "location": "[resourceGroup().location]",
  "tags": {
    "tagName1": "tagValue1",
    "tagName2": "tagValue2"
  },
  "kind": "AzurePowerShell", // or "AzureCLI"
  "identity": {
    "type": "userAssigned",
    "userAssignedIdentities": {
      "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myID": {}
    }
  },
  "properties": {
    "forceUpdateTag": "1",
    "containerSettings": {
      "containerGroupName": "mycustomaci"
    },
    "storageAccountSettings": {
      "storageAccountName": "myStorageAccount",
      "storageAccountKey": "myKey"
    },
    "azPowerShellVersion": "9.7",  // or "azCliVersion": "2.47.0",
    "arguments": "-name \\\"John Dole\\\"",
    "environmentVariables": [
      {
        "name": "UserName",
        "value": "jdole"
      },
      {
        "name": "Password",
        "secureValue": "jDolePassword"
      }
    ],
    "scriptContent": "
      param([string] $name)
      $output = 'Hello {0}. The username is {1}, the password is {2}.' -f $name,${Env:UserName},${Env:Password}
      Write-Output $output
      $DeploymentScriptOutputs = @{}
      $DeploymentScriptOutputs['text'] = $output
    ", // or "primaryScriptUri": "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/deployment-script/deploymentscript-helloworld.ps1",
    "supportingScriptUris":[],
    "timeout": "PT30M",
    "cleanupPreference": "OnSuccess",
    "retentionInterval": "P1D"
  }
}

Hinweis

Dieses Beispiel dient zu Demonstrationszwecken. Die Eigenschaften scriptContent und primaryScriptUri können nicht zusammen in einer Vorlage enthalten sein.

Hinweis

scriptContent zeigt ein Skript mit mehreren Zeilen an. Das Azure-Portal und die Azure DevOps-Pipeline können keine Bereitstellungsskripts mit mehreren Zeilen analysieren. Sie können entweder die PowerShell-Befehle (mit Semikolons oder \r\n bzw. \n) zu einer Zeile verketten oder die primaryScriptUri-Eigenschaft mit einer externen Skriptdatei verwenden. Es stehen viele kostenlose Escape-/Unescapetools für JSON-Zeichenfolgen zur Verfügung. Beispiel: https://www.freeformatter.com/json-escape.html.

Details zu Eigenschaftswerten:

  • identity: Für die API-Version 2020-10-01 oder höher des Bereitstellungsskripts ist eine vom Benutzer zugewiesene verwaltete Identität optional, es sei denn, Sie müssen Azure-spezifische Aktionen im Skript ausführen. Für die API-Version 2019-10-01-preview ist eine verwaltete Identität erforderlich, da der Bereitstellungsskriptdienst diese verwendet, um die Skripts auszuführen. Wenn die Identitätseigenschaft angegeben wird, ruft der Skriptdienst Connect-AzAccount -Identity auf, bevor das Benutzerskript aufgerufen wird. Zurzeit wird nur eine benutzerseitig zugewiesene verwaltete Identität unterstützt. Wenn Sie sich mit einer anderen Identität anmelden möchten, können Sie Connect-AzAccount im Skript aufrufen.

  • tags: Bereitstellungsskripttags. Wenn der Bereitstellungsskriptdienst ein Speicherkonto und eine Containerinstanz generiert, werden die Tags an beide Ressourcen übergeben, die zur Identifizierung verwendet werden können. Diese Ressourcen können auch anhand ihrer Suffixe, welche „azscripts“ enthalten, identifiziert werden. Weitere Informationen finden Sie unter Überwachung und Problembehandlung für Bereitstellungsskripts.

  • kind: Geben Sie den Typ des Skripts an. Zurzeit werden Azure PowerShell- und Azure CLI-Skripts unterstützt. Die Werte sind AzurePowerShell und AzureCLI.

  • forceUpdateTag: Wenn Sie diesen Wert zwischen Vorlagenbereitstellungen ändern, wird das Bereitstellungsskript erneut ausgeführt. Die beiden Funktionen newGuid() und utcNow() können nur mit dem Standardwert eines Parameters verwendet werden. Weitere Informationen finden Sie unter Mehrmaliges Ausführen des Skripts.

  • containerSettings: Geben Sie die Einstellungen zum Anpassen der Azure-Containerinstanz an. Im Bereitstellungsskript muss eine neue Azure-Containerinstanz angegeben werden. Sie können keine vorhandene Azure-Containerinstanz angeben. Sie können jedoch den Namen der Containergruppe mithilfe von containerGroupName anpassen. Falls nicht angegeben, wird der Gruppenname automatisch generiert.

  • storageAccountSettings: Geben Sie die Einstellungen zur Verwendung eines vorhandenen Speicherkontos an. Wenn storageAccountName nicht angegeben ist, wird ein Speicherkonto automatisch erstellt. Weitere Informationen finden Sie unter Verwenden eines vorhandenen Speicherkontos.

  • azPowerShellVersion/azCliVersion: Geben Sie die zu verwendende Modulversion an. Eine Liste mit den unterstützten Azure PowerShell-Versionen finden Sie hier. Die Version bestimmt, welches Containerimage verwendet werden soll:

    • Die Az-Version größer als oder gleich 9 verwendet Ubuntu 22.04.
    • Die Az-Version größer als oder gleich 6 aber kleiner als 9 verwendet Ubuntu 20.04.
    • Die Az-Version kleiner als 6 verwendet Ubuntu 18.04.

    Wichtig

    Es empfiehlt sich, ein Upgrade auf die neueste Version von Ubuntu durchzuführen, da Ubuntu 18.04 sich seinem Ende seiner Lebensdauer nähert und nach dem 31. Mai 2023 keine Sicherheitsupdates mehr erhält.

    Eine Liste mit den unterstützten Azure CLI-Versionen finden Sie hier.

    Wichtig

    Das Bereitstellungsskript verwendet die verfügbaren CLI-Images von Microsoft Container Registry (MCR). Das Zertifizieren eines CLI-Images für das Bereitstellungsskript dauert normalerweise circa einen Monat. Verwenden Sie nicht die CLI-Versionen, die innerhalb von 30 Tagen veröffentlicht wurden. Die Veröffentlichungsdaten für die Images finden Sie unter Versionshinweise für die Azure CLI. Wenn eine nicht unterstützte Version verwendet wird, werden in der Fehlermeldung die unterstützten Versionen aufgelistet.

  • arguments: Geben Sie die Parameterwerte an. Die Werte werden durch Leerzeichen voneinander getrennt.

    Bereitstellungsskripts teilen die Argumente in ein Array von Zeichenfolgen auf, indem sie den Systemaufruf CommandLineToArgvW aufrufen. Dieser Schritt ist erforderlich, weil die Argumente als Befehlseigenschaft an Azure Container Instance übergeben werden. Die Befehlseigenschaft ist ein Zeichenfolgenarray.

    Wenn die Argumente Escapezeichen enthalten, verwenden Sie JsonEscaper, um die Zeichen mit doppelten Escapezeichen zu versehen. Fügen Sie Ihre Originalzeichenfolge mit Escapezeichen in das Tool ein, und wählen Sie dann Escape (Mit Escapezeichen versehen) aus. Daraufhin wird von dem Tool eine Zeichenfolge mit doppelten Escapezeichen ausgegeben. In der vorherigen Beispielvorlage wird beispielsweise das Argument -name \"John Dole\" verwendet. Die Zeichenfolge mit Escapezeichen lautet -name \\\"John Dole\\\".

    Wenn Sie einen ARM-Vorlagenparameter vom Typ „Objekt“ als Argument übergeben möchten, konvertieren Sie das Objekt mithilfe der string()-Funktion in eine Zeichenfolge, und verwenden Sie anschließend die replace()-Funktion, um alle Vorkommen von \" durch \\\" zu ersetzen. Beispiel:

    replace(string(parameters('tables')), '\"', '\\\"')

    Weitere Informationen finden Sie in der Beispielvorlage.

  • environmentVariables: Geben Sie die Umgebungsvariablen an, die an das Skript übergeben werden sollen. Weitere Informationen finden Sie unter Entwickeln von Bereitstellungsskripts.

  • scriptContent: Geben Sie den Skriptinhalt an. Wenn Sie ein externes Skript ausführen möchten, verwenden Sie stattdessen primaryScriptUri. Beispiele finden Sie unter Verwenden von Inlineskripts und Verwenden externer Skripts.

  • primaryScriptUri: Geben Sie eine öffentlich zugängliche URL zum primären Bereitstellungsskript mit unterstützten Dateierweiterungen an. Weitere Informationen finden Sie unter Verwenden externer Skripts.

  • supportingScriptUris: Geben Sie ein Array öffentlich zugänglicher URLs zu unterstützenden Dateien an, die in scriptContent oder primaryScriptUri aufgerufen werden. Weitere Informationen finden Sie unter Verwenden externer Skripts.

  • timeout: Geben Sie die maximal zulässige Ausführungsdauer für das Skript im ISO 8601-Format an. Der Standardwert ist P1D.

  • cleanupPreference. Geben Sie das Verfahren an, mit dem die beiden unterstützenden Bereitstellungsressourcen, das Speicherkonto und die Containerinstanz bereinigt werden sollen, wenn die Skriptausführung in einen Beendigungszustand gelangt. Die Standardeinstellung ist Always (Immer). Damit werden die Unterstützungsressourcen unabhängig vom Endzustand (Erfolg, Fehler, Abbruch) gelöscht. Weitere Informationen finden Sie unter Bereinigen von Bereitstellungsskriptressourcen.

  • retentionInterval: Geben Sie das Intervall an, das vom Dienst für die Aufbewahrung der Bereitstellungsskriptressource verwendet wird, nachdem das Bereitstellungsskript einen Beendigungszustand erreicht. Die Bereitstellungsskriptressource wird gelöscht, wenn dieser Zeitraum abgelaufen ist. Die Dauer basiert auf dem ISO 8601-Muster. Der Aufbewahrungszeitraum liegt zwischen 1 und 26 Stunden (PT26H). Diese Eigenschaft wird verwendet, wenn cleanupPreference auf OnExpiration festgelegt ist. Weitere Informationen finden Sie unter Bereinigen von Bereitstellungsskriptressourcen.

Weitere Beispiele

  • Beispiel 1: In diesem Beispiel wird ein Schlüsseltresor erstellt und ein Bereitstellungsskript verwendet, um dem Schlüsseltresor ein Zertifikat zuzuweisen.
  • Beispiel 2: In diesem Beispiel werden eine Ressourcengruppe auf der Abonnementebene und ein Schlüsseltresor in der Ressourcengruppe erstellt. Anschließend wird ein Bereitstellungsskript verwendet, um dem Schlüsseltresor ein Zertifikat zuzuweisen.
  • Beispiel 3: In diesem Beispiel wird eine benutzerseitig verwaltete Identität erstellt. Der Identität wird die Rolle „Mitwirkender“ auf der Ressourcengruppenebene zugewiesen, und es wird ein Schlüsseltresor erstellt. Anschließend wird ein Bereitstellungsskript verwendet, um dem Schlüsseltresor ein Zertifikat zuzuweisen.
  • Beispiel 4: Hierbei handelt es sich um das gleiche Szenario wie in Beispiel 1 aus dieser Liste. Zum Ausführen des Bereitstellungsskripts wird eine neue Ressourcengruppe erstellt. Diese Vorlage ist eine Vorlage auf Abonnementebene.
  • Beispiel 5: Hierbei handelt es sich um das gleiche Szenario wie in Beispiel 4. Diese Vorlage ist eine Vorlage auf Ressourcengruppenebene.
  • Beispiel 6: Erstellen Sie manuell eine benutzerseitig zugewiesene verwaltete Identität, und weisen Sie ihr Berechtigungen zur Verwendung der Microsoft Graph-API zum Erstellen von Microsoft Entra-Anwendungen zu. Verwenden Sie in der ARM-Vorlage ein Bereitstellungsskript, um eine Microsoft Entra-Anwendung und einen Dienstprinzipal zu erstellen und die Objekt-IDs und Client-ID auszugeben.

Verwenden von Inlineskripts

Für die folgende Vorlage wurde eine Ressource mit dem Typ Microsoft.Resources/deploymentScripts definiert. Der hervorgehobene Teil ist das Inlineskript.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "name": {
      "type": "string",
      "defaultValue": "\\\"John Dole\\\""
    },
    "utcValue": {
      "type": "string",
      "defaultValue": "[utcNow()]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2020-10-01",
      "name": "runPowerShellInlineWithOutput",
      "location": "[resourceGroup().location]",
      "kind": "AzurePowerShell",
      "properties": {
        "forceUpdateTag": "[parameters('utcValue')]",
        "azPowerShellVersion": "8.3",
        "scriptContent": "
          param([string] $name)
          $output = \"Hello {0}\" -f $name
          Write-Output $output
          $DeploymentScriptOutputs = @{}
          $DeploymentScriptOutputs['text'] = $output
        ",
        "arguments": "[concat('-name', ' ', parameters('name'))]",
        "timeout": "PT1H",
        "cleanupPreference": "OnSuccess",
        "retentionInterval": "P1D"
      }
    }
  ],
  "outputs": {
    "result": {
      "value": "[reference('runPowerShellInlineWithOutput').outputs.text]",
      "type": "string"
    }
  }
}

Hinweis

Da die Inlinebereitstellungsskripts in doppelte Anführungszeichen eingeschlossen sind, muss für Zeichenfolgen innerhalb der Bereitstellungsskripts ein umgekehrter Schrägstrich (\) als Escapezeichen verwendet werden, oder sie müssen in einfache Anführungszeichen eingeschlossen werden. Sie können auch, wie im vorherigen JSON-Beispiel gezeigt, eine Zeichenfolgenersetzung in Erwägung ziehen.

Das Skript akzeptiert einen Parameter und gibt den Parameterwert aus. DeploymentScriptOutputs wird zum Speichern von Ausgaben verwendet. Im Abschnitt „outputs“ zeigt die Zeile value an, wie auf die gespeicherten Werte zugegriffen wird. Write-Output wird zum Debuggen verwendet. Informationen zum Zugreifen auf die Ausgabedatei finden Sie unter Überwachen von Bereitstellungsskripts und Behandeln von Problemen. Beschreibungen der Eigenschaften finden Sie unter Beispielvorlagen.

Wählen Sie zum Ausführen des Skripts Jetzt testen aus, um die Cloud Shell zu öffnen, und fügen Sie anschließend den folgenden Code in den Shellbereich ein.

$resourceGroupName = Read-Host -Prompt "Enter the name of the resource group to be created"
$location = Read-Host -Prompt "Enter the location (i.e. centralus)"

New-AzResourceGroup -Name $resourceGroupName -Location $location

New-AzResourceGroupDeployment -ResourceGroupName $resourceGroupName -TemplateUri "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/deployment-script/deploymentscript-helloworld.json"

Write-Host "Press [ENTER] to continue ..."

Die Ausgabe sieht wie folgt aus:

Screenshot: Resource Manager-Vorlage: Ausgabe des Hallo Welt-Bereitstellungsskripts

Verwenden externer Skripts

Neben Inlineskripts können Sie auch externe Skriptdateien verwenden. Es werden nur primäre PowerShell-Skripts mit der Dateierweiterung ps1 unterstützt. Bei CLI-Skripts können die primären Skripts beliebige (oder gar keine) Erweiterungen besitzen, solange es sich bei den Skripts um gültige Bash-Skripts handelt. Um externe Skriptdateien zu verwenden, ersetzen Sie scriptContent durch primaryScriptUri. Beispiel:

"primaryScriptUri": "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/deployment-script/deploymentscript-helloworld.ps1",

Weitere Informationen finden Sie in der Beispielvorlage.

Die externen Skriptdateien müssen zugänglich sein. Generieren Sie zum Sichern Ihrer in Azure Storage-Konten gespeicherten Skriptdateien ein SAS-Token, und fügen Sie es in den URI für die Vorlage ein. Legen Sie die Ablaufzeit so fest, dass ausreichend Zeit für die Bereitstellung bleibt. Weitere Informationen finden Sie unter Bereitstellen einer privaten ARM-Vorlage mit SAS-Token.

Es ist Ihre Aufgabe, die Integrität der Skripts zu gewährleisten, auf die vom Bereitstellungsskript verwiesen wird, entweder primaryScriptUri oder supportingScriptUris. Verweisen Sie nur auf Skripts, denen Sie vertrauen.

Verwenden unterstützender Skripts

Sie können komplizierte Logik in unterstützende Skriptdateien aufteilen. Die supportingScriptUris-Eigenschaft ermöglicht Ihnen, bei Bedarf ein Array von URIs für die unterstützenden Skriptdateien bereitzustellen:

"scriptContent": "
    ...
    ./Create-Cert.ps1
    ...
"

"supportingScriptUris": [
  "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/deployment-script/create-cert.ps1"
],

Unterstützende Skriptdateien können sowohl aus Inlineskripts als auch aus primären Skriptdateien aufgerufen werden. Unterstützende Skriptdateien unterliegen keinen Einschränkungen in Bezug auf die Dateierweiterung.

Die unterstützenden Dateien werden zur Laufzeit in azscripts/azscriptinput kopiert. Verwenden Sie den relativen Pfad, um aus Inlineskripts und primären Skriptdateien auf die unterstützenden Dateien zu verweisen.

Arbeiten mit Ausgaben von PowerShell-Skripts

Die folgende Vorlage zeigt, wie Werte zwischen zwei deploymentScripts-Ressourcen übergeben werden:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "name": {
      "type": "string",
      "defaultValue": "John Dole"
    },
    "utcValue": {
      "type": "string",
      "defaultValue": "[utcNow()]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2020-10-01",
      "name": "scriptInTemplate1",
      "location": "[resourceGroup().location]",
      "kind": "AzurePowerShell",
      "properties": {
        "forceUpdateTag": "[parameters('utcValue')]",
        "azPowerShellVersion": "8.3",
        "timeout": "PT1H",
        "arguments": "[concat('-name', ' ', concat('\\\"', parameters('name'), '\\\"'))]",
        "scriptContent": "
          param([string] $name)
          $output = 'Hello {0}' -f $name
          Write-Output $output
          $DeploymentScriptOutputs = @{}
          $DeploymentScriptOutputs['text'] = $output
        ",
        "cleanupPreference": "Always",
        "retentionInterval": "P1D"
      }
    },
    {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2020-10-01",
      "name": "scriptInTemplate2",
      "location": "[resourceGroup().location]",
      "kind": "AzurePowerShell",
      "dependsOn": [
        "scriptInTemplate1"
      ],
      "properties": {
        "forceUpdateTag": "[parameters('utcValue')]",
        "azPowerShellVersion": "8.3",
        "timeout": "PT1H",
        "arguments": "[concat('-textToEcho', ' ', concat('\\\"', reference('scriptInTemplate1').outputs.text, '\\\"'))]",
        "scriptContent": "
          param([string] $textToEcho)
          Write-Output $textToEcho
          $DeploymentScriptOutputs = @{}
          $DeploymentScriptOutputs['text'] = $textToEcho
        ",
        "cleanupPreference": "Always",
        "retentionInterval": "P1D"
      }
    }
  ],
  "outputs": {
    "result": {
      "value": "[reference('scriptInTemplate2').outputs.text]",
      "type": "string"
    }
  }
}

In der ersten Ressource definieren Sie eine Variable mit dem Namen $DeploymentScriptOutputs, die Sie zum Speichern der Ausgabewerte verwenden. Um aus einer anderen Ressource in der Vorlage auf den Ausgabewert zuzugreifen, verwenden Sie Folgendes:

reference('<ResourceName>').outputs.text

Arbeiten mit Ausgaben von CLI-Skripts

Im Gegensatz zu den Azure PowerShell-Bereitstellungsskripts stellen CLI oder Bash keine gemeinsame Variable zum Speichern von Skriptausgaben zur Verfügung. Stattdessen wird eine Umgebungsvariable mit dem Namen AZ_SCRIPTS_OUTPUT_PATH verwendet, um den Speicherort der Skriptausgabedatei anzugeben. Beim Ausführen eines Bereitstellungsskripts in einer ARM-Vorlage konfiguriert die Bash-Shell diese Umgebungsvariable automatisch für Sie. Der vordefinierte Wert lautet /mnt/azscripts/azscriptoutput/scriptoutputs.json. Die Ausgaben sind für eine gültige JSON-Zeichenfolgenobjektstruktur erforderlich. Der Inhalt der Datei sollte als Schlüssel-Wert-Paar formatiert werden. Beispielsweise sollte ein Array von Zeichenfolgen als { "MeinErgebnis": [ "foo", "bar"] } gespeichert werden. Das ausschließliche Speichern der Arrayergebnisse (z. B. [ "foo", "bar" ]) ist ungültig.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "identity": {
      "type": "string"
    },
    "utcValue": {
      "type": "string",
      "defaultValue": "[utcNow()]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2020-10-01",
      "name": "runBashWithOutputs",
      "location": "[resourceGroup().location]",
      "kind": "AzureCLI",
      "identity": {
        "type": "UserAssigned",
        "userAssignedIdentities": {
          "[parameters('identity')]": {
          }
        }
      },
      "properties": {
        "forceUpdateTag": "[parameters('utcValue')]",
        "AzCliVersion": "2.40.0",
        "timeout": "PT30M",
        "arguments": "'foo' 'bar'",
        "environmentVariables": [
          {
            "name": "UserName",
            "value": "jdole"
          },
          {
            "name": "Password",
            "secureValue": "jDolePassword"
          }
        ],
        "scriptContent": "result=$(az keyvault list); echo \"arg1 is: $1\"; echo \"arg2 is: $2\"; echo \"Username is: $UserName\"; echo \"password is: $Password\"; echo $result | jq -c '{Result: map({id: .id})}' > $AZ_SCRIPTS_OUTPUT_PATH",
        "cleanupPreference": "OnExpiration",
        "retentionInterval": "P1D"

Im vorherigen Beispiel wird jq verwendet. Dies ist in den Containerimages enthalten. Weitere Informationen finden Sie unter Konfigurieren der Entwicklungsumgebung.

Verwenden eines vorhandenen Speicherkontos

Für die Skriptausführung und Problembehandlung werden ein Speicherkonto und eine Containerinstanz benötigt. Sie haben die Möglichkeit, ein vorhandenes Speicherkonto anzugeben. Andernfalls wird das Speicherkonto zusammen mit der Containerinstanz vom Skriptdienst automatisch erstellt. Die Voraussetzungen für die Verwendung eines vorhandenen Speicherkontos:

  • Unterstützte Speicherkontotypen:

    SKU Unterstützte Typen
    Premium_LRS FileStorage
    Premium_ZRS FileStorage
    Standard_GRS Storage, StorageV2
    Standard_GZRS StorageV2
    Standard_LRS Storage, StorageV2
    Standard_RAGRS Storage, StorageV2
    Standard_RAGZRS StorageV2
    Standard_ZRS StorageV2

    Diese Kombinationen unterstützen Dateifreigaben. Weitere Informationen finden Sie unter Erstellen einer Azure-Dateifreigabe und Speicherkontoübersicht.

  • Firewallregeln für Speicherkonten werden noch nicht unterstützt. Weitere Informationen finden Sie unter Konfigurieren von Firewalls und virtuellen Netzwerken in Azure Storage.

  • Der Bereitstellungsprinzipal muss über Berechtigungen zum Verwalten des Speicherkontos verfügen. Dies umfasst das Lesen, Erstellen und Löschen von Dateifreigaben.

  • Die allowSharedKeyAccess-Eigenschaft des Speicherkontos muss auf true festgelegt werden. Die einzige Möglichkeit zum Bereitstellen eines Speicherkontos in Azure Container Instance (ACI) ist über einen Zugriffsschlüssel.

Um ein vorhandenes Speicherkonto anzugeben, fügen Sie dem Eigenschaftselement von Microsoft.Resources/deploymentScripts den folgenden JSON-Code hinzu:

"storageAccountSettings": {
  "storageAccountName": "myStorageAccount",
  "storageAccountKey": "myKey"
},

  • storageAccountName: Geben Sie den Namen des Speicherkontos an.

  • storageAccountKey: Geben Sie einen der Speicherkontoschlüssel an. Sie können den Schlüssel mit der listKeys()-Funktion abrufen. Beispiel:

    "storageAccountSettings": {
    "storageAccountName": "[variables('storageAccountName')]",
    "storageAccountKey": "[listKeys(resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName')), '2019-06-01').keys[0].value]"
}

Ein vollständiges Beispiel für die Definition von Microsoft.Resources/deploymentScripts finden Sie unter Beispielvorlagen.

Wenn ein vorhandenes Speicherkonto zum Einsatz kommt, erstellt der Skriptdienst eine Dateifreigabe mit einem eindeutigen Namen. Informationen dazu, wie der Skriptdienst die Dateifreigabe bereinigt, finden Sie unter Bereinigen von Ressourcen für Bereitstellungsskripts.

Entwickeln von Bereitstellungsskripts

Behandeln von Fehlern ohne Abbruch

Sie können steuern, wie PowerShell auf Fehler ohne Abbruch reagieren soll, indem Sie die Variable „$ErrorActionPreference“ in Ihrem Bereitstellungsskript verwenden. Wenn die Variable in Ihrem Bereitstellungsskript nicht festgelegt ist, wird der Standardwert Continue (Fortsetzen) verwendet.

Tritt bei dem Skript ein Fehler auf, wird der Bereitstellungsstatus der Ressource ungeachtet der Einstellung von $ErrorActionPreference auf Fehler festgelegt.

Verwenden von Umgebungsvariablen

Das Bereitstellungsskript verwendet diese Umgebungsvariablen:

Umgebungsvariable Standardwert System-reserviert
AZ_SCRIPTS_AZURE_ENVIRONMENT AzureCloud N
AZ_SCRIPTS_CLEANUP_PREFERENCE OnExpiration N
AZ_SCRIPTS_OUTPUT_PATH <AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY>/<AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME> J
AZ_SCRIPTS_PATH_INPUT_DIRECTORY /mnt/azscripts/azscriptinput J
AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY /mnt/azscripts/azscriptoutput J
AZ_SCRIPTS_PATH_USER_SCRIPT_FILE_NAME Azure PowerShell: userscript.ps1; Azure CLI: userscript.sh J
AZ_SCRIPTS_PATH_PRIMARY_SCRIPT_URI_FILE_NAME primaryscripturi.config J
AZ_SCRIPTS_PATH_SUPPORTING_SCRIPT_URI_FILE_NAME supportingscripturi.config J
AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME scriptoutputs.json J
AZ_SCRIPTS_PATH_EXECUTION_RESULTS_FILE_NAME executionresult.json J
AZ_SCRIPTS_USER_ASSIGNED_IDENTITY /subscriptions/ N

Weitere Informationen zur Verwendung von AZ_SCRIPTS_OUTPUT_PATH finden Sie unter Verwenden der Ausgaben vom CLI-Skript.

Übergeben von sicheren Zeichenfolgen an Bereitstellungsskripts

Das Festlegen von Umgebungsvariablen (EnvironmentVariable) in Ihren Containerinstanzen ermöglicht es Ihnen, eine dynamische Konfiguration der Anwendung oder des Skripts bereitzustellen, die bzw. das vom Container ausgeführt wird. Das Bereitstellungsskript verarbeitet nicht gesicherte und gesicherte Umgebungsvariablen auf dieselbe Weise wie Azure-Containerinstanz. Weitere Informationen finden Sie unter Festlegen von Umgebungsvariablen in Container Instances. Ein Beispiel finden Sie unter Beispielvorlagen.

Die maximal zulässige Größe für Umgebungsvariablen beträgt 64 KB.

Überwachen von Bereitstellungsskripts und Behandeln von Problemen

Der Skriptdienst erstellt für die Ausführung von Skripts im Hintergrund ein Speicherkonto (es sei denn, Sie geben ein vorhandenes Speicherkonto an) und eine Containerinstanz. Wenn diese Ressourcen automatisch vom Skriptdienst erstellt werden, haben die Namen der Ressourcen das Suffix azscripts.

Screenshot: Resource Manager-Vorlage: Ressourcennamen des Bereitstellungsskript

Das Benutzerskript, die Ausführungsergebnisse und die stdout-Datei werden in den Dateifreigaben des Speicherkontos gespeichert. Ein Ordner namens azscripts ist vorhanden. In diesem Ordner sind zwei weitere Ordner für die Eingabe- und Ausgabedateien enthalten: azscriptinput und azscriptoutput.

Der Ausgabeordner enthält die Datei executionresult.json und die Skriptausgabedatei. Sie können die Fehlermeldung der Skriptausführung in executionresult.json anzeigen. Die Ausgabedatei wird nur erstellt, wenn das Skript erfolgreich ausgeführt wurde. Der Eingabeordner enthält eine PowerShell-Skriptdatei des Systems und die Bereitstellungsskriptdateien der Benutzer. Sie können die Skriptdatei für die Benutzerbereitstellung durch eine überarbeitete Version ersetzen und das Bereitstellungsskript erneut aus der Azure-Containerinstanz ausführen.

Verwenden des Azure-Portals

Nachdem Sie eine Bereitstellungsskriptressource bereitgestellt haben, wird sie im Azure-Portal unter der Ressourcengruppe aufgeführt. Der folgende Screenshot zeigt die Übersichtsseite einer Bereitstellungsskriptressource:

Screenshot: Resource Manager-Vorlage: Übersicht über das Bereitstellungsskript im Portal

Auf der Übersichtsseite werden einige wichtige Informationen der Ressource wie Bereitstellungsstatus, Speicherkonto, Containerinstanz und Protokolle angezeigt.

Über das Menü auf der linken Seite können Sie den Inhalt des Bereitstellungsskripts, die an das Skript übergebenen Argumente und die Ausgabe anzeigen. Außerdem können Sie eine Vorlage für das Bereitstellungsskript exportieren (einschließlich des Bereitstellungsskripts).

Verwenden von PowerShell

Mit Azure PowerShell können Sie Bereitstellungsskripts im Abonnement- oder Ressourcengruppenbereich verwalten:

Die Ausgabe von Get-AzDeploymentScript sieht in etwa wie folgt aus:

Name                : runPowerShellInlineWithOutput
Id                  : /subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myds0618rg/providers/Microsoft.Resources/deploymentScripts/runPowerShellInlineWithOutput
ResourceGroupName   : myds0618rg
Location            : centralus
SubscriptionId      : aaaabbbb-0000-cccc-1111-dddd2222eeee
ProvisioningState   : Succeeded
Identity            : /subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/mydentity1008rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myuami
ScriptKind          : AzurePowerShell
AzPowerShellVersion : 9.7
StartTime           : 5/11/2023 7:46:45 PM
EndTime             : 5/11/2023 7:49:45 PM
ExpirationDate      : 5/12/2023 7:49:45 PM
CleanupPreference   : OnSuccess
StorageAccountId    : /subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myds0618rg/providers/Microsoft.Storage/storageAccounts/ftnlvo6rlrvo2azscripts
ContainerInstanceId : /subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myds0618rg/providers/Microsoft.ContainerInstance/containerGroups/ftnlvo6rlrvo2azscripts
Outputs             :
                      Key                 Value
                      ==================  ==================
                      text                Hello John Dole

RetentionInterval   : P1D
Timeout             : PT1H

Mithilfe der Azure-Befehlszeilenschnittstelle

Über die Azure-Befehlszeilenschnittstelle können Sie Bereitstellungsskripts im Abonnement- oder Ressourcengruppenbereich verwalten:

Die Ausgabe des Befehls „list“ sieht in etwa wie folgt aus:

[
  {
    "arguments": "'foo' 'bar'",
    "azCliVersion": "2.40.0",
    "cleanupPreference": "OnExpiration",
    "containerSettings": {
      "containerGroupName": null
    },
    "environmentVariables": null,
    "forceUpdateTag": "20231101T163748Z",
    "id": "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myds0624rg/providers/Microsoft.Resources/deploymentScripts/runBashWithOutputs",
    "identity": {
      "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
      "type": "userAssigned",
      "userAssignedIdentities": {
        "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourcegroups/myidentity/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myuami": {
          "clientId": "00001111-aaaa-2222-bbbb-3333cccc4444",
          "principalId": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
        }
      }
    },
    "kind": "AzureCLI",
    "location": "centralus",
    "name": "runBashWithOutputs",
    "outputs": {
      "Result": [
        {
          "id": "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/mytest/providers/Microsoft.KeyVault/vaults/mykv1027",
          "resourceGroup": "mytest"
        }
      ]
    },
    "primaryScriptUri": null,
    "provisioningState": "Succeeded",
    "resourceGroup": "mytest",
    "retentionInterval": "1 day, 0:00:00",
    "scriptContent": "result=$(az keyvault list); echo \"arg1 is: $1\"; echo $result | jq -c '{Result: map({id: .id})}' > $AZ_SCRIPTS_OUTPUT_PATH",
    "status": {
      "containerInstanceId": "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/mytest/providers/Microsoft.ContainerInstance/containerGroups/eg6n7wvuyxn7iazscripts",
      "endTime": "2023-11-01T16:39:12.080950+00:00",
      "error": null,
      "expirationTime": "2023-11-02T16:39:12.080950+00:00",
      "startTime": "2023-11-01T16:37:53.139700+00:00",
      "storageAccountId": null
    },
    "storageAccountSettings": {
      "storageAccountKey": null,
      "storageAccountName": "dsfruro267qwb4i"
    },
    "supportingScriptUris": null,
    "systemData": {
      "createdAt": "2023-10-31T19:06:57.060909+00:00",
      "createdBy": "someone@contoso.com",
      "createdByType": "User",
      "lastModifiedAt": "2023-11-01T16:37:51.859570+00:00",
      "lastModifiedBy": "someone@contoso.com",
      "lastModifiedByType": "User"
    },
    "tags": null,
    "timeout": "0:30:00",
    "type": "Microsoft.Resources/deploymentScripts"
  }
]

REST-API

Mithilfe der REST-API können Sie die Bereitstellungsinformationen der Bereitstellungsskriptressourcen auf Ressourcengruppenebene und Abonnementebene abrufen:

/subscriptions/<SubscriptionID>/resourcegroups/<ResourceGroupName>/providers/microsoft.resources/deploymentScripts/<DeploymentScriptResourceName>?api-version=2020-10-01

/subscriptions/<SubscriptionID>/providers/microsoft.resources/deploymentScripts?api-version=2020-10-01

Im folgenden Beispiel wird ARMClient verwendet:

armclient login
armclient get /subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourcegroups/myrg/providers/microsoft.resources/deploymentScripts/myDeployementScript?api-version=2020-10-01

Die Ausgabe sieht in etwa wie folgt aus:

{
  "kind": "AzurePowerShell",
  "identity": {
    "type": "userAssigned",
    "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
    "userAssignedIdentities": {
      "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myidentity1008rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myuami": {
        "principalId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
        "clientId": "00001111-aaaa-2222-bbbb-3333cccc4444"
      }
    }
  },
  "location": "centralus",
  "systemData": {
    "createdBy": "someone@contoso.com",
    "createdByType": "User",
    "createdAt": "2023-05-11T02:59:04.7501955Z",
    "lastModifiedBy": "someone@contoso.com",
    "lastModifiedByType": "User",
    "lastModifiedAt": "2023-05-11T02:59:04.7501955Z"
  },
  "properties": {
    "provisioningState": "Succeeded",
    "forceUpdateTag": "20220625T025902Z",
    "azPowerShellVersion": "9.7",
    "scriptContent": "\r\n          param([string] $name)\r\n          $output = \"Hello {0}\" -f $name\r\n          Write-Output $output\r\n          $DeploymentScriptOutputs = @{}\r\n          $DeploymentScriptOutputs['text'] = $output\r\n        ",
    "arguments": "-name \\\"John Dole\\\"",
    "retentionInterval": "P1D",
    "timeout": "PT1H",
    "containerSettings": {},
    "status": {
      "containerInstanceId": "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myds0624rg/providers/Microsoft.ContainerInstance/containerGroups/64lxews2qfa5uazscripts",
      "storageAccountId": "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myds0624rg/providers/Microsoft.Storage/storageAccounts/64lxews2qfa5uazscripts",
      "startTime": "2023-05-11T02:59:07.5951401Z",
      "endTime": "2023-05-11T03:00:16.7969234Z",
      "expirationTime": "2023-05-12T03:00:16.7969234Z"
    },
    "outputs": {
      "text": "Hello John Dole"
    },
    "cleanupPreference": "OnSuccess"
  },
  "id": "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myds0624rg/providers/Microsoft.Resources/deploymentScripts/runPowerShellInlineWithOutput",
  "type": "Microsoft.Resources/deploymentScripts",
  "name": "runPowerShellInlineWithOutput"
}

Die folgende REST-API gibt das Protokoll zurück:

/subscriptions/<SubscriptionID>/resourcegroups/<ResourceGroupName>/providers/microsoft.resources/deploymentScripts/<DeploymentScriptResourceName>/logs?api-version=2020-10-01

Dies funktioniert nur, bevor die Bereitstellungsskriptressourcen gelöscht werden.

Wählen Sie im Portal die Option Ausgeblendete Typen anzeigen aus, um die deploymentScripts-Ressource anzuzeigen.

Screenshot: Resource Manager-Vorlage: Bereitstellungsskript mit Option „Ausgeblendete Typen anzeigen“ im Portal

Bereinigen von Bereitstellungsskriptressourcen

Die beiden automatisch erstellten Unterstützungsressourcen können die deploymentScript-Ressource nie überdauern, es sei denn, es treten Fehler beim Löschen auf. Der Lebenszyklus der Unterstützungsressourcen wird über die cleanupPreference-Eigenschaft gesteuert und der Lebenszyklus der deploymentScript-Ressource über die retentionInterval-Eigenschaft:

  • cleanupPreference: Geben Sie die Einstellung für das Bereinigen der beiden Unterstützungsressourcen an, nachdem die Skriptausführung beendet wurde. Die unterstützten Werte sind:

    • Always: Die beiden Unterstützungsressourcen werden gelöscht, wenn die Skriptausführung einen Beendigungszustand erreicht. Wenn ein vorhandenes Speicherkonto zum Einsatz kommt, löscht der Skriptdienst die vom Dienst erstellte Dateifreigabe. Da die deploymentScripts-Ressource möglicherweise noch vorhanden ist, nachdem die unterstützenden Ressourcen bereinigt wurden, hält der Skriptdienst die Ergebnisse der Skriptausführung fest, z. B. stdout, Ausgaben und Rückgabewert, bevor die Ressourcen gelöscht werden.

    • OnSuccess: Die beiden Unterstützungsressourcen werden nur gelöscht, wenn die Skriptausführung erfolgreich war. Wenn ein vorhandenes Speicherkonto verwendet wird, entfernt der Skriptdienst die Dateifreigabe nur bei erfolgreicher Skriptausführung.

      Wenn die Skriptausführung nicht erfolgreich ist, wartet der Skriptdienst, bis das retentionInterval abläuft, bevor er die Unterstützungsressourcen und dann die Bereitstellungsskriptressource bereinigt.

    • OnExpiration: Die beiden Unterstützungsressourcen werden nur gelöscht, wenn die Einstellung retentionInterval abgelaufen ist. Wenn ein vorhandenes Speicherkonto zum Einsatz kommt, entfernt der Skriptdienst die Dateifreigabe und behält das Speicherkonto bei.

    Die Containerinstanz und das Speicherkonto werden gemäß der Option cleanupPreference gelöscht. Wenn beim Skript jedoch ein Fehler auftritt und cleanupPreference nicht auf Always festgelegt ist, führt der Bereitstellungsprozess den Container automatisch eine Stunde lang oder bis zur Bereinigung des Containers aus. Sie können diese Zeit für die Problembehandlung des Skripts nutzen. Wenn Sie den Container nach erfolgreichen Bereitstellungen beibehalten möchten, fügen Sie dem Skript einen Energiesparmodusschritt hinzu. Fügen Sie z. B. Start-Sleep am Ende des Skripts hinzu. Wenn Sie den Energiesparmodusschritt nicht hinzufügen, wird der Container auf einen Terminalzustand festgelegt. Auf ihn kann dann nicht zugegriffen werden, auch wenn er noch nicht gelöscht wurde.

  • retentionInterval: Geben Sie das Zeitintervall an, für das eine deploymentScript-Ressource aufbewahrt wird und nach dem sie als abgelaufen gilt und gelöscht wird.

Hinweis

Es wird nicht empfohlen, das Speicherkonto und die Containerinstanz zu verwenden, die vom Skriptdienst für andere Zwecke generiert werden. Die beiden Ressourcen werden abhängig vom Lebenszyklus des Skripts möglicherweise entfernt.

Das automatisch erstellte Speicherkonto und die Containerinstanz können nicht gelöscht werden, wenn das Bereitstellungsskript in einer Ressourcengruppe mit CanNotDelete-Sperre bereitgestellt wurde. Zur Behebung dieses Problem können Sie das Bereitstellungsskript ohne Sperren in einer anderen Ressourcengruppe bereitstellen. Sehen Sie sich dazu unter Beispielvorlagen die Beispiele 4 und 5 an.

Mehrmaliges Ausführen des Skripts

Die Ausführung des Bereitstellungsskripts ist ein idempotenter Vorgang. Wenn keine der deploymentScripts-Ressourceneigenschaften (einschließlich des Inlineskripts) geändert werden, wird das Skript nicht ausgeführt, wenn Sie die Vorlage erneut bereitstellen. Der Bereitstellungsskriptdienst vergleicht die Ressourcennamen in der Vorlage mit den vorhandenen Ressourcen in derselben Ressourcengruppe. Wenn Sie dasselbe Bereitstellungsskript mehrmals ausführen möchten, haben Sie zwei Möglichkeiten:

  • Wählen Sie den Namen Ihrer deploymentScripts-Ressource aus. Verwenden Sie z. B. die Vorlagenfunktion utcNow als Ressourcennamen oder als Teil des Ressourcennamens. Wenn Sie den Ressourcennamen ändern, wird eine neue deploymentScripts-Ressource erstellt. Diese ist sinnvoll, um den Verlauf der Skriptausführung zu protokollieren.

    Hinweis

    Die utcNow-Funktion kann nur für den Standardwert eines Parameters verwendet werden.

  • Geben Sie einen anderen Wert in der forceUpdateTag-Eigenschaft der Vorlage an. Verwenden Sie beispielsweise als Wert utcNow.

Hinweis

Schreiben Sie idempotente Bereitstellungsskripts. Dadurch wird sichergestellt, dass bei versehentlicher erneuter Ausführung keine Systemänderungen auftreten. Wenn das Bereitstellungsskript z. B. zum Erstellen einer Azure-Ressource verwendet wird, vergewissern Sie sich, dass die Ressource vor dem Erstellen nicht vorhanden ist, damit das Skript erfolgreich ausgeführt werden kann und Sie die Ressource nicht erneut erstellen.

Konfigurieren der Entwicklungsumgebung

Sie können ein vorkonfiguriertes Containerimage als Entwicklungsumgebung für Ihr Bereitstellungsskript verwenden. Weitere Informationen finden Sie unter Konfigurieren der Entwicklungsumgebung für Bereitstellungsskripts in Vorlagen.

Nachdem das Skript erfolgreich getestet wurde, können Sie es als Bereitstellungsskript in Ihren Vorlagen verwenden.

Fehlercodes von Bereitstellungsskripts

Fehlercode BESCHREIBUNG
DeploymentScriptInvalidOperation Die Bereitstellungsskript-Ressourcendefinition in der Vorlage enthält ungültige Eigenschaftsnamen.
DeploymentScriptResourceConflict Eine Bereitstellungsskriptressource, die sich in einem Nicht-Terminalzustand befindet und deren Ausführung 1 Stunde noch nicht überschritten hat, kann nicht gelöscht werden. Oder es kann nicht dasselbe Bereitstellungsskript mit demselben Ressourcenbezeichner (selbes Abonnement, selber Ressourcengruppenname und selber Ressourcenname), aber unterschiedlichem Skripttextinhalt gleichzeitig erneut ausgeführt werden.
DeploymentScriptOperationFailed Interner Fehler beim Bereitstellungsskriptvorgang. Wenden Sie sich an den Microsoft-Support.
DeploymentScriptStorageAccountAccessKeyNotSpecified Der Zugriffsschlüssel wurde nicht für das vorhandene Speicherkonto angegeben.
DeploymentScriptContainerGroupContainsInvalidContainers Eine vom Bereitstellungsskriptdienst erstellte Containergruppe wurde extern geändert, und es wurden ungültige Container hinzugefügt.
DeploymentScriptContainerGroupInNonterminalState Mindestens zwei Bereitstellungsskriptressourcen verwenden denselben Azure-Containerinstanznamen in derselben Ressourcengruppe, und einer von ihnen hat die Ausführung noch nicht abgeschlossen.
DeploymentScriptStorageAccountInvalidKind Das vorhandene Speicherkonto des Typs „BlobBlobStorage“ oder „BlobStorage“ unterstützt keine Dateifreigaben und kann nicht verwendet werden.
DeploymentScriptStorageAccountInvalidKindAndSku Das vorhandene Speicherkonto unterstützt keine Dateifreigaben. Eine Liste der unterstützten Speicherkontotypen finden Sie unter Verwenden eines vorhandenen Speicherkontos.
DeploymentScriptStorageAccountNotFound Das Speicherkonto ist nicht vorhanden oder wurde von einem externen Prozess oder Tool gelöscht.
DeploymentScriptStorageAccountWithServiceEndpointEnabled Das angegebene Speicherkonto besitzt einen Dienstendpunkt. Ein Speicherkonto mit einem Dienstendpunkt wird nicht unterstützt.
DeploymentScriptStorageAccountInvalidAccessKey Für das vorhandene Speicherkonto wurde ein ungültiger Zugriffsschlüssel angegeben.
DeploymentScriptStorageAccountInvalidAccessKeyFormat Ungültiges Speicherkonto-Schlüsselformat. Weitere Informationen finden Sie unter Verwalten von Speicherkonto-Zugriffsschlüsseln.
DeploymentScriptExceededMaxAllowedTime Die Dauer der Ausführung des Bereitstellungsskripts hat den in der Ressourcendefinition des Bereitstellungsskripts angegebenen Timeoutwert überschritten.
DeploymentScriptInvalidOutputs Die Bereitstellungsskriptausgabe ist kein gültiges JSON-Objekt.
DeploymentScriptContainerInstancesServiceLoginFailure Die vom Benutzer zugewiesene verwaltete Identität konnte sich nach 10 Versuchen in einem Intervall von jeweils 1 Minute nicht anmelden.
DeploymentScriptContainerGroupNotFound Eine vom Bereitstellungsskriptdienst erstellte Containergruppe wurde von einem externen Tool oder Prozess gelöscht.
DeploymentScriptDownloadFailure Fehler beim Herunterladen eines unterstützenden Skripts. Siehe Verwenden unterstützender Skripts.
DeploymentScriptError Das Benutzerskript hat einen Fehler ausgelöst.
DeploymentScriptBootstrapScriptExecutionFailed Das Bootstrapskript hat einen Fehler ausgelöst. Das Bootstrapskript ist das Systemskript, das die Ausführung des Bereitstellungsskripts orchestriert.
DeploymentScriptExecutionFailed Unbekannter Fehler während der Ausführung des Bereitstellungsskripts.
DeploymentScriptContainerInstancesServiceUnavailable Beim Erstellen der Azure-Containerinstanz (ACI) hat ACI den Fehler „Dienst nicht verfügbar“ ausgelöst.
DeploymentScriptContainerGroupInNonterminalState Beim Erstellen der Azure-Containerinstanz (ACI) verwendet ein anderes Bereitstellungsskript denselben ACI-Namen im selben Bereich (selbes/r Abonnement, Ressourcengruppenname und Ressourcenname).
DeploymentScriptContainerGroupNameInvalid Der angegebene Name der Azure-Containerinstanz (ACI) entspricht nicht den ACI-Anforderungen. Siehe Behandeln von häufigen Problemen in Azure Container Instances.

Verwenden von Microsoft Graph in einem Bereitstellungsskript

Ein Bereitstellungsskript kann Microsoft Graph zum Erstellen und Verwenden von Objekten in Microsoft Entra ID verwenden.

Befehle

Wenn Sie Azure CLI-Bereitstellungsskripts verwenden, können Sie Befehle in der Befehlsgruppe az ad verwenden, um mit Anwendungen, Dienstprinzipalen, Gruppen und Benutzern zu arbeiten. Sie können Microsoft Graph-APIs auch direkt mithilfe des Befehls az rest aufrufen.

Wenn Sie Azure PowerShell-Bereitstellungsskripts verwenden, können Sie das Invoke-RestMethod-Cmdlet verwenden, um die Microsoft Graph-APIs direkt aufzurufen.

Berechtigungen

Die Identität, die Ihr Bereitstellungsskript verwendet, muss für die Verwendung mit der Microsoft Graph-API mit den entsprechenden Berechtigungen für die ausgeführten Vorgänge autorisiert werden. Sie müssen die Identität außerhalb der Vorlagenbereitstellung autorisieren, etwa, indem Sie vorab eine benutzerseitig zugewiesene verwaltete Identität erstellen und ihr eine App-Rolle für Microsoft Graph zuweisen. Weitere Informationen finden Sie in diesem Schnellstartbeispiel.

Zugreifen auf ein privates virtuelles Netzwerk

Mit Microsoft.Resources/deploymentScripts, Version 2023-08-01, können Sie Bereitstellungsskripts in privaten Netzwerken mit einigen zusätzlichen Konfigurationen ausführen.

  • Erstellen Sie eine benutzerseitig zugewiesene verwaltete Identität, und geben Sie sie in der Eigenschaft identity an. Informationen zum Zuweisen der Identität finden Sie unter Identität.

  • Erstellen Sie ein Speicherkonto für das allowSharedKeyAccess auf true festgelegt ist, und geben Sie das Bereitstellungsskript für die Verwendung des vorhandenen Speicherkontos an. Informationen zum Festlegen eines vorhandenen Speicherkontos finden Sie unter Verwenden eines vorhandenen Speicherkontos. Für das Speicherkonto sind einige zusätzlichen Konfigurationen erforderlich.

    1. Öffnen Sie das Speicherkonto im Azure-Portal.

    2. Wählen Sie im linken Menü Zugriffssteuerung (IAM) aus, und wählen Sie dann die Registerkarte Rollenzuweisungen aus.

    3. Fügen Sie der verwalteten Identität der Benutzerzuweisung die Storage File Data Privileged Contributor-Rolle hinzu.

    4. Wählen Sie unter Sicherheit + Netzwerk die Option Netzwerk und dann Firewalls und virtuelle Netzwerke aus.

    5. Wählen Sie Aktiviert von ausgewählten virtuellen Netzwerken und IP-Adressen aus.

      Screenshot der Konfiguration eines Speicherkontos für den Zugriff auf ein privates Netzwerk.

    6. Fügen Sie unter Virtuelle Netzwerke ein Subnetz hinzu. Im Screenshot heißt das Subnetz dspvnVnet.

    7. Wählen Sie unter Ausnahmen die Option Allow Azure services on the trusted services list to access this storage account (Für Azure-Dienste aus der Liste vertrauenswürdiger Dienste Zugriff auf dieses Speicherkonto zulassen) aus.

Die folgende ARM-Vorlage zeigt, wie Sie die Umgebung für die Ausführung eines Bereitstellungsskripts konfigurieren:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "prefix": {
      "type": "string",
      "maxLength": 10
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    },
    "userAssignedIdentityName": {
      "type": "string",
      "defaultValue": "[format('{0}Identity', parameters('prefix'))]"
    },
    "storageAccountName": {
      "type": "string",
      "defaultValue": "[format('{0}stg{1}', parameters('prefix'), uniqueString(resourceGroup().id))]"
    },
    "vnetName": {
      "type": "string",
      "defaultValue": "[format('{0}Vnet', parameters('prefix'))]"
    },
    "subnetName": {
      "type": "string",
      "defaultValue": "[format('{0}Subnet', parameters('prefix'))]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Network/virtualNetworks",
      "apiVersion": "2023-09-01",
      "name": "[parameters('vnetName')]",
      "location": "[parameters('location')]",
      "properties": {
        "addressSpace": {
          "addressPrefixes": [
            "10.0.0.0/16"
          ]
        },
        "enableDdosProtection": false,
        "subnets": [
          {
            "name": "[parameters('subnetName')]",
            "properties": {
              "addressPrefix": "10.0.0.0/24",
              "serviceEndpoints": [
                {
                  "service": "Microsoft.Storage"
                }
              ],
              "delegations": [
                {
                  "name": "Microsoft.ContainerInstance.containerGroups",
                  "properties": {
                    "serviceName": "Microsoft.ContainerInstance/containerGroups"
                  }
                }
              ]
            }
          }
        ]
      }
    },
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2023-01-01",
      "name": "[parameters('storageAccountName')]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "StorageV2",
      "properties": {
        "networkAcls": {
          "bypass": "AzureServices",
          "virtualNetworkRules": [
            {
              "id": "[resourceId('Microsoft.Network/virtualNetworks/subnets', parameters('vnetName'), parameters('subnetName'))]",
              "action": "Allow",
              "state": "Succeeded"
            }
          ],
          "defaultAction": "Deny"
        },
        "allowSharedKeyAccess": true
      },
      "dependsOn": [
        "[resourceId('Microsoft.Network/virtualNetworks', parameters('vnetName'))]"
      ]
    },
    {
      "type": "Microsoft.ManagedIdentity/userAssignedIdentities",
      "apiVersion": "2023-07-31-preview",
      "name": "[parameters('userAssignedIdentityName')]",
      "location": "[parameters('location')]"
    },
    {
      "type": "Microsoft.Authorization/roleAssignments",
      "apiVersion": "2022-04-01",
      "scope": "[format('Microsoft.Storage/storageAccounts/{0}', parameters('storageAccountName'))]",
      "name": "[guid(tenantResourceId('Microsoft.Authorization/roleDefinitions', '69566ab7-960f-475b-8e7c-b3118f30c6bd'), resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentityName')), resourceId('Microsoft.Storage/storageAccounts', parameters('storageAccountName')))]",
      "properties": {
        "principalId": "[reference(resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentityName')), '2023-07-31-preview').principalId]",
        "roleDefinitionId": "[tenantResourceId('Microsoft.Authorization/roleDefinitions', '69566ab7-960f-475b-8e7c-b3118f30c6bd')]",
        "principalType": "ServicePrincipal"
      },
      "dependsOn": [
        "[resourceId('Microsoft.Storage/storageAccounts', parameters('storageAccountName'))]",
        "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentityName'))]"
      ]
    }
  ]
}

Sie können die folgende ARM-Vorlage zum Testen der Bereitstellung verwenden:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "prefix": {
      "type": "string"
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    },
    "utcValue": {
      "type": "string",
      "defaultValue": "[utcNow()]"
    },
    "storageAccountName": {
      "type": "string"
    },
    "vnetName": {
      "type": "string"
    },
    "subnetName": {
      "type": "string"
    },
    "userAssignedIdentityName": {
      "type": "string"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2023-08-01",
      "name": "[format('{0}DS', parameters('prefix'))]",
      "location": "[parameters('location')]",
      "identity": {
        "type": "userAssigned",
        "userAssignedIdentities": {
          "[format('{0}', resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentityName')))]": {}
        }
      },
      "kind": "AzureCLI",
      "properties": {
        "forceUpdateTag": "[parameters('utcValue')]",
        "azCliVersion": "2.47.0",
        "storageAccountSettings": {
          "storageAccountName": "[parameters('storageAccountName')]"
        },
        "containerSettings": {
          "subnetIds": [
            {
              "id": "[resourceId('Microsoft.Network/virtualNetworks/subnets', parameters('vnetName'), parameters('subnetName'))]"
            }
          ]
        },
        "scriptContent": "echo \"Hello world!\"",
        "retentionInterval": "P1D",
        "cleanupPreference": "OnExpiration"
      }
    }
  ]
}

Nächste Schritte

In diesem Artikel haben Sie erfahren, wie Sie Bereitstellungsskripts verwenden. Ein Tutorial zu Bereitstellungsskripts finden Sie unter:

Tutorial: Verwenden von Bereitstellungsskripts in Azure Resource Manager-Vorlagen.

Learn-Modul: Erweitern von ARM-Vorlagen mithilfe von Bereitstellungsskripts