Sdílet prostřednictvím

Použití implementačních skriptů v Bicep

Pomocí prostředku deploymentScripts můžete spouštět skripty v nasazeních Bicep a kontrolovat výsledky provádění. Tyto skripty vám pomůžou provést následující vlastní kroky:

  • Přidejte uživatele do adresáře.
  • cs-CZ: Provádějte operace datové roviny; například zkopírujte objekty blob nebo zasuňte databázi.
  • Vyhledejte a ověřte licenční klíč.
  • Vytvořte certifikát s vlastním podpisem.
  • Vytvořte objekt v Microsoft Entra ID.
  • Vyhledejte bloky IP adres z vlastního systému.

Mezi výhody skriptů nasazení patří:

  • Snadno se dají kódovat, používat a ladit. Skripty nasazení můžete vyvíjet ve svých oblíbených vývojových prostředích. Skripty mohou být vloženy do souborů Bicep nebo do externích souborů skriptů.
  • Můžete zadat jazyk skriptu a platformu. Skripty nasazení Azure PowerShellu a Azure CLI v linuxovém prostředí se v tuto chvíli podporují.
  • Můžete povolit předávání argumentů příkazového řádku do skriptu.
  • Můžete zadat výstupy skriptu a předat je zpět do nasazení.

Prostředek skriptu nasazení je k dispozici pouze v oblastech, ve kterých je k dispozici služba Azure Container Instances. Další informace najdete v tématu Omezení dostupnosti prostředků a kvót pro ACI a produkty dostupné v jednotlivých oblastech.

Služba skriptů nasazení vytvoří dva podpůrné prostředky – účet úložiště a instanci kontejneru – pro spuštění a řešení potíží se skripty. Názvy těchto prostředků se generují pomocí deterministického hash ID prostředku skriptu nasazení s připojenou příponou azscripts (například jgczqtxom5oreazscripts). V důsledku toho může opakované spuštění stejného skriptu nasazení znovu použít stejný účet úložiště.

Ve výjimečných případech se může zobrazit chyba Účet úložiště s názvem <storage-account-name> je již pořízen. K tomu obvykle dochází v případě, že se účet úložiště vytvořený předchozím spuštěním stejného skriptu nasazení úspěšně nevyčistil.

Varování

Obecně platí, že služba tyto podpůrné prostředky po dokončení skriptu nasazení vyčistí. Za tyto zdroje se vám účtují poplatky, dokud se neodstraní. Informace o cenách najdete v tématu Ceny služby Azure Container Instances a ceny služby Azure Blob Storage. Další informace najdete v Vyčištění prostředků skriptu nasazení.

Konfigurace minimálních oprávnění

Pro verzi 2020-10-01 nebo novější se na spouštění skriptů nasazení podílejí dva principály:

  • Hlavní objekt nasazení: Tento hlavní objekt se používá k nasazení souboru Bicep. Vytvoří podkladové prostředky, které jsou potřebné, aby prostředek skriptu nasazení mohl spustit účet úložiště a instanci kontejneru Azure. Pro nakonfiguraci zásady nejmenších oprávnění přiřadit vlastní roli s následujícími vlastnostmi k principálu nasazení.

    {
  "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]"
  ]
}

    Pokud poskytovatelé prostředků Azure Storage a Azure Container Instances nebyli zaregistrovaní, přidejte Microsoft.Storage/register/action a Microsoft.ContainerInstance/register/action.

  • Principál skriptu nasazení: Tento principál se vyžaduje jenom v případě, že se skript nasazení musí ověřit v Azure a volat Azure CLI nebo PowerShell. Instanční objekt skriptu nasazení můžete zadat dvěma způsoby:

    • Specifikujte uživatelsky přiřazenou spravovanou identitu ve vlastnosti identity. Podívejte se na syntaxi prostředku skriptu nasazení. Když zadáte spravovanou identitu přiřazenou uživatelem, služba skriptů zavolá Connect-AzAccount -Identity před vyvoláním skriptu nasazení. Spravovaná identita musí mít požadovaný přístup k dokončení operace ve skriptu. Pro tuto vlastnost je v tuto chvíli podporována pouze uživatelsky přiřazená spravovaná identita identity. Pokud se chcete přihlásit s jinou identitou, použijte druhou metodu v tomto seznamu.
    • Předejte přihlašovací údaje služebního principála jako zabezpečené proměnné prostředí, potom volejte Connect-AzAccount nebo az login ve skriptu nasazení.

    Pokud používáte spravovanou identitu, objekt zabezpečení nasazení potřebuje předdefinované role operátora spravované identity přiřazené k prostředku spravované identity.

Předdefinovaná role není v tuto chvíli přizpůsobená pro konfiguraci oprávnění skriptu nasazení.

Vytváření skriptů nasazení

Následující příklad ukazuje jednoduchý soubor Bicep s prostředkem nasazovacího skriptu. Skript přebírá jeden řetězcový parametr a vytvoří další řetězec:

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: 'echo "The argument is ${name}."; jq -n -c --arg st "Hello ${name}" \'{"text": $st}\' > $AZ_SCRIPTS_OUTPUT_PATH'
    retentionInterval: 'PT1H'
  }
}

output text string = deploymentScript.properties.outputs.text

Další informace o vytváření prostředků skriptu nasazení naleznete v tématu Vývoj skriptu nasazení v Bicep. Pokud chcete vytvořit skripty pro prostředek nasazovacího skriptu, doporučujeme zřídit vyhrazené vývojové prostředí pro skripty, jako je instance kontejneru Azure nebo image Dockeru. Po vývoji a důkladném otestování skriptů můžete integrovat nebo vyvolat soubory skriptu z prostředků skriptu nasazení. Další informace najdete v tématu Konfigurace vývojového prostředí pro skripty nasazení v souborech Bicep.

Uložte skript do souboru inlineScript.bicep a pak pomocí následujících skriptů nasaďte prostředek:

$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 -TemplateFile "inlineScript.bicep"

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

Použití spravované identity

Následující příklad ukazuje, jak používat spravovanou identitu k interakci s Azure z skriptu nasazení:

@description('The location of the resources.')
param location string = resourceGroup().location

@description('The storage account to list blobs from.')
param storageAccountData {
  name: string
  container: string
}

@description('The role id of Storage Blob Data Reader.')
var storageBlobDataReaderRoleId = '2a2b9908-6ea1-4ae2-8e65-a410df84e7d1'

@description('The storage account to read blobs from.')
resource storageAccount 'Microsoft.Storage/storageAccounts@2025-06-01' existing = {
  name: storageAccountData.name
}

@description('The Storage Blob Data Reader Role definition from [Built In Roles](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles).')
resource storageBlobDataReaderRoleDef 'Microsoft.Authorization/roleDefinitions@2022-05-01-preview' existing = {
  scope: subscription()
  name: storageBlobDataReaderRoleId
}

@description('The user identity for the deployment script.')
resource scriptIdentity 'Microsoft.ManagedIdentity/userAssignedIdentities@2025-01-31-preview' = {
  name: 'script-identity'
  location: location
}

@description('Assign permission for the deployment scripts user identity access to the read blobs from the storage account.')
resource dataReaderRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  scope: storageAccount
  name: guid(storageBlobDataReaderRoleDef.id, scriptIdentity.id, storageAccount.id)
  properties: {
    principalType: 'ServicePrincipal'
    principalId: scriptIdentity.properties.principalId
    roleDefinitionId: storageBlobDataReaderRoleDef.id
  }
}

@description('The deployment script.')
resource script 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'script'
  location: location
  kind: 'AzureCLI'
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '${scriptIdentity.id}': {}
    }
  }
  properties: {
    azCliVersion: '2.59.0'
    retentionInterval: 'PT1H'
    arguments: '${storageAccount.properties.primaryEndpoints.blob} ${storageAccountData.container}'
    scriptContent: '''
      #!/bin/bash
      set -e
      az storage blob list --auth-mode login --blob-endpoint $1 --container-name $2
    '''
  }
}

Monitorování a řešení potíží se skriptem nasazení

Když nasazujete skript pro nasazení, potřebujete úložný účet k uložení uživatelského skriptu, výsledků spuštění a souboru stdout. Můžete zadat vlastní účet úložiště. Další informace najdete v tématu Použití existujícího účtu úložiště.

Alternativou k určení vlastního účtu úložiště je nastavit cleanupPreference na OnExpiration. Pak nakonfigurujete retentionInterval dobu trvání, která umožňuje dostatek času ke kontrole výstupů před odebráním účtu úložiště. Další informace najdete v tématu Vyčištění prostředků skriptu nasazení.

cleanupPreference Přidejte vlastnost do předchozího souboru Bicep a nastavte hodnotu na OnExpiration. Výchozí hodnota je Always. Také nastavte rentalInterval na PT1H (jednu hodinu) nebo kratší.

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: 'echo "The argument is ${name}."; jq -n -c --arg st "Hello ${name}" \'{"text": $st}\' > $AZ_SCRIPTS_OUTPUT_PATH'
    cleanupPreference: 'OnExpiration'
    retentionInterval: 'PT1H'
  }
}

output text string = deploymentScript.properties.outputs.text

Po úspěšném nasazení souboru Bicep zkontrolujte výsledky pomocí webu Azure Portal, Azure CLI, Azure PowerShellu nebo rozhraní REST API.

Azure Portal

Po nasazení prostředku skriptu nasazení se prostředek zobrazí ve skupině prostředků v Azure Portal. Na stránce Přehled jsou kromě prostředku nasazovacího skriptu uvedeny dva podpůrné prostředky. Podpůrné prostředky budou odstraněny po vypršení intervalu uchovávání informací.

Všimněte si, že oba podpůrné prostředky mají příponu azscripts v jejich názvech, protože tyto prostředky se vytvářejí automaticky. Druhým způsobem identifikace podpůrných prostředků je použití značek.

Snímek obrazovky se skupinou prostředků nasazovacího skriptu

Ze seznamu vyberte prostředek skriptu nasazení. Na stránce Přehled nasazovacího skriptu se zobrazují důležité informace o prostředku, včetně stavu zřizování a dvou podpůrných prostředků, účtu úložiště a instance kontejneru. V oblasti Protokoly se zobrazí výstupní text ze skriptu.

Snímek obrazovky s informacemi o prostředku skriptu pro nasazení

Výběrem karta Výstupy zobrazíte výstupy skriptu.

Snímek obrazovky s výstupy skriptu nasazení

Vraťte se do skupiny prostředků, vyberte účet úložiště, vyberte Sdílené složky a pak vyberte sdílenou složku s připojenými příkazy azscripts k názvu sdílené složky. V seznamu se zobrazí dvě složky: azscriptinput a azscriptoutput. Výstupní složka obsahuje executionresult.json soubor a výstupní soubor skriptu. Soubor executionresult.json obsahuje chybovou zprávu o spuštění skriptu. Výstupní soubor se vytvoří pouze při úspěšném spuštění skriptu.

Snímek obrazovky s obsahem výstupní složky skriptu nasazení

Vstupní složka obsahuje systémový soubor skriptu a soubor skriptu nasazení uživatele. Soubor skriptu nasazení uživatele můžete nahradit upraveným souborem a znovu spustit skript nasazení z instance kontejneru Azure.

Azure CLI

Pomocí Azure CLI lze spravovat skripty nasazení v rámci předplatného nebo skupiny prostředků.

Výstup příkazu list je podobný tomuto příkladu:

{
  "arguments": "John Dole",
  "azCliVersion": "2.52.0",
  "cleanupPreference": "OnExpiration",
  "containerSettings": {
    "containerGroupName": null
  },
  "environmentVariables": null,
  "forceUpdateTag": null,
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/dsDemo/providers/Microsoft.Resources/deploymentScripts/inlineCLI",
  "identity": null,
  "kind": "AzureCLI",
  "location": "centralus",
  "name": "inlineCLI",
  "outputs": {
    "text": "Hello John Dole"
  },
  "primaryScriptUri": null,
  "provisioningState": "Succeeded",
  "resourceGroup": "dsDemo",
  "retentionInterval": "1:00:00",
  "scriptContent": "echo \"The argument is John Dole.\"; jq -n -c --arg st \"Hello John Dole\" '{\"text\": $st}' > $AZ_SCRIPTS_OUTPUT_PATH",
  "status": {
    "containerInstanceId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/dsDemo/providers/Microsoft.ContainerInstance/containerGroups/jgczqtxom5oreazscripts",
    "endTime": "2023-12-11T20:20:12.149468+00:00",
    "error": null,
    "expirationTime": "2023-12-11T21:20:12.149468+00:00",
    "startTime": "2023-12-11T20:18:26.674492+00:00",
    "storageAccountId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/dsDemo/providers/Microsoft.Storage/storageAccounts/jgczqtxom5oreazscripts"
  },
  "storageAccountSettings": null,
  "supportingScriptUris": null,
  "systemData": {
    "createdAt": "2023-12-11T19:45:32.239063+00:00",
    "createdBy": "johndole@contoso.com",
    "createdByType": "User",
    "lastModifiedAt": "2023-12-11T20:18:26.183565+00:00",
    "lastModifiedBy": "johndole@contoso.com",
    "lastModifiedByType": "User"
  },
  "tags": null,
  "timeout": "1 day, 0:00:00",
  "type": "Microsoft.Resources/deploymentScripts"
}

Azure PowerShell

Pomocí Azure PowerShellu můžete spravovat skripty nasazení na úrovni předplatného nebo úrovni skupiny prostředků:

Výstup Get-AzDeploymentScript je podobný tomuto příkladu:

Name                : inlinePS
Id                  : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/dsDemo/providers/Microsoft.Resources/deploymentScripts/inlinePS
ResourceGroupName   : dsDemo
Location            : centralus
SubscriptionId      : aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e
ProvisioningState   : Succeeded
Identity            :
ScriptKind          : AzurePowerShell
AzPowerShellVersion : 14.0
StartTime           : 12/11/2023 9:45:50 PM
EndTime             : 12/11/2023 9:46:59 PM
ExpirationDate      : 12/11/2023 10:46:59 PM
CleanupPreference   : OnExpiration
StorageAccountId    : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/dsDemo/providers/Microsoft.Storage/storageAccounts/ee5o4rmoo6ilmazscripts
ContainerInstanceId : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/dsDemo/providers/Microsoft.ContainerInstance/containerGroups/ee5o4rmoo6ilmazscripts
Outputs             :
                      Key                 Value
                      ==================  ==================
                      text                Hello John Dole.

RetentionInterval   : PT1H
Timeout             : P1D

REST API

Rozhraní REST API umožňuje získat informace o prostředku skriptu pro nasazení na úrovni skupiny prostředků a na úrovni předplatného.

/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

Následující příklad používá ARMClient. ARMClient není podporovaný nástroj Microsoftu.

armclient login
armclient get /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/myrg/providers/microsoft.resources/deploymentScripts/myDeployementScript?api-version=2020-10-01

Výstup je podobný tomuto příkladu:

{
  "kind": "AzureCLI",
  "identity": null,
  "location": "centralus",
  "systemData": {
    "createdAt": "2023-12-11T19:45:32.239063+00:00",
    "createdBy": "johndole@contoso.com",
    "createdByType": "User",
    "lastModifiedAt": "2023-12-11T20:18:26.183565+00:00",
    "lastModifiedBy": "johndole@contoso.com",
    "lastModifiedByType": "User"
  },
  "properties": {
    "provisioningState": "Succeeded",
    "azCliVersion": "2.52.0",
    "scriptContent": "echo \"The argument is John Dole.\"; jq -n -c --arg st \"Hello John Dole\" '{\"text\": $st}' > $AZ_SCRIPTS_OUTPUT_PATH",
    "arguments": "John Dole",
    "retentionInterval": "1:00:00",
    "timeout": "1 day, 0:00:00",
    "containerSettings": {
      "containerGroupName": null
    },
    "status": {
      "containerInstanceId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/dsDemo/providers/Microsoft.ContainerInstance/containerGroups/jgczqtxom5oreazscripts",
      "endTime": "2023-12-11T20:20:12.149468+00:00",
      "error": null,
      "expirationTime": "2023-12-11T21:20:12.149468+00:00",
      "startTime": "2023-12-11T20:18:26.674492+00:00",
      "storageAccountId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/dsDemo/providers/Microsoft.Storage/storageAccounts/jgczqtxom5oreazscripts"
    },
    "outputs": {
      "text": "Hello John Dole"
    },
    "cleanupPreference": "OnSuccess"
  },
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/dsDemo/providers/Microsoft.Resources/deploymentScripts/inlineCLI",
  "type": "Microsoft.Resources/deploymentScripts",
  "name": "inlineCLI",
}

Následující rozhraní REST API vrátí protokol:

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

Funguje pouze před odstraněním prostředků skriptu nasazení.

Kódy chyb skriptu nasazení

Následující tabulka uvádí kódy chyb pro skript nasazení:

Kód chyby Popis
DeploymentScriptInvalidOperation Definice skriptu nasazení prostředku v souboru Bicep obsahuje neplatné názvy vlastností.
DeploymentScriptResourceConflict Prostředek skriptu nasazení nemůžete odstranit, pokud je v netermiálním stavu a spuštění nepřekročilo jednu hodinu. Nebo nemůžete znovu spustit stejný skript nasazení se stejným identifikátorem prostředku (stejné předplatné, název skupiny prostředků a název prostředku), ale současně s jiným obsahem textu skriptu.
DeploymentScriptOperationFailed Operace skriptu nasazení selhala interně. Obraťte se na podporu Microsoftu.
DeploymentScriptStorageAccountAccessKeyNotSpecified Přístupový klíč nebyl zadán pro existující účet úložiště.
DeploymentScriptContainerGroupContainsInvalidContainers Skupina kontejnerů, kterou vytvořila služba skriptu nasazení, byla externě změněna a byly přidány neplatné kontejnery.
DeploymentScriptContainerGroupInNonterminalState Dva nebo více prostředků skriptu nasazení používají stejný název instance kontejneru Azure ve stejné skupině prostředků a jeden z nich ještě nedokončil její spuštění.
DeploymentScriptExistingStorageNotInSameSubscriptionAsDeploymentScript V předplatném, ve kterém se nasazuje skript, se nenachází existující úložiště zadané v nasazení.
DeploymentScriptStorageAccountInvalidKind Existující účet úložiště typu BlobBlobStorage nebo BlobStorage nepodporuje sdílené složky a nelze jej použít.
DeploymentScriptStorageAccountInvalidKindAndSku Stávající účet úložiště nepodporuje sdílené složky. Seznam podporovaných typů účtů úložiště najdete v tématu Použití existujícího účtu úložiště.
DeploymentScriptStorageAccountNotFound Účet úložiště neexistuje nebo ho externí proces nebo nástroj odstranil.
DeploymentScriptStorageAccountWithServiceEndpointEnabled Zadaný účet úložiště má koncový bod služby. Účet úložiště s koncovým bodem služby se nepodporuje.
DeploymentScriptStorageAccountInvalidAccessKey Pro existující účet úložiště byl zadán neplatný přístupový klíč.
DeploymentScriptStorageAccountInvalidAccessKeyFormat Klíč účtu úložiště má neplatný formát. Viz Správa přístupových klíčů účtu úložiště.
DeploymentScriptExceededMaxAllowedTime Doba spuštění skriptu nasazení překročila hodnotu časového limitu zadanou v definici prostředku skriptu nasazení.
DeploymentScriptInvalidOutputs Výstup skriptu nasazení není platný objekt JSON.
DeploymentScriptContainerInstancesServiceLoginFailure Spravovaná identita přiřazená uživatelem se nemohla přihlásit po 10 pokusech v minutových intervalech.
DeploymentScriptContainerGroupNotFound Externí nástroj nebo proces odstranil skupinu kontejnerů, kterou vytvořila služba skriptu nasazení.
DeploymentScriptDownloadFailure Stažení podpůrného skriptu se nezdařilo. Viz Použití podpůrných skriptů.
DeploymentScriptError Uživatelský skript vyvolal chybu.
DeploymentScriptBootstrapScriptExecutionFailed Skript bootstrap vyvolal chybu. Spouštěcí skript je systémový skript, který orchestruje spuštění skriptu nasazení.
DeploymentScriptExecutionFailed Během spouštění skriptu nasazení došlo k neznámé chybě.
DeploymentScriptContainerInstancesServiceUnavailable Služba Azure Container Instances při vytvoření instance kontejneru vyvolala chybu "Služba není k dispozici".
DeploymentScriptContainerGroupInNonterminalState Během vytváření instance kontejneru používal jiný skript nasazení stejný název instance kontejneru ve stejném oboru (stejné předplatné, název skupiny prostředků a název prostředku).
DeploymentScriptContainerGroupNameInvalid Zadaný název instance kontejneru nesplňuje požadavky služby Azure Container Instances. Viz Řešení běžných problémů ve službě Azure Container Instances.

Přístup k privátní virtuální síti

Skripty nasazení můžete spouštět v privátních sítích s některými dalšími konfiguracemi. Další informace najdete v tématu Přístup k privátní virtuální síti ze skriptu nasazení Bicep nebo spuštění skriptu nasazení Bicep soukromě přes privátní koncový bod.

Další kroky

V tomto článku jste se naučili, jak používat skripty nasazení. Pokud chcete prozkoumat témata v tomto článku, přečtěte si:

  • Last updated on