Použití skriptů nasazení v Bicep

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.

Š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

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

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'inlinePS'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '10.0'
    arguments: '-name ${name}'
    scriptContent: '''
      param([string] $name)
      Write-Host 'The argument is {0}' -f $name
      $output = 'Hello {0}' -f $name
      $DeploymentScriptOutputs = @{}
      $DeploymentScriptOutputs['text'] = $output
    '''
    retentionInterval: 'PT1H'
  }
}

output result 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://video2.skills-academy.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

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

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'inlinePS'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '10.0'
    arguments: '-name ${name}'
    scriptContent: '''
      param([string] $name)
      Write-Output "The argument is {0}." -f $name
      $output = "Hello {0}." -f $name
      $DeploymentScriptOutputs = @{}
      $DeploymentScriptOutputs['text'] = $output
    '''
    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.

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.

Výběrem možnosti Výstupy zobrazíte výstupy skriptu.

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.

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ů:

• az deployment-scripts delete: Odstranění skriptu nasazení
• az deployment-scripts list: Seznam všech skriptů nasazení
• az deployment-scripts show: Načtení skriptu nasazení
• az deployment-scripts show-log: Show deployment script logs.

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ů:

• Get-AzDeploymentScript: Získání nebo výpis skriptů nasazení
• Get-AzDeploymentScriptLog: Získejte protokol spuštění skriptu nasazení.
• Remove-AzDeploymentScript: Odeberte skript nasazení a jeho přidružené prostředky.
• Save-AzDeploymentScriptLog: Uložte protokol spuštění skriptu nasazení na disk.

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í:

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:

• Trénovací modul: Rozšíření šablon ARM pomocí skriptů nasazení
• Vývoj prostředků skriptu nasazení
• Přístup k privátní virtuální síti pomocí koncového bodu služby
• Privátní spuštění skriptu nasazení Bicep přes privátní koncový bod
• Vytváření vývojových prostředí skriptů