Delen via

Implementatiescripts gebruiken in Bicep

  • Artikel

Met behulp van de deploymentScripts-resource kunt u scripts uitvoeren in Bicep-implementaties en uitvoeringsresultaten bekijken. U kunt deze scripts gebruiken om aangepaste stappen uit te voeren, zoals:

  • Gebruikers toevoegen aan een directory.
  • Gegevensvlakbewerkingen uitvoeren; Kopieer bijvoorbeeld blobs of seed een database.
  • Zoek en valideer een licentiesleutel.
  • Maak een zelfondertekend certificaat.
  • Maak een object in Microsoft Entra ID.
  • Zoek IP-adresblokken van een aangepast systeem op.

De voordelen van implementatiescripts zijn:

  • Ze zijn eenvoudig te coden, te gebruiken en fouten op te sporen. U kunt implementatiescripts ontwikkelen in uw favoriete ontwikkelomgevingen. De scripts kunnen worden ingesloten in Bicep-bestanden of in externe scriptbestanden.
  • U kunt de scripttaal en het platform opgeven. Momenteel worden Azure PowerShell- en Azure CLI-implementatiescripts in de Linux-omgeving ondersteund.
  • U kunt het doorgeven van opdrachtregelargumenten aan het script toestaan.
  • U kunt scriptuitvoer opgeven en deze doorgeven aan de implementatie.

De implementatiescriptresource is alleen beschikbaar in de regio's waar Azure Container Instances beschikbaar is. Zie de beschikbaarheid van resources voor Azure Container Instances in Azure-regio's voor meer informatie.

Waarschuwing

De implementatiescriptservice vereist twee extra resources voor het uitvoeren en oplossen van problemen met scripts: een opslagaccount en een containerinstantie. Over het algemeen schoont de service deze resources op nadat het implementatiescript is voltooid. Er worden kosten in rekening gebracht voor deze resources totdat ze worden verwijderd.

Zie Prijzen voor Container Instances en Prijzen voor Azure Storage voor informatie over prijzen. Zie Resources van implementatiescripts opschonen voor meer informatie.

Trainingsmateriaal

Als u liever meer wilt weten over implementatiescripts via stapsgewijze richtlijnen, raadpleegt u Bicep- en ARM-sjablonen uitbreiden met behulp van implementatiescripts.

De minimale machtigingen configureren

Voor implementatiescript-API-versie 2020-10-01 of hoger zijn er twee principals betrokken bij het uitvoeren van implementatiescripts:

  • Implementatie-principal: Deze principal wordt gebruikt om het Bicep-bestand te implementeren. Er worden onderliggende resources gemaakt die vereist zijn om de implementatiescriptresource uit te voeren: een opslagaccount en een Azure-containerinstantie. Als u de machtigingen met minimale bevoegdheden wilt configureren, wijst u een aangepaste rol toe met de volgende eigenschappen aan de implementatie-principal:

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

    Als de resourceproviders van Azure Storage en Azure Container Instances niet zijn geregistreerd, moet u deze toevoegen Microsoft.Storage/register/action en Microsoft.ContainerInstance/register/action.

  • Implementatiescript-principal: deze principal is alleen vereist als het implementatiescript moet worden geverifieerd bij Azure en de Azure CLI of PowerShell moet aanroepen. Er zijn twee manieren om de principal voor het implementatiescript op te geven:

    • Geef een door de gebruiker toegewezen beheerde identiteit op in de identity eigenschap. (Zie de syntaxis van de implementatiescriptresource.) Wanneer u een door de gebruiker toegewezen beheerde identiteit opgeeft, roept Connect-AzAccount -Identity de scriptservice aan voordat u het implementatiescript aanroept. De beheerde identiteit moet de vereiste toegang hebben om de bewerking in het script te voltooien. Op dit moment wordt alleen een door de gebruiker toegewezen beheerde identiteit ondersteund voor de identity eigenschap. Als u zich wilt aanmelden met een andere identiteit, gebruikt u de tweede methode in deze lijst.
    • Geef de referenties van de service-principal door als veilige omgevingsvariabelen en roep vervolgens Connect-AzAccount of az login aan in het implementatiescript.

    Als u een beheerde identiteit gebruikt, heeft de implementatie-principal de ingebouwde rol Managed Identity Operator nodig die is toegewezen aan de beheerde identiteitsresource.

Momenteel is er geen ingebouwde rol afgestemd op het configureren van machtigingen voor implementatiescripts.

Implementatiescripts maken

In het volgende voorbeeld ziet u een eenvoudig Bicep-bestand met een implementatiescriptresource. Het script gebruikt één tekenreeksparameter en maakt een andere tekenreeks.

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

Zie Implementatiescripts maken voor meer informatie over het maken van implementatiescriptresources. Voor het maken van scripts voor de implementatiescriptresource raden we u aan een toegewezen ontwikkelomgeving voor scripts, zoals een Azure-containerinstantie of een Docker-installatiekopie, in te stellen. Nadat u de scripts hebt ontwikkeld en grondig hebt getest, kunt u de scriptbestanden integreren of aanroepen vanuit de implementatiescriptresource. Zie Scriptontwikkelingsomgevingen configureren voor meer informatie.

Sla het script op in een inlineScript.bicep-bestand en implementeer de resource met behulp van het volgende script:

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

Een beheerde identiteit gebruiken

In het volgende voorbeeld ziet u hoe u beheerde identiteit gebruikt om te communiceren met Azure vanuit het implementatiescript.

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

Een implementatiescript bewaken en problemen oplossen

Wanneer u een implementatiescriptresource implementeert, hebt u een opslagaccount nodig om het gebruikersscript, de uitvoeringsresultaten en het stdout bestand op te slaan. U kunt uw eigen opslagaccount opgeven. Zie Een bestaand opslagaccount gebruiken voor meer informatie.

Een alternatief voor het opgeven van uw eigen opslagaccount omvat het instellen cleanupPreference van OnExpiration. Vervolgens configureert retentionInterval u voor een duur die voldoende tijd biedt voor het controleren van de uitvoer voordat het opslagaccount wordt verwijderd. Zie Implementatiescriptresources opschonen voor meer informatie.

Voeg de cleanupPreference eigenschap toe aan het voorgaande Bicep-bestand en stel de waarde in op OnExpiration. De standaardwaarde is Always. rentalInterval Stel ook in op PT1H (één uur) of korter.

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

Nadat u het Bicep-bestand hebt geïmplementeerd, gebruikt u Azure Portal, de Azure CLI, Azure PowerShell of de REST API om de resultaten te controleren.

Azure Portal

Nadat u een implementatiescriptresource hebt geïmplementeerd, wordt de resource vermeld onder de resourcegroep in Azure Portal. De pagina Overzicht bevat de twee ondersteunende resources naast de implementatiescriptresource. De ondersteunende resources worden verwijderd nadat het bewaarinterval is verlopen.

U ziet dat beide ondersteunende resources het achtervoegsel azscripts in hun namen hebben, omdat deze resources automatisch worden gemaakt. De andere manier om de ondersteunende resources te identificeren, is door tags te gebruiken.

Schermopname van een resourcegroep voor een implementatiescript.

Selecteer de implementatiescriptresource in de lijst. Op de pagina Overzicht van een implementatiescriptresource wordt belangrijke informatie weergegeven over de resource, zoals de inrichtingsstatus en de twee ondersteunende resources (opslagaccount en containerinstantie). In het gebied Logboeken wordt de afdruktekst uit het script weergegeven.

Schermopname van informatie over een implementatiescriptresource.

Selecteer Uitvoer om uitvoer van het script weer te geven.

Schermopname van uitvoer van implementatiescripts.

Ga terug naar de resourcegroep, selecteer het opslagaccount, selecteer Bestandsshares en selecteer vervolgens de bestandsshare met azscripts die zijn toegevoegd aan de naam van de share. Er worden twee mappen weergegeven in de lijst: azscriptinput en azscriptoutput. De uitvoermap bevat een executionresult.json-bestand en het uitvoerbestand van het script. Het executionresult.json-bestand bevat het foutbericht over de uitvoering van het script. Het uitvoerbestand wordt alleen gemaakt wanneer u het script uitvoert.

Schermopname van de inhoud van de uitvoermap van een implementatiescript.

De invoermap bevat het scriptbestand van het systeem en het scriptbestand voor gebruikersimplementatie. U kunt het scriptbestand voor gebruikersimplementatie vervangen door een herzien script en het implementatiescript opnieuw uitvoeren vanuit de Azure-containerinstantie.

Azure-CLI

U kunt de Azure CLI gebruiken om implementatiescripts te beheren op het abonnements- of resourcegroepbereik:

De uitvoer van de lijstopdracht is vergelijkbaar met dit voorbeeld:

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

U kunt Azure PowerShell gebruiken om implementatiescripts te beheren binnen het bereik van het abonnement of de resourcegroep:

De Get-AzDeploymentScript uitvoer is vergelijkbaar met dit voorbeeld:

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

U kunt de REST API gebruiken om informatie over de implementatiescriptresource op het niveau van de resourcegroep en het abonnementsniveau op te halen:

/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

In het volgende voorbeeld wordt ARMClient gebruikt. ARMClient is geen ondersteund Microsoft-hulpprogramma.

armclient login
armclient get /subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourcegroups/myrg/providers/microsoft.resources/deploymentScripts/myDeployementScript?api-version=2020-10-01

De uitvoer is vergelijkbaar met dit voorbeeld:

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

De volgende REST API retourneert het logboek:

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

Dit werkt alleen voordat de resources van het implementatiescript worden verwijderd.

Foutcodes voor implementatiescripts

De volgende tabel bevat de foutcodes voor het implementatiescript:

Foutcode Beschrijving
DeploymentScriptInvalidOperation De resourcedefinitie van het implementatiescript in het Bicep-bestand bevat ongeldige eigenschapsnamen.
DeploymentScriptResourceConflict U kunt een implementatiescriptresource niet verwijderen als deze een niet-terminale status heeft en de uitvoering niet langer is dan één uur. Of u kunt hetzelfde implementatiescript niet opnieuw uitvoeren met dezelfde resource-id (hetzelfde abonnement, dezelfde naam van de resourcegroep en de resourcenaam), maar tegelijkertijd andere inhoud van de scripttekst.
DeploymentScriptOperationFailed De implementatiescriptbewerking is intern mislukt. Neem contact op met Microsoft Ondersteuning.
DeploymentScriptStorageAccountAccessKeyNotSpecified De toegangssleutel is niet opgegeven voor het bestaande opslagaccount.
DeploymentScriptContainerGroupContainsInvalidContainers Een containergroep die door de implementatiescriptservice is gemaakt, is extern gewijzigd en er zijn ongeldige containers toegevoegd.
DeploymentScriptContainerGroupInNonterminalState Twee of meer implementatiescriptresources gebruiken dezelfde Naam van het Azure-containerexemplaren in dezelfde resourcegroep en een van deze resources heeft de uitvoering nog niet voltooid.
DeploymentScriptExistingStorageNotInSameSubscriptionAsDeploymentScript De bestaande opslag die in de implementatie wordt geleverd, is niet gevonden in het abonnement waarin het script wordt geïmplementeerd.
DeploymentScriptStorageAccountInvalidKind Het bestaande opslagaccount van het BlobBlobStorage of BlobStorage type biedt geen ondersteuning voor bestandsshares en kan niet worden gebruikt.
DeploymentScriptStorageAccountInvalidKindAndSku Het bestaande opslagaccount biedt geen ondersteuning voor bestandsshares. Zie Een bestaand opslagaccount gebruiken voor een lijst met ondersteunde typen opslagaccounts.
DeploymentScriptStorageAccountNotFound Het opslagaccount bestaat niet, of er is een extern proces of hulpprogramma verwijderd.
DeploymentScriptStorageAccountWithServiceEndpointEnabled Het opgegeven opslagaccount heeft een service-eindpunt. Een opslagaccount met een service-eindpunt wordt niet ondersteund.
DeploymentScriptStorageAccountInvalidAccessKey Er is een ongeldige toegangssleutel opgegeven voor het bestaande opslagaccount.
DeploymentScriptStorageAccountInvalidAccessKeyFormat De sleutel van het opslagaccount heeft een ongeldige indeling. Zie Toegangssleutels voor opslagaccounts beheren.
DeploymentScriptExceededMaxAllowedTime De uitvoeringstijd van het implementatiescript heeft de time-outwaarde overschreden die is opgegeven in de definitie van de implementatiescriptresource.
DeploymentScriptInvalidOutputs De uitvoer van het implementatiescript is geen geldig JSON-object.
DeploymentScriptContainerInstancesServiceLoginFailure De door de gebruiker toegewezen beheerde identiteit kan zich niet aanmelden na tien pogingen met intervallen van één minuut.
DeploymentScriptContainerGroupNotFound Een extern hulpprogramma of proces heeft een containergroep verwijderd die door de implementatiescriptservice is gemaakt.
DeploymentScriptDownloadFailure Downloaden van een ondersteunend script is mislukt. Zie Ondersteunende scripts gebruiken.
DeploymentScriptError Er is een fout opgetreden in het gebruikersscript.
DeploymentScriptBootstrapScriptExecutionFailed Er is een fout opgetreden in het bootstrap-script. Het bootstrap-script is het systeemscript waarmee de uitvoering van het implementatiescript wordt ingedeeld.
DeploymentScriptExecutionFailed Er is een onbekende fout opgetreden tijdens het uitvoeren van het implementatiescript.
DeploymentScriptContainerInstancesServiceUnavailable Tijdens het maken van een containerinstantie heeft de Azure Container Instances-service een fout 'service niet beschikbaar' veroorzaakt.
DeploymentScriptContainerGroupInNonterminalState Tijdens het maken van een containerinstantie gebruikt een ander implementatiescript dezelfde containerinstantienaam in hetzelfde bereik (hetzelfde abonnement, de naam van de resourcegroep en de resourcenaam).
DeploymentScriptContainerGroupNameInvalid De opgegeven naam van het containerexemplaren voldoet niet aan de vereisten voor Azure Container Instances. Zie Veelvoorkomende problemen in Azure Container Instances oplossen.

Toegang tot een virtueel privénetwerk

U kunt implementatiescripts uitvoeren in privénetwerken met enkele aanvullende configuraties. Zie Access a private virtual network using service endpoint or Run Bicep deployment script privately over a private endpoint.

Volgende stappen

In dit artikel hebt u geleerd hoe u implementatiescripts gebruikt. Raadpleeg voor meer informatie: