Partager via

Utiliser des scripts de déploiement dans Bicep

  • Article

La ressource deploymentScripts vous permet d’exécuter des scripts dans des déploiements Bicep et de passer en revue les résultats d’exécution. Vous pouvez utiliser ces scripts pour effectuer des étapes personnalisées telles que les 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 ;
  • Créez un certificat auto-signé.
  • Créer un objet dans Microsoft Entra ID
  • Rechercher des blocs d’adresses IP à partir d’un système personnalisé

Parmi les avantages des scripts de déploiement, citons 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. À l’heure actuelle, les scripts de déploiement Azure PowerShell et Azure CLI dans l’environnement Linux sont pris en charge.
  • Vous pouvez autoriser le passage d’arguments de ligne de commande au script.
  • Vous pouvez spécifier des sorties de script et les repasser 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 Disponibilité des ressources pour Azure Container Instances dans les régions Azure.

Avertissement

Le service de script de déploiement nécessite deux ressources supplémentaires pour exécuter et dépanner des scripts : un compte de stockage et une instance de conteneur. En général, le service nettoie ces ressources une fois le script de déploiement terminé. Tant qu’elles ne sont pas supprimées, ces ressources engendrent des frais.

Pour plus d’informations sur les prix, consultez Tarification Container Instances et Tarification Stockage Azure. Pour plus d’informations, consultez Nettoyer les ressources de script de déploiement.

Ressources de formation

Si vous préférez découvrir les scripts de déploiement grâce à une aide pas à pas, consultez Étendre des modèles ARM et des fichiers Bicep avec des scripts de déploiement.

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 d’un script de déploiement :

  • Principal de déploiement : ce principal est utilisé pour déployer le fichier Bicep. Il crée les ressources sous-jacentes nécessaires à l’exécution de la ressource de script de déploiement : 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, veillez à ajouter 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 Azure CLI 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 propriété identity. (Consultez la syntaxe des ressources de script de déploiement.) Quand 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. Actuellement, seule une identité managée affectée par l’utilisateur est prise en charge pour la propriété identity. Pour vous connecter avec une identité différente, utilisez la deuxième méthode de cette liste.
    • Passez 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é managée, le principal de déploiement exige que le rôle d’opérateur d’identités managées intégré soit attribué à la ressource d’identité managée.

Actuellement, aucun rôle intégré n’est adapté à la configuration des autorisations de script de déploiement.

Créer des scripts de déploiement

L’exemple suivant illustre 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

Pour plus d’informations sur la création de ressources de script de déploiement, consultez Créer des scripts de déploiement. Lors de la création de scripts pour la ressource de script de déploiement, nous vous conseillons 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é minutieusement 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 des environnements de développement de scripts.

Enregistrez le script dans un fichier inlineScript.bicep, puis déployez la ressource à l’aide du script suivant :

$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 illustre l’utilisation de l’identité managée pour interagir avec Azure depuis le 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@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
    '''
  }
}

Monitorer et dépanner un script de déploiement

Quand 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 avec une durée qui vous laisse suffisamment de temps pour passer en revue 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

Après avoir déployé le fichier Bicep, 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 prise en charge en plus de la ressource de script de déploiement. Les ressources de prise en charge seront supprimées après l’expiration de l’intervalle de rétention.

Notez la présence du suffixe azscripts dans le nom des deux ressources complémentaires, car celles-ci sont créées automatiquement. L’autre façon d’identifier les ressources complémentaires consiste à utiliser des balises.

Capture d’écran d’un groupe de ressources de script de déploiement.

Sélectionnez la ressource de script de déploiement dans la liste. La page Vue d’ensemble d’une ressource de script de déploiement affiche des informations importantes sur la ressource, telles que l’État d’approvisionnement et les deux ressources complémentaires (Compte de stockage et Instance de conteneur). La zone Journaux affiche le texte imprimé du script.

Capture d’écran d’informations sur une ressource de script de déploiement.

Sélectionnez Sorties pour afficher les sorties du script.

Capture d’écran des sorties de script de déploiement.

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 lorsque l’exécution du script aboutit.

Capture d’écran du contenu du dossier de sortie d’un script de déploiement.

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é, puis 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’étendue de l’abonnement ou du groupe de ressources :

La sortie de la commande list 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’étendue de l’abonnement ou du groupe de ressources :

La sortie de 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 : 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

API REST

Vous pouvez utiliser l’API REST pour obtenir des informations sur la ressource de 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 du script de déploiement :

Code d’erreur Description
DeploymentScriptInvalidOperation La définition de la ressource de script de déploiement dans le fichier Bicep contient des noms de propriétés non valides.
DeploymentScriptResourceConflict Vous ne pouvez pas supprimer une ressource de script de déploiement si elle se trouve dans un état non terminal et si l’exécution n’a pas dépassé une heure. Par ailleurs, vous ne pouvez pas réexécuter le même script de déploiement avec le même identificateur de ressource (même abonnement, même nom de groupe de ressources et même nom de ressource) et un contenu de corps de script différent en même temps.
DeploymentScriptOperationFailed L’opération de script de déploiement a échoué en interne. Contactez le Support Microsoft.
DeploymentScriptStorageAccountAccessKeyNotSpecified La clé d’accès n’a pas été spécifiée pour le compte de stockage existant.
DeploymentScriptContainerGroupContainsInvalidContainers Un groupe de conteneurs créé par le service de script de déploiement a été modifié en externe, et des conteneurs non valides ont été ajoutés.
DeploymentScriptContainerGroupInNonterminalState Au moins deux ressources de script de déploiement utilisent le même nom Azure Container Instance dans le même groupe de ressources, et l’une d’entre elles n’a pas encore terminé son exécution.
DeploymentScriptExistingStorageNotInSameSubscriptionAsDeploymentScript Le stockage existant indiqué dans le déploiement est introuvable dans l’abonnement où le script est déployé.
DeploymentScriptStorageAccountInvalidKind Le compte de stockage existant du type BlobBlobStorage ou BlobStorage ne prend pas en charge les partages de fichiers et ne peut pas être utilisé.
DeploymentScriptStorageAccountInvalidKindAndSku Le compte de stockage existant ne prend pas en charge les partages de fichiers. Pour obtenir la liste des types de comptes de stockage pris en charge, consultez Utiliser un compte de stockage existant.
DeploymentScriptStorageAccountNotFound Le compte de stockage n’existe pas ou a été supprimé par un processus ou un outil externe.
DeploymentScriptStorageAccountWithServiceEndpointEnabled Le compte de stockage spécifié possède un point de terminaison de service. Les comptes de stockage comportant un point de terminaison de service ne sont pas pris en charge.
DeploymentScriptStorageAccountInvalidAccessKey Une clé d’accès non valide a été spécifiée pour le compte de stockage existant.
DeploymentScriptStorageAccountInvalidAccessKeyFormat Le format de la clé de compte de stockage n’est pas valide. Consultez Gérer les clés d’accès au compte de stockage.
DeploymentScriptExceededMaxAllowedTime Le temps d’exécution du script de déploiement a dépassé la valeur de délai d’attente spécifiée dans la définition de la ressource de script de déploiement.
DeploymentScriptInvalidOutputs La sortie du script de déploiement n’est pas un objet JSON valide.
DeploymentScriptContainerInstancesServiceLoginFailure L’identité managée affectée par l’utilisateur n’a pas pu se connecter après 10 tentatives à une minute d’intervalle.
DeploymentScriptContainerGroupNotFound Un outil ou un processus externe a supprimé un groupe de conteneurs créé par le service de script de déploiement.
DeploymentScriptDownloadFailure Le téléchargement d’un script complémentaire a échoué. Consultez Utiliser des scripts complémentaires.
DeploymentScriptError Le script utilisateur a généré une erreur.
DeploymentScriptBootstrapScriptExecutionFailed Le script de démarrage a généré une erreur. Le script de démarrage correspond au script système qui orchestre l’exécution du script de déploiement.
DeploymentScriptExecutionFailed Une erreur inconnue s’est produite pendant l’exécution du script de déploiement.
DeploymentScriptContainerInstancesServiceUnavailable Pendant la création d’une instance de conteneur, le service Azure Container Instances a généré une erreur « service non disponible ».
DeploymentScriptContainerGroupInNonterminalState Pendant la création d’une instance de conteneur, un autre script de déploiement a utilisé le même nom d’instance de conteneur dans la même étendue (même abonnement, même nom de groupe de ressources et même nom de ressource).
DeploymentScriptContainerGroupNameInvalid Le nom de l’instance de conteneur spécifié ne répond pas aux exigences d’Azure Container Instances. Consultez Résolution des problèmes courants dans Azure Container Instances.

Accéder à un réseau virtuel privé

Vous pouvez exécuter des scripts de déploiement dans des réseaux privés avec des configurations supplémentaires. Pour plus d’informations, consultez Accéder à un réseau virtuel privé à l’aide du point de terminaison de service 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 plus d'informations, consultez les rubriques suivantes :