Utiliser des scripts de déploiement dans Bicep

Vous pouvez utiliser la ressource deploymentScripts pour exécuter des scripts dans les déploiements Bicep et passer en revue les résultats d’exécution. Ces scripts vous aident à effectuer les étapes personnalisées suivantes :

• Ajouter des utilisateurs à un annuaire ;
• Effectuer des opérations de plan de données : par exemple, copier des objets blob ou alimenter une base de données ;
• Rechercher et valider une clé de licence ;
• Vous pouvez créer un certificat auto-signé.
• Créez un objet dans Microsoft Entra ID.
• Rechercher des blocs d’adresses IP à partir d’un système personnalisé.

Les avantages des scripts de déploiement sont les suivants :

• Ils sont faciles à coder, à utiliser et à déboguer. Vous pouvez développer des scripts de déploiement dans vos environnements de développement préférés. Les scripts peuvent être incorporés aux fichiers Bicep ou dans des fichiers de script externe.
• Vous pouvez spécifier le langage de script et la plateforme. Les scripts de déploiement Azure PowerShell et Azure CLI dans l’environnement Linux sont pris en charge pour l’instant.
• Vous pouvez permettre la transmission des arguments de ligne de commande au script.
• Vous pouvez spécifier des sorties de script et les renvoyer au déploiement.

La ressource de script de déploiement n'est disponible que dans les régions où Azure Container Instances est disponible. Pour plus d’informations, consultez Les limites de disponibilité des ressources et des quotas pour ACI et Products disponibles par région.

Le service de script de déploiement crée deux ressources de prise en charge ( un compte de stockage et une instance de conteneur) pour exécuter et dépanner des scripts. Les noms de ces ressources sont générés à l’aide d’un hachage déterministe de l’ID de ressource du script de déploiement, avec le suffixe azscripts ajouté (par exemple, jgczqtxom5oreazscripts). Par conséquent, les exécutions répétées du même script de déploiement peuvent réutiliser le même compte de stockage.

Dans de rares cas, vous pouvez rencontrer l’erreur « Le compte de stockage nommé <storage-account-name> est déjà pris ». Cela se produit généralement lorsqu’un compte de stockage créé par une exécution précédente du même script de déploiement n’a pas été nettoyé correctement.

Configurer les autorisations minimales

Pour l’API de script de déploiement version 2020-10-01 ou ultérieure, deux principaux sont impliqués dans l’exécution du script de déploiement :

• Principal de déploiement : ce principal est utilisé pour déployer le fichier Bicep. Il crée des ressources sous-jacentes requises pour que la ressource de script de déploiement exécute un compte de stockage et une instance de conteneur Azure. Pour configurer les autorisations de privilège minimum, affectez un rôle personnalisé avec les propriétés suivantes au principal de déploiement :

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

  Si les fournisseurs de ressources Stockage Azure et Azure Container Instances n’ont pas été inscrits, ajoutez Microsoft.Storage/register/action et Microsoft.ContainerInstance/register/action.

• Principal du script de déploiement : ce principal est requis uniquement si le script de déploiement doit s’authentifier auprès d’Azure et appeler l’instance CLI Azure ou PowerShell. Deux méthodes permettent de spécifier le principal du script de déploiement :

  • Spécifiez une identité managée affectée par l’utilisateur dans la identity propriété ; consultez la syntaxe des ressources de script de déploiement. Lorsque vous spécifiez une identité managée affectée par l’utilisateur, le service de script appelle Connect-AzAccount -Identity avant d’appeler le script de déploiement. L’identité managée doit avoir l’accès requis pour terminer l’opération dans le script. Seule l’identité managée affectée par l’utilisateur est prise en charge pour la propriété identity pour le moment. Pour vous connecter avec une identité différente, utilisez la deuxième méthode de cette liste.
  • Transmettez les informations d’identification du principal de service en tant que variables d’environnement sécurisées, puis appelez Connect-AzAccount ou az login dans le script de déploiement.

  Si vous utilisez une identité gérée, le principal de déploiement a besoin du rôle intégré d’Opérateur d’identités gérées affecté à la ressource d’identité gérée.

Un rôle intégré n’est pas adapté à la configuration des autorisations de script de déploiement pour l’instant.

Créer des scripts de déploiement

L’exemple suivant montre un fichier Bicep simple avec une ressource de script de déploiement. Le script prend un paramètre de chaîne et crée une autre chaîne :

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

Pour plus d’informations sur la création de ressources de script de déploiement, consultez Développer un script de déploiement dans Bicep. Pour créer des scripts pour la ressource de script de déploiement, il est recommandé d’établir un environnement de développement de script dédié tel qu’une instance de conteneur Azure ou une image Docker. Après avoir développé et testé attentivement les scripts, vous pouvez intégrer ou appeler les fichiers de script à partir de la ressource de script de déploiement. Pour plus d’informations, consultez Configurer l’environnement de développement pour les scripts de déploiement dans les fichiers Bicep.

Enregistrez le script dans un fichier inlineScript.bicep , puis utilisez les scripts suivants pour déployer la ressource :

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

Utiliser l’identité managée

L’exemple suivant montre comment utiliser l’identité managée pour interagir avec Azure à partir du script de déploiement :

@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@2025-06-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@2025-01-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
    '''
  }
}

Surveiller et détecter les problèmes des scripts de déploiement

Lorsque vous déployez une ressource de script de déploiement, vous avez besoin d’un compte de stockage pour stocker le script utilisateur, les résultats d’exécution et le fichier stdout. Vous pouvez spécifier votre propre compte de stockage. Pour plus d’informations, consultez Utiliser un compte de stockage existant.

Au lieu de spécifier votre propre compte de stockage, vous pouvez définir cleanupPreference sur OnExpiration. Ensuite, configurez retentionInterval pendant une durée qui vous laisse suffisamment de temps pour examiner les sorties avant la suppression du compte de stockage. Pour plus d’informations, consultez Nettoyer les ressources de script de déploiement.

Ajoutez la propriété cleanupPreference au fichier Bicep précédent et définissez la valeur sur OnExpiration. La valeur par défaut est Always. Définissez également rentalInterval sur PT1H (une heure) ou moins.

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

Une fois le déploiement du fichier Bicep réussi, utilisez le portail Azure, Azure CLI, Azure PowerShell ou l’API REST pour vérifier les résultats.

Portail Azure

Une fois que vous avez déployé une ressource de script de déploiement, la ressource est listée sous le groupe de ressources dans la Portail Azure. La page Vue d’ensemble répertorie les deux ressources de support en complément de la ressource de script de déploiement. Les ressources de support seront supprimées une fois l’intervalle de rétention expirée.

Remarquez que les deux ressources de support comportent le suffixe azscripts dans leur nom, car celles-ci sont créées automatiquement. L’autre moyen d’identifier les ressources de prise en charge consiste à utiliser des balises.

Sélectionnez la ressource de script de déploiement depuis la liste. La page Vue d’ensemble d’une ressource de script de déploiement affiche des informations importantes sur la ressource, notamment l’état d’approvisionnement et les deux ressources de prise en charge, le compte de stockage et l’instance conteneur. La zone Journaux affiche le texte d’impression du script.

Sélectionnez Sorties pour afficher les sorties du script.

Revenez au groupe de ressources, sélectionnez le compte de stockage, sélectionnez Partages de fichiers, puis sélectionnez le partage de fichiers avec azscripts ajouté au nom de partage. Deux dossiers apparaissent dans la liste : azscriptinput et azscriptoutput. Le dossier de sortie contient un fichier executionresult.json et le fichier de sortie du script. Le fichier executionresult.json contient le message d’erreur d’exécution du script. Le fichier de sortie est créé uniquement si vous exécutez le script correctement.

Le dossier d’entrée contient le fichier de script système et le fichier de script de déploiement utilisateur. Vous pouvez remplacer le fichier de script de déploiement utilisateur par un fichier révisé avant de réexécuter le script de déploiement à partir de l’instance de conteneur Azure.

Azure CLI

Vous pouvez utiliser Azure CLI pour gérer les scripts de déploiement au niveau de l’abonnement ou de l’étendue du groupe de ressources :

• az deployment-scripts delete : supprimer un script de déploiement.
• az deployment-scripts list : répertorier tous les scripts de déploiement.
• az deployment-scripts show : récupérer un script de déploiement.
• az deployment-scripts show-log : afficher les journaux du script de déploiement.

La sortie de la commande de liste est similaire à cet exemple :

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

Vous pouvez utiliser Azure PowerShell pour gérer les scripts de déploiement au niveau de l’abonnement ou de l’étendue du groupe de ressources :

• Get-AzDeploymentScript : obtenir ou répertorier les scripts de déploiement.
• Get-AzDeploymentScriptLog : obtenir le journal de l’exécution d’un script de déploiement.
• Remove-AzDeploymentScript : supprimer un script de déploiement et ses ressources associées.
• Save-AzDeploymentScriptLog : enregistrer le journal d’exécution d’un script de déploiement sur le disque.

La sortie Get-AzDeploymentScript est similaire à cet exemple :

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

API REST

Vous pouvez utiliser l’API REST pour obtenir des informations au sujet du script de déploiement au niveau du groupe de ressources et au niveau de l’abonnement :

/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

L’exemple suivant utilise ARMClient. ARMClient n’est pas un outil Microsoft pris en charge.

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

La sortie est similaire à cet exemple :

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

L’API REST suivante retourne le journal :

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

Elle fonctionne uniquement avant la suppression des ressources de script de déploiement.

Codes d’erreur des scripts de déploiement

Le tableau suivant répertorie les codes d’erreur relatifs au script de déploiement :

Accéder à un réseau virtuel privé

Vous pouvez exécuter des scripts de déploiement dans des réseaux privés grâce à des configurations supplémentaires. Pour plus d’informations, consultez Accéder à un réseau virtuel privé à partir d’un script de déploiement Bicep ou exécuter un script de déploiement Bicep en privé sur un point de terminaison privé.

Étapes suivantes

Dans cet article, vous avez appris à utiliser des scripts de déploiement. Pour explorer les rubriques de cet article, consultez :

• Développer un script de déploiement dans Bicep
• Accéder à un réseau virtuel privé à partir d’un script de déploiement Bicep
• Exécuter un script de déploiement Bicep discrètement sur un point de terminaison privé
• Configurer l’environnement de développement pour les scripts de déploiement dans les fichiers Bicep