Använda distributionsskript i Bicep

Du kan använda deploymentScripts-resursen för att köra skript under Bicep-distributioner och granska körningsresultat. De här skripten hjälper dig att utföra följande anpassade steg:

• Lägg till användare i en katalog.
• Utför dataplanoperationer; till exempel kopiera blobbar eller plantera 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. Azure PowerShell- och Azure CLI-distributionsskript i Linux-miljön stöds just nu.
• 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 & kvotgränser för ACI- och produkter som är tillgängliga per region.

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 i Microsoft Learn-modulen.

Konfigurera de minsta behörigheterna

För distributionsskriptets API-version 2020-10-01 eller senare, ingår två huvudaktörer i utförandet av distributionsskriptet.

• Distributionsprincip: Den här funktionen används för att distribuera Bicep-filen. Den skapar underliggande resurser som krävs för att distributionsskriptresursen ska kunna köra 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 lägger du till Microsoft.Storage/register/action 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 distributionsskript. När du anger en användartilldelad hanterad identitet anropar skripttjänsten Connect-AzAccount -Identity innan distributionsskriptet anropas. Den hanterade identiteten måste ha den åtkomst som krävs för att slutföra åtgärden i skriptet. Endast en användartilldelad hanterad identitet stöds för den identity egenskapen just nu. 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 distributionshuvudansvarig den inbyggda rollen Hanterad identitetsoperatör som tilldelats den hanterade identitetsresursen.

En inbyggd roll är inte anpassad för att konfigurera behörigheter för distributionsskript just nu.

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

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: '14.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 Utveckla ett distributionsskript i Bicep. 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 utvecklingsmiljö för distributionsskript i Bicep-filer.

Spara skriptet i en inlineScript.bicep- fil och använd sedan följande skript för att distribuera resursen:

$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://free.blessedness.top/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.

Lägg till cleanupPreference-egenskapen i den föregående Bicep-filen och ställ in värdet till OnExpiration. Standardvärdet är Always. Sätt också rentalInterval till PT1H (en timme) eller mindre.

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: '14.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 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 stödjande resurser är att använda tagg.

Välj resursen för distributionsskriptet i listan. Sidan Översikt för en distributionsskriptresurs visar viktig information om resursen, inklusive Etableringstillstånd och de två stödresurserna, Lagringskonto och containerinstans. Området Loggar visar utskriftstexten från skriptet.

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

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.

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

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:

• 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 är liknande detta exempel:

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

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:

Få åtkomst till ett privat virtuellt nätverk

Du kan köra distributionsskript i privata nätverk med några ytterligare konfigurationer. För mer information, se Access a private virtual network from a Bicep deployment script eller Run Bicep deployment script privately over a private endpoint.

Nästa steg

I den här artikeln har du lärt dig hur du använder distributionsskript. Mer information finns i modulen Utöka Bicep- och ARM-mallar med hjälp av distributionsskripten från Microsoft Learn.

Mer information om ämnena i den här artikeln finns i:

• Utveckla ett distributionsskript i Bicep
• Få åtkomst till ett privat virtuellt nätverk från ett Bicep-distributionsskript
• Kör Bicep-distributionsskript privat över en privat slutpunkt
• Konfigurera utvecklingsmiljön för distributionsskript i Bicep-filer