Dela via

Använda distributionsskript i Bicep

  • Artikel

Med hjälp av deploymentScripts-resursen kan du köra skript i Bicep-distributioner och granska körningsresultat. Du kan använda dessa skript för att utföra anpassade steg, till exempel:

  • Lägg till användare i en katalog.
  • Utför dataplansåtgärder; Till exempel kopiera blobar eller seed en databas.
  • Leta upp och verifiera en licensnyckel.
  • Skapa ett självsignerat certifikat.
  • Skapa ett objekt i Microsoft Entra-ID.
  • Leta upp IP-adressblock från ett anpassat system.

Fördelarna med distributionsskript är:

  • De är enkla att koda, använda och felsöka. Du kan utveckla distributionsskript i dina favoritmiljöer för utveckling. Skripten kan bäddas in i Bicep-filer eller i externa skriptfiler.
  • Du kan ange skriptspråk och plattform. För närvarande stöds Azure PowerShell- och Azure CLI-distributionsskript i Linux-miljön.
  • Du kan tillåta att kommandoradsargument skickas till skriptet.
  • Du kan ange skriptutdata och skicka tillbaka dem till distributionen.

Distributionsskriptresursen är endast tillgänglig i de regioner där Azure Container Instances är tillgängligt. Mer information finns i Resurstillgänglighet för Azure Container Instances i Azure-regioner.

Varning

Distributionsskripttjänsten kräver två extra resurser för att köra och felsöka skript: ett lagringskonto och en containerinstans. I allmänhet rensar tjänsten dessa resurser när distributionsskriptet har slutförts. Du debiteras avgifter för dessa resurser tills de tas bort.

Prisinformation finns i Prissättning för containerinstanser och Priser för Azure Storage. Mer information finns i Rensa distributionsskriptresurser.

Utbildningsresurser

Om du föredrar att lära dig mer om distributionsskript via stegvis vägledning kan du läsa Utöka Bicep- och ARM-mallar med hjälp av distributionsskript.

Konfigurera de minsta behörigheterna

För api-versionen 2020-10-01 av distributionsskriptet eller senare ingår två huvudnamn i körningen av distributionsskriptet:

  • Distributionsobjekt: Det här huvudkontot används för att distribuera Bicep-filen. Den skapar underliggande resurser som krävs för att distributionsskriptresursen ska kunna köras – ett lagringskonto och en Azure-containerinstans. Om du vill konfigurera behörigheter med minst behörighet tilldelar du en anpassad roll med följande egenskaper till distributionsobjektet:

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

    Om resursprovidrar för Azure Storage och Azure Container Instances inte har registrerats måste du lägga Microsoft.Storage/register/action till och Microsoft.ContainerInstance/register/action.

  • Huvudnamn för distributionsskript: Det här huvudnamnet krävs endast om distributionsskriptet behöver autentiseras till Azure och anropa Azure CLI eller PowerShell. Det finns två sätt att ange distributionsskriptets huvudnamn:

    • Ange en användartilldelad hanterad identitet i egenskapen identity . (Se resurssyntaxen för distributionsskriptet.) När du anger en användartilldelad hanterad identitet anropar Connect-AzAccount -Identity skripttjänsten innan du anropar distributionsskriptet. Den hanterade identiteten måste ha den åtkomst som krävs för att slutföra åtgärden i skriptet. För närvarande stöds endast en användartilldelad hanterad identitet för egenskapen identity . Om du vill logga in med en annan identitet använder du den andra metoden i den här listan.
    • Skicka autentiseringsuppgifterna för tjänstens huvudnamn som säkra miljövariabler och anropa sedan Connect-AzAccount eller az login i distributionsskriptet.

    Om du använder en hanterad identitet behöver distributionsobjektet den inbyggda rollen Hanterad identitetsoperator som tilldelats den hanterade identitetsresursen.

För närvarande är ingen inbyggd roll anpassad för att konfigurera behörigheter för distributionsskript.

Skapa distributionsskript

I följande exempel visas en enkel Bicep-fil med en distributionsskriptresurs. Skriptet tar en strängparameter och skapar en annan sträng.

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

Mer information om hur du skapar distributionsskriptresurser finns i Skapa distributionsskript. För att skapa skript för distributionsskriptresursen rekommenderar vi att du upprättar en dedikerad skriptutvecklingsmiljö, till exempel en Azure-containerinstans eller en Docker-avbildning. När du har utvecklat och testat skripten noggrant kan du integrera eller anropa skriptfilerna från distributionsskriptresursen. Mer information finns i Konfigurera skriptutvecklingsmiljöer.

Spara skriptet i en inlineScript.bicep-fil och distribuera sedan resursen med hjälp av följande skript:

$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 ..."

Använda hanterad identitet

I följande exempel visas hur du använder hanterad identitet för att interagera med Azure inifrån distributionsskriptet.

@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
    '''
  }
}

Övervaka och felsöka ett distributionsskript

När du distribuerar en distributionsskriptresurs behöver du ett lagringskonto för att lagra användarskriptet, körningsresultatet stdout och filen. Du kan ange ett eget lagringskonto. Mer information finns i Använda ett befintligt lagringskonto.

Ett alternativ till att ange ett eget lagringskonto omfattar inställningen cleanupPreference till OnExpiration. Sedan konfigurerar retentionInterval du en varaktighet som ger gott om tid för att granska utdata innan lagringskontot tas bort. Mer information finns i Rensa distributionsskriptresurser.

cleanupPreference Lägg till egenskapen i föregående Bicep-fil och ange värdet till OnExpiration. Standardvärdet är Always. rentalInterval Ange också till PT1H (en timme) eller kortare.

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

När du har distribuerat Bicep-filen använder du Azure Portal, Azure CLI, Azure PowerShell eller REST-API:et för att kontrollera resultatet.

Azure Portal

När du har distribuerat en distributionsskriptresurs visas resursen under resursgruppen i Azure Portal. På sidan Översikt visas de två stödresurserna utöver distributionsskriptresursen. Stödresurserna tas bort när kvarhållningsintervallet upphör att gälla.

Observera att båda stödresurserna har azscripts-suffixet i sina namn eftersom dessa resurser skapas automatiskt. Det andra sättet att identifiera de stödande resurserna är genom att använda taggar.

Skärmbild av en resursgrupp för distributionsskript.

Välj resursen för distributionsskriptet i listan. Sidan Översikt för en distributionsskriptresurs visar viktig information om resursen, till exempel etableringstillstånd och de två stödresurserna (lagringskontot och containerinstansen). Området Loggar visar utskriftstexten från skriptet.

Skärmbild av information om en distributionsskriptresurs.

Välj Utdata för att visa utdata från skriptet.

Skärmbild av distributionsskriptets utdata.

Gå tillbaka till resursgruppen väljer du lagringskontot, väljer Filresurser och välj sedan filresursen med azscripts som läggs till i resursnamnet. Två mappar visas i listan: azscriptinput och azscriptoutput. Utdatamappen innehåller en executionresult.json fil och skriptets utdatafil. Den executionresult.json filen innehåller felmeddelandet för skriptkörning. Utdatafilen skapas bara när du kör skriptet.

Skärmbild av innehållet i distributionsskriptets utdatamapp.

Indatamappen innehåller systemskriptfilen och skriptfilen för användardistribution. Du kan ersätta skriptfilen för användardistribution med en reviderad och köra distributionsskriptet igen från Azure-containerinstansen.

Azure CLI

Du kan använda Azure CLI för att hantera distributionsskript i prenumerations- eller resursgruppsomfånget:

Utdata från listkommandot liknar det här exemplet:

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

Du kan använda Azure PowerShell för att hantera distributionsskript i prenumerations- eller resursgruppsomfånget:

Utdata Get-AzDeploymentScript liknar det här exemplet:

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

Du kan använda REST-API:et för att hämta information om resursen för distributionsskriptet på resursgruppsnivå och prenumerationsnivå:

/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

I följande exempel används ARMClient. ARMClient är inte ett Microsoft-verktyg som stöds.

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

Utdata liknar det här exemplet:

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

Följande REST API returnerar loggen:

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

Det fungerar bara innan resurserna för distributionsskriptet tas bort.

Felkoder för distributionsskript

I följande tabell visas felkoderna för distributionsskriptet:

Felkod beskrivning
DeploymentScriptInvalidOperation Resursdefinitionen för distributionsskriptet i Bicep-filen innehåller ogiltiga egenskapsnamn.
DeploymentScriptResourceConflict Du kan inte ta bort en distributionsskriptresurs om den är i ett icke-terminalt tillstånd och körningen inte har överskridit en timme. Eller så kan du inte köra samma distributionsskript igen med samma resursidentifierare (samma prenumeration, resursgruppsnamn och resursnamn) utan olika innehåll i skripttexten samtidigt.
DeploymentScriptOperationFailed Distributionsskriptåtgärden misslyckades internt. Kontakta Microsofts support.
DeploymentScriptStorageAccountAccessKeyNotSpecified Åtkomstnyckeln har inte angetts för det befintliga lagringskontot.
DeploymentScriptContainerGroupContainsInvalidContainers En containergrupp som distributionsskripttjänsten skapade ändrades externt och ogiltiga containrar lades till.
DeploymentScriptContainerGroupInNonterminalState Två eller flera distributionsskriptresurser använder samma Azure-containerinstansnamn i samma resursgrupp, och en av dem har inte slutfört körningen ännu.
DeploymentScriptExistingStorageNotInSameSubscriptionAsDeploymentScript Den befintliga lagringen som tillhandahålls i distributionen finns inte i prenumerationen där skriptet distribueras.
DeploymentScriptStorageAccountInvalidKind Det befintliga lagringskontot för BlobBlobStorage eller BlobStorage -typen stöder inte filresurser och kan inte användas.
DeploymentScriptStorageAccountInvalidKindAndSku Det befintliga lagringskontot stöder inte filresurser. En lista över typer av lagringskonton som stöds finns i Använda ett befintligt lagringskonto.
DeploymentScriptStorageAccountNotFound Lagringskontot finns inte, eller så har en extern process eller ett verktyg tagit bort det.
DeploymentScriptStorageAccountWithServiceEndpointEnabled Det angivna lagringskontot har en tjänstslutpunkt. Ett lagringskonto med en tjänstslutpunkt stöds inte.
DeploymentScriptStorageAccountInvalidAccessKey En ogiltig åtkomstnyckel har angetts för det befintliga lagringskontot.
DeploymentScriptStorageAccountInvalidAccessKeyFormat Lagringskontonyckeln har ett ogiltigt format. Se Hantera åtkomstnycklar för lagringskonto.
DeploymentScriptExceededMaxAllowedTime Körningstiden för distributionsskriptet överskred tidsgränsvärdet som anges i resursdefinitionen för distributionsskriptet.
DeploymentScriptInvalidOutputs Distributionsskriptets utdata är inte ett giltigt JSON-objekt.
DeploymentScriptContainerInstancesServiceLoginFailure Den användartilldelade hanterade identiteten kunde inte logga in efter 10 försök med intervall på en minut.
DeploymentScriptContainerGroupNotFound Ett externt verktyg eller en process tog bort en containergrupp som distributionsskripttjänsten skapade.
DeploymentScriptDownloadFailure Det gick inte att ladda ned ett stödskript. Se Använda stödskript.
DeploymentScriptError Användarskriptet utlöste ett fel.
DeploymentScriptBootstrapScriptExecutionFailed Bootstrap-skriptet utlöste ett fel. Bootstrap-skriptet är det systemskript som samordnar körningen av distributionsskriptet.
DeploymentScriptExecutionFailed Ett okänt fel uppstod under körningen av distributionsskriptet.
DeploymentScriptContainerInstancesServiceUnavailable När en containerinstans skapades utlöste Tjänsten Azure Container Instances ett "tjänsten är inte tillgänglig".
DeploymentScriptContainerGroupInNonterminalState När en containerinstans skapades använde ett annat distributionsskript samma containerinstansnamn i samma omfång (samma prenumeration, resursgruppsnamn och resursnamn).
DeploymentScriptContainerGroupNameInvalid Det angivna containerinstansnamnet uppfyller inte kraven för Azure Container Instances. Se Felsöka vanliga problem i Azure Container Instances.

Få åtkomst till ett privat virtuellt nätverk

Du kan köra distributionsskript i privata nätverk med några ytterligare konfigurationer. Mer information finns i Access a private virtual network using service endpoint or Run Bicep deployment script privately over a private endpoint (Åtkomst till ett privat virtuellt nätverk med tjänstslutpunkt eller Kör Bicep-distributionsskript privat över en privat slutpunkt).

Nästa steg

I den här artikeln har du lärt dig hur du använder distributionsskript. Mer information finns i: