Freigeben über

Entwickeln eines Bereitstellungsskripts in Bicep

  • Artikel

In diesem Artikel finden Sie Beispiele zum Entwickeln eines Bereitstellungsskripts in Bicep.

Bereitstellungsskriptressourcen weisen möglicherweise eine Bereitstellungsdauer auf. Für das effiziente Entwickeln und Testen dieser Skripts sollten Sie gegebenenfalls eine dedizierte Entwicklungsumgebung einrichten, z. B. eine Azure-Containerinstanz (ACI) oder eine Docker-Instanz. Weitere Informationen finden Sie unter Erstellen einer Entwicklungsumgebung.

Syntax

Die folgende Bicep-Datei ist ein Beispiel für eine Bereitstellungsskriptressource. Weitere Informationen finden Sie im aktuellen Bereitstellungsskriptschema.

resource <symbolic-name> 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: '<resource-name>'
  location: resourceGroup().location
  tags: {}
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '<user-assigned-identity-id>': {}
    }
  }
  kind: 'AzureCLI'
  properties: {
    storageAccountSettings: {
      storageAccountName: '<storage-account-name>'
      storageAccountKey: '<storage-account-key>'
    }
    containerSettings: {
      containerGroupName: '<container-group-name>'
      subnetIds: [
        {
          id: '<subnet-id>'
        }
      ]
    }
    environmentVariables: []
    azCliVersion: '2.52.0'
    arguments: '<script-arguments>'
    scriptContent: '''<azure-cli-or-azure-powershell-script>''' // or primaryScriptUri: 'https://raw.githubusercontent.com/Azure/azure-docs-bicep-samples/main/samples/deployment-script/inlineScript.ps1'
    supportingScriptUris: []
    timeout: 'P1D'
    cleanupPreference: 'OnSuccess'
    retentionInterval: 'P1D'
    forceUpdateTag: '1'
  }
}

Geben Sie in Ihrem Bereitstellungsskript die folgenden Eigenschaftswerte an:

  • tags: Geben Sie Bereitstellungsskripttags an. Wenn der Bereitstellungsskriptdienst die beiden unterstützenden Ressourcen (ein Speicherkonto und eine Containerinstanz) erstellt, werden die Tags an beide Ressourcen übergeben. Sie können die Tags zur Identifizierung der Ressourcen verwenden. Diese unterstützenden Ressourcen können auch anhand ihrer Suffixe, welche azscripts enthalten, identifiziert werden. Weitere Informationen finden Sie unter Überwachung und Problembehandlung für Bereitstellungsskripts.

  • identity: Für die API-Version 2020-10-01 oder höher des Bereitstellungsskripts ist eine benutzerseitig zugewiesene verwaltete Identität optional, es sei denn, Sie müssen Azure-spezifische Aktionen im Skript ausführen oder führen das Bereitstellungsskript in einem privaten Netzwerk aus. 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 Eigenschaft identity 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 im Bereitstellungsskript anmelden möchten, können Sie Connect-AzAccount aufrufen. Weitere Informationen finden Sie unter Konfigurieren der mindestens erforderlichen Berechtigungen.

  • kind: Geben Sie den Typ des Skripts an, entweder AzurePowerShell oder AzureCLI. Neben kind müssen Sie auch die Eigenschaft azPowerShellVersion oder azCliVersion angeben.

  • 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.

  • containerSettings: Passen Sie den Namen der Azure-Containerinstanz an. Informationen zum Konfigurieren des Gruppennamens des Containers finden Sie weiter unten in diesem Artikel unter Konfigurieren einer Containerinstanz. Informationen zum Konfigurieren von subnetIds zum Ausführen des Bereitstellungsskripts in einem privaten Netzwerk finden Sie unter Zugreifen auf ein privates virtuelles Netzwerk.

  • environmentVariables: Geben Sie die Umgebungsvariablen an, die an das Skript übergeben werden sollen.

  • azPowerShellVersion/azCliVersion: Geben Sie die zu verwendende Modulversion an.

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

    Wichtig

    Das Bereitstellungsskript verwendet die verfügbaren CLI-Images der Microsoft-Artefaktregistrierung. In der Regel dauert das Zertifizieren eines CLI-Images für ein Bereitstellungsskript dauert ungefähr einen Monat. Verwenden Sie nicht die CLI-Versionen, die innerhalb der letzten 30 Tage veröffentlicht wurden. Die Veröffentlichungsdaten für die Images finden Sie unter Versionshinweise für die Azure CLI. Wenn Sie eine nicht unterstützte Version verwenden, werden in der Fehlermeldung die unterstützten Versionen aufgelistet.

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

    Im Bereitstellungsskript werden die Argumente mithilfe des Systemaufrufs CommandLineToArgvW in ein Zeichenfolgenarray unterteilt. Dieser Schritt ist erforderlich, weil die Argumente als Befehlseigenschaft an Azure Container Instances übergeben werden. Die Befehlseigenschaft ist ein Zeichenfolgenarray.

    Wenn die Argumente Escapezeichen enthalten, versehen Sie die Zeichen mit doppelten Escapezeichen. In der vorherigen Bicep-Beispielsyntax wird beispielsweise das Argument -name \"John Dole\" verwendet. Die Zeichenfolge mit Escapezeichen lautet -name \\"John Dole\\".

    Wenn Sie einen Bicep-Parameter des Typs object 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 Anführungszeichen (") durch Anführungszeichen mit doppelten Escapezeichen (\\") zu ersetzen. Beispiel:

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

    Weitere Informationen finden Sie in der Bicep-Beispieldatei.

  • scriptContent: Geben Sie den Skriptinhalt an. Es kann sich um ein Inlineskript oder eine externe Skriptdatei handeln, die Sie mithilfe der loadTextContent-Funktion importieren. Weitere Informationen finden Sie weiter unten in diesem Artikel unter Inlinedatei und externe Datei. Wenn Sie ein externes Skript ausführen möchten, verwenden Sie stattdessen primaryScriptUri.

  • primaryScriptUri: Geben Sie eine öffentlich zugängliche URL zum primären Bereitstellungsskript mit unterstützten Dateierweiterungen an. Weitere Informationen finden Sie weiter unten in diesem Artikel 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 weiter unten in diesem Artikel unter Inlinedatei und externe Datei.

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

  • forceUpdateTag: Wenn Sie diesen Wert zwischen Bicep-Dateibereitstellungen ändern, wird die erneute Ausführung des Bereitstellungsskripts erzwungen. Wenn Sie die Funktion newGuid() oder utcNow() nutzen, können Sie sie nur im Standardwert für einen Parameter verwenden. Weitere Informationen finden Sie weiter unten in diesem Artikel unter Mehrmaliges Ausführen eines Skripts.

  • cleanupPreference. Geben Sie das Verfahren zum Bereinigen der beiden unterstützenden Bereitstellungsressourcen (Speicherkonto und Containerinstanz) an, wenn die Skriptausführung in einen Endzustand gelangt. Die Standardeinstellung ist Always. Damit werden die unterstützenden Ressourcen unabhängig vom Endzustand (Succeeded, Failed oder Canceled) gelöscht. Weitere Informationen finden Sie weiter unten in diesem Artikel 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 Stunde (PT1H) und 26 Stunden (PT26H). Diese Eigenschaft wird verwendet, wenn cleanupPreference auf OnExpiration festgelegt ist. Weitere Informationen finden Sie weiter unten in diesem Artikel 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: In diesem wird manuell eine benutzerseitig zugewiesene verwaltete Identität erstellt. Der Identität wird die Berechtigung zum Erstellen von Microsoft Entra-Anwendungen mithilfe der Microsoft Graph-API zugewiesen. Verwenden Sie in der Bicep-Datei ein Bereitstellungsskript, um eine Microsoft Entra-Anwendung und einen Dienstprinzipal zu erstellen und die Objekt-IDs und die Client-ID auszugeben.

Inlinedatei und externe Datei

Ein Bereitstellungsskript kann sich in einer Bicep-Datei befinden oder extern als separate Datei gespeichert werden.

Verwenden eines Inlineskripts

Die folgende Bicep-Datei zeigt, wie ein Inlineskript verwendet wird:

param name string = 'John Dole'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'inlineCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    arguments: name
    scriptContent: 'set -e; output="Hello $1"; echo $output'
    retentionInterval: 'P1D'
  }
}

Fügen Sie set -e in Ihr Skript ein, um das sofortige Beenden zu aktivieren, wenn ein Befehl einen anderen Status als NULL zurückgibt. In dieser Übung werden Fehlerdebuggingprozesse optimiert.

Laden einer Skriptdatei

Verwenden Sie die loadTextContent-Funktion, um eine Skriptdatei als Zeichenfolge abzurufen. Mit dieser Funktion können Sie das Skript in einer externen Datei verwalten und darauf als Bereitstellungsskript zugreifen. Der für die Skriptdatei bereitgestellte Pfad ist relativ zur Bicep-Datei.

Sie können das Inlineskript aus der vorherigen Bicep-Datei in eine Datei vom Typ hello.sh extrahieren und die Datei dann in einem Unterordner mit dem Namen scripts platzieren.

output="Hello $1"
echo $output

Anschließend können Sie die vorherige Bicep-Datei wie im folgenden Beispiel überarbeiten:

param name string = 'John Dole'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'loadTextContentCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    arguments: name
    scriptContent: loadTextContent('./scripts/hello.sh')
    retentionInterval: 'P1D'
  }
}

Verwenden externer Skripts

Sie können externe Skriptdateien anstelle von Inlineskripts verwenden. Es werden nur primäre PowerShell-Skripts mit der Erweiterung .ps1 unterstützt. Bei CLI-Skripts können primäre Skripts beliebige gültige Bash-Skripterweiterungen oder überhaupt keine Erweiterung haben. Um externe Skriptdateien zu verwenden, tauschen Sie scriptContent mit primaryScriptUri aus.

param name string = 'John Dole'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'externalScriptCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    primaryScriptUri: 'https://raw.githubusercontent.com/Azure/azure-docs-bicep-samples/main/samples/deployment-script/hello.sh'
    arguments: '-name ${name}'
    retentionInterval: 'P1D'
  }
}

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

Es ist Ihre Aufgabe, die Integrität der Skripts zu gewährleisten, auf die das Bereitstellungsskript verweist (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. Verwenden Sie die supportingScriptUris-Eigenschaft, um bei Bedarf ein Array von URIs für die unterstützenden Skriptdateien bereitzustellen.

param name string = 'John Dole'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'supportingScriptCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    arguments: name
    scriptContent: 'output="Hello $1"; echo $output; ./hello.sh "$1"'
    supportingScriptUris: [
      'https://raw.githubusercontent.com/Azure/azure-docs-bicep-samples/master/samples/deployment-script/hello.sh'
    ]
    retentionInterval: 'P1D'
  }
}

Sie können unterstützende Skriptdateien sowohl aus Inlineskripts als auch aus primären Skriptdateien aufrufen. 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 einen relativen Pfad, um aus Inlineskripts und primären Skriptdateien auf die unterstützenden Dateien zu verweisen.

Zugreifen auf Azure-Ressourcen

Um auf Azure-Ressourcen zuzugreifen, müssen Sie das identity-Element konfigurieren. Die folgende Bicep-Datei veranschaulicht, wie eine Liste von Azure-Schlüsseltresoren abgerufen wird. Der Verwaltungsidentität für die Benutzerzuweisung muss außerdem die Berechtigung zum Zugreifen auf den Schlüsseltresor gewährt werden.

param identity string
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'listKvCLI'
  location: location
  kind: 'AzureCLI'
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '${identity}': {}
    }
  }
  properties: {
    azCliVersion: '2.52.0'
    scriptContent: 'result=$(az keyvault list); echo $result | jq -c \'{Result: map({id: .id})}\' > $AZ_SCRIPTS_OUTPUT_PATH'
    retentionInterval: 'P1D'
  }
}

output result object = deploymentScript.properties.outputs

Hinweis

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

Arbeiten mit Ausgaben

Der Ansatz für die Behandlung von Ausgaben variiert je nach Typ des verwendeten Skripts: Azure CLI oder Azure PowerShell.

Das Azure CLI-Bereitstellungsskript nutzt eine Umgebungsvariable mit dem Namen AZ_SCRIPTS_OUTPUT_PATH, um den Speicherort der Datei für Skriptausgaben anzugeben. Beim Ausführen eines Bereitstellungsskripts in einer Bicep-Datei konfiguriert die Bash-Shell diese Umgebungsvariable automatisch für Sie. Der vordefinierte Wert ist auf /mnt/azscripts/azscriptoutput/scriptoutputs.json festgelegt.

Die Ausgaben müssen einer gültigen JSON-Zeichenfolgenobjektstruktur entsprechen. Der Inhalt der Datei sollte als Schlüssel-Wert-Paar formatiert werden. Speichern Sie beispielsweise ein Array von Zeichenfolgen als { "MyResult": [ "foo", "bar"] }. Das ausschließliche Speichern der Arrayergebnisse (z. B. [ "foo", "bar" ]) ist ungültig.

param name string = 'John Dole'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'outputCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    arguments: name
    scriptContent: 'jq -n -c --arg st "Hello ${name}" \'{"text": $st}\' > $AZ_SCRIPTS_OUTPUT_PATH'
    retentionInterval: 'P1D'
  }
}

output text string = deploymentScript.properties.outputs.text

Im vorherigen Beispiel wird jq zum Erstellen von Ausgaben verwendet. Das jq-Tool ist in den Containerimages enthalten. Weitere Informationen finden Sie unter Konfigurieren einer Entwicklungsumgebung.

Verwenden von Umgebungsvariablen

Übergeben von sicheren Zeichenfolgen an ein Bereitstellungsskript

Sie können Umgebungsvariablen (EnvironmentVariable) in Ihren Containerinstanzen festlegen, um eine dynamische Konfiguration der Anwendung oder des Skripts bereitzustellen, die bzw. das vom Container ausgeführt wird. Ein Bereitstellungsskript verarbeitet nicht gesicherte und gesicherte Umgebungsvariablen auf dieselbe Weise wie Azure Container Instances. Weitere Informationen finden Sie unter Festlegen von Umgebungsvariablen in Container Instances.

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

param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'passEnvVariablesCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    environmentVariables: [
      {
        name: 'UserName'
        value: 'jdole'
      }
      {
        name: 'Password'
        secureValue: 'jDolePassword'
      }
    ]
    scriptContent: 'echo "Username is :$Username"; echo "Password is: $Password"'
    retentionInterval: 'P1D'
  }
}

Systemdefinierte Umgebungsvariablen

In der folgenden Tabelle sind die systemdefinierten Umgebungsvariablen aufgeführt:

Umgebungsvariable Standardwert (CLI) Standardwert (PowerShell) System-reserviert
AZ_SCRIPTS_AZURE_ENVIRONMENT AzureCloud AzureCloud Nein
AZ_SCRIPTS_CLEANUP_PREFERENCE Always Always Nein
AZ_SCRIPTS_OUTPUT_PATH /mnt/azscripts/azscriptoutput/scriptoutputs.json Nicht zutreffend Ja
AZ_SCRIPTS_PATH_INPUT_DIRECTORY /mnt/azscripts/azscriptinput|/mnt/azscripts/azscriptinput Nicht zutreffend Ja
AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY /mnt/azscripts/azscriptoutput|/mnt/azscripts/azscriptoutput Nicht zutreffend Ja
AZ_SCRIPTS_PATH_USER_SCRIPT_FILE_NAME userscript.sh userscript.ps1 Ja
AZ_SCRIPTS_PATH_PRIMARY_SCRIPT_URI_FILE_NAME primaryscripturi.config primaryscripturi.config Ja
AZ_SCRIPTS_PATH_SUPPORTING_SCRIPT_URI_FILE_NAME supportingscripturi.config supportingscripturi.config Ja
AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME scriptoutputs.json scriptoutputs.json Ja
AZ_SCRIPTS_PATH_EXECUTION_RESULTS_FILE_NAME executionresult.json executionresult.json Ja
AZ_SCRIPTS_USER_ASSIGNED_IDENTITY Nicht zutreffend Nicht zutreffend Nein

Ein Beispiel zur Verwendung von AZ_SCRIPTS_OUTPUT_PATH finden Sie weiter oben in diesem Artikel unter Arbeiten mit Ausgaben.

Verwenden Sie zum Zugreifen auf die Umgebungsvariablen den folgenden Code:

param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'listEnvVariablesCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    scriptContent: 'echo "AZ_SCRIPTS_AZURE_ENVIRONMENT is : $AZ_SCRIPTS_AZURE_ENVIRONMENT",echo "AZ_SCRIPTS_CLEANUP_PREFERENCE	is : $AZ_SCRIPTS_CLEANUP_PREFERENCE",echo "AZ_SCRIPTS_OUTPUT_PATH	is : $AZ_SCRIPTS_OUTPUT_PATH",echo "AZ_SCRIPTS_PATH_INPUT_DIRECTORY is : $AZ_SCRIPTS_PATH_INPUT_DIRECTORY",echo "AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY is : $AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY",echo "AZ_SCRIPTS_PATH_USER_SCRIPT_FILE_NAME is : $AZ_SCRIPTS_PATH_USER_SCRIPT_FILE_NAME",echo "AZ_SCRIPTS_PATH_PRIMARY_SCRIPT_URI_FILE_NAME	is : $AZ_SCRIPTS_PATH_PRIMARY_SCRIPT_URI_FILE_NAME",echo "AZ_SCRIPTS_PATH_SUPPORTING_SCRIPT_URI_FILE_NAME	is : $AZ_SCRIPTS_PATH_SUPPORTING_SCRIPT_URI_FILE_NAME",echo "AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME	is : $AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME",echo "AZ_SCRIPTS_PATH_EXECUTION_RESULTS_FILE_NAME	is : $AZ_SCRIPTS_PATH_EXECUTION_RESULTS_FILE_NAME",echo "AZ_SCRIPTS_USER_ASSIGNED_IDENTITY	is : $AZ_SCRIPTS_USER_ASSIGNED_IDENTITY"'
    retentionInterval: 'P1D'
  }
}

Verwenden eines vorhandenen Speicherkontos

Damit das Skript ausgeführt wird und die Problembehandlung zulässt, benötigen Sie ein Speicherkonto und eine Containerinstanz. Sie können entweder ein vorhandenes Speicherkonto festlegen oder zulassen, dass der Skriptdienst sowohl das Speicherkonto als auch die Containerinstanz automatisch erstellt.

Hier sind die Voraussetzungen für die Verwendung eines vorhandenen Speicherkontos angegeben:

  • In der folgenden Tabelle sind die unterstützten Kontotypen aufgeführt. Die Spalte für Ebenen bezieht sich auf den Wert des Parameters -SkuName oder --sku. Die Spalte für unterstützte Typen bezieht sich auf den Parameter -Kind oder --kind.

    Tarif Unterstützter Typ
    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. Weitere Informationen finden Sie unter Konfigurieren der mindestens erforderlichen Berechtigungen.

  • 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 Bicep-Code hinzu:

param storageAccountName string = 'myStorageAccount'

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  ...
  properties: {
    ...
    storageAccountSettings: {
      storageAccountName: storageAccountName
      storageAccountKey: listKeys(resourceId('Microsoft.Storage/storageAccounts', storageAccountName), '2023-01-01').keys[0].value
    }
  }
}

Ein vollständiges Definitionsbeispiel für Microsoft.Resources/deploymentScripts finden Sie weiter oben in diesem Artikel unter Syntax.

Wenn Sie ein vorhandenes Speicherkonto nutzen, erstellt der Skriptdienst eine Dateifreigabe mit einem eindeutigen Namen. Informationen dazu, wie der Skriptdienst die Dateifreigabe bereinigt, finden Sie weiter unten in diesem Artikel unter Bereinigen von Bereitstellungsskriptressourcen.

Konfigurieren einer Containerinstanz

Im Bereitstellungsskript muss eine neue Azure-Containerinstanz angegeben werden. Sie können keine vorhandene Containerinstanz angeben. Sie können jedoch den Gruppennamen des Containers mithilfe von containerGroupName anpassen. Wenn Sie keinen Gruppennamen angeben, wird er automatisch generiert. Für die Erstellung dieser Containerinstanz sind zusätzliche Konfigurationen erforderlich. Weitere Informationen finden Sie unter Konfigurieren der mindestens erforderlichen Berechtigungen.

Sie können auch subnetId-Werte für die Ausführung des Bereitstellungsskripts in einem privaten Netzwerk angeben. Weitere Informationen finden Sie unter Zugreifen auf ein privates virtuelles Netzwerk.

param containerGroupName string = 'mycustomaci'
param subnetId string = '/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/myResourceGroup/providers/Microsoft.Network/virtualNetworks/myVnet/subnets/mySubnet'

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  ...
  properties: {
    ...
    containerSettings: {
      containerGroupName: containerGroupName
      subnetIds: [
        {
          id: subnetId
        }
      ]
    }
  }
}

Mehrmaliges Ausführen eines 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 Bicep-Datei erneut bereitstellen.

Der Bereitstellungsskriptdienst vergleicht die Ressourcennamen in der Bicep-Datei 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 Funktion utcNow als Ressourcennamen oder als Teil des Ressourcennamens. Sie können die utcNow-Funktion nur für den Standardwert eines Parameters verwenden.

    Wenn Sie den Ressourcennamen ändern, wird eine neue deploymentScripts-Ressource erstellt. Diese ist sinnvoll, um den Verlauf der Skriptausführung zu protokollieren.

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

Schreiben Sie Bereitstellungsskripts, um Idempotenz zu gewährleisten, sodass versehentliche Wiederholungen nicht zu Systemänderungen führen. Wenn Sie beispielsweise eine Azure-Ressource über das Bereitstellungsskript erstellen, überprüfen Sie vor der Erstellung, ob diese vorhanden ist, um sicherzustellen, dass das Skript entweder erfolgreich ist oder eine redundante Ressourcenerstellung vermeidet.

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 Bicep-Datei 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.

Bereinigen von Bereitstellungsskriptressourcen

Die beiden automatisch erstellten Unterstützungsressourcen können die deploymentScript-Ressource nie überdauern, es sei denn, sie werden durch Fehler gelöscht. Die cleanupPreference-Eigenschaft steuert den Lebenszyklus der unterstützenden Ressourcen. Die retentionInterval-Eigenschaft steuert den Lebenszyklus der deploymentScript-Ressource. Hier erfahren Sie, wie Sie diese Eigenschaften verwenden:

  • 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 Endzustand erreicht. Wenn Sie ein vorhandenes Speicherkonto verwenden, 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, speichert der Skriptdienst die Ergebnisse der Skriptausführung (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 Sie ein vorhandenes Speicherkonto verwenden, entfernt der Skriptdienst die Dateifreigabe nur bei erfolgreicher Skriptausführung.

      Wenn die Skriptausführung nicht erfolgreich ist, wartet der Skriptdienst, bis der retentionInterval-Wert abläuft, bevor er die Unterstützungsressourcen und anschließend die Bereitstellungsskriptressource bereinigt.

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

    Die Containerinstanz und das Speicherkonto werden gemäß dem Wert 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 weiter 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 Endzustand festgelegt. Auf ihn kann dann nicht zugegriffen werden, auch wenn Sie ihn noch nicht gelöscht haben.

  • retentionInterval: Geben Sie das Zeitintervall an, für das eine deploymentScript-Ressource aufbewahrt wird, bevor sie abläuft und gelöscht wird.

Hinweis

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

Nächste Schritte

In diesem Artikel haben Sie erfahren, wie Sie Bereitstellungsskriptressourcen erstellen. Weitere Informationen:

Verwenden von Bereitstellungsskripts in Bicep