Använda distributionsskript i Bicep

Artikel
01/03/2024

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

CLI
PowerShell

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

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

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

CLI
PowerShell

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

När du har distribuerat Bicep-filen använder du Azure-portalen, 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-portalen. 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älj lagringskontot, välj 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:

az deployment-scripts delete: Ta bort ett distributionsskript.
az deployment-scripts list: Lista alla distributionsskript.
az deployment-scripts show: Hämta ett distributionsskript.
az deployment-scripts show-log: Visa distributionsskriptloggar.

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/01234567-89AB-CDEF-0123-456789ABCDEF/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/01234567-89AB-CDEF-0123-456789ABCDEF/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/01234567-89AB-CDEF-0123-456789ABCDEF/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:

Get-AzDeploymentScript: Hämta eller lista distributionsskript.
Get-AzDeploymentScriptLog: Hämta loggen för en distributionsskriptkörning.
Remove-AzDeploymentScript: Ta bort ett distributionsskript och dess associerade resurser.
Save-AzDeploymentScriptLog: Spara loggen för en distributionsskriptkörning till disk.

Utdata Get-AzDeploymentScript liknar det här exemplet:

Name                : inlinePS
Id                  : /subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/dsDemo/providers/Microsoft.Resources/deploymentScripts/inlinePS
ResourceGroupName   : dsDemo
Location            : centralus
SubscriptionId      : 01234567-89AB-CDEF-0123-456789ABCDEF
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/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/dsDemo/providers/Microsoft.Storage/storageAccounts/ee5o4rmoo6ilmazscripts
ContainerInstanceId : /subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/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/01234567-89AB-CDEF-0123-456789ABCDEF/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/01234567-89AB-CDEF-0123-456789ABCDEF/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/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/dsDemo/providers/Microsoft.Storage/storageAccounts/jgczqtxom5oreazscripts"
    },
    "outputs": {
      "text": "Hello John Dole"
    },
    "cleanupPreference": "OnSuccess"
  },
  "id": "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/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 Åtkomst till ett privat virtuellt nätverk.

Nästa steg

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