Sdílet prostřednictvím

Použití skriptů nasazení v Bicep

  • Článek

Pomocí prostředku deploymentScripts můžete spouštět skripty v nasazeních Bicep a kontrolovat výsledky provádění. Pomocí těchto skriptů můžete provádět vlastní kroky, například:

  • Přidejte uživatele do adresáře.
  • Provádění operací roviny dat; Například zkopírujte objekty blob nebo počáteční databázu.
  • Vyhledejte a ověřte licenční klíč.
  • Vytvořte certifikát podepsaný svým držitelem.
  • 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. V současné době se podporují skripty nasazení Azure PowerShellu a Azure CLI v linuxovém prostředí.
  • 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 Dostupnost prostředků pro službu Azure Container Instances v oblastech Azure.

Upozorňující

Služba skriptů nasazení vyžaduje ke spuštění a řešení potíží se skripty dva další prostředky: účet úložiště a instanci kontejneru. Obecně platí, že služba tyto prostředky po dokončení skriptu nasazení vyčistí. Za tyto prostředky se vám účtují poplatky, dokud se neodeberou.

Informace o cenách najdete v tématu Ceny služby Container Instances a ceny služby Azure Storage. Další informace najdete v tématu Vyčištění prostředků skriptu nasazení.

Školicí materiály

Pokud chcete získat informace o skriptech nasazení pomocí podrobných pokynů, přečtěte si téma Rozšíření šablon Bicep a ARM pomocí skriptů nasazení.

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

Pro verzi 2020-10-01 rozhraní API skriptu nasazení nebo novější se ke spouštění skriptů nasazení podílejí dva objekty zabezpečení:

  • Instanční objekt nasazení: Tento objekt zabezpečení se používá k nasazení souboru Bicep. Vytvoří podkladové prostředky potřebné ke spuštění prostředku skriptu nasazení – účet úložiště a instanci kontejneru Azure. Pokud chcete nakonfigurovat oprávnění s nejnižšími oprávněními, přiřaďte k objektu zabezpečení nasazení vlastní roli s následujícími vlastnostmi:

    {
  "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í, nezapomeňte je přidat Microsoft.Storage/register/action a Microsoft.ContainerInstance/register/action.

  • Instanční objekt skriptu nasazení: Tento objekt zabezpečení 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:

    • Zadejte spravovanou identitu přiřazenou uživatelem identity ve vlastnosti. (Viz syntaxe prostředků 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. V současné době se pro tuto vlastnost podporuje pouze spravovaná identita přiřazená uživatelem identity . Pokud se chcete přihlásit s jinou identitou, použijte druhou metodu v tomto seznamu.
    • Předejte přihlašovací údaje instančního objektu jako zabezpečené proměnné prostředí a pak ve skriptu nasazení volejte Connect-AzAccount nebo az login .

    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.

V současné době není žádná předdefinovaná role 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 skriptu nasazení. 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 Vytváření skriptů nasazení. Při vytváření skriptů pro prostředek skriptu nasazení doporučujeme vytvořit vyhrazené vývojové prostředí skriptu, jako je instance kontejneru Azure nebo image Dockeru. Po vývoji a důkladném testování skriptů můžete soubory skriptu integrovat nebo vyvolat z prostředku skriptu nasazení. Další informace najdete v tématu Konfigurace vývojových prostředí skriptů.

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

$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 v rámci 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@2023-04-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@2023-07-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ž nasadíte prostředek skriptu nasazení, potřebujete účet úložiště k uložení uživatelského skriptu, výsledků spuštění a stdout souboru. 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 nastavení cleanupPreference .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. Je také nastavená 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.

portál Azure

Po nasazení prostředku skriptu nasazení se prostředek zobrazí ve skupině prostředků na webu Azure Portal. Na stránce Přehled jsou uvedené dva podpůrné prostředky kromě prostředku skriptu nasazení. 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, jak identifikovat podpůrné prostředky, je použití značek.

Snímek obrazovky se skupinou prostředků skriptu nasazení

Ze seznamu vyberte prostředek skriptu nasazení. Na stránce Přehled prostředku skriptu nasazení se zobrazují důležité informace o prostředku, jako je stav zřizování a dva podpůrné prostředky (účet úložiště a instance kontejneru). V oblasti Protokoly se zobrazí text tisku ze skriptu.

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

Výběrem možnosti 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 můžete spravovat skripty nasazení v oboru 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í v oboru předplatného nebo 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 : 10.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

Pomocí rozhraní REST API můžete získat informace o prostředku skriptu 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 prostředku skriptu nasazení 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 BlobBlobStorage úložiště typu nebo BlobStorage sdílené složky nepodporuje a nedá se 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 o jednu minutu.
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 Během vytváření instance kontejneru služba Azure Container Instances 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 pomocí koncového bodu služby nebo spuštění skriptu nasazení Bicep soukromě přes privátní koncový bod.

Další kroky

V tomto článku jste zjistili, jak používat skripty nasazení. Další informace najdete v následujících tématech: