Partager via

Développer un script de déploiement dans Bicep

  • Article

Cet article fournit des exemples pour vous montrer comment développer un script de déploiement dans Bicep.

Les ressources de script de déploiement peuvent avoir une durée de déploiement. Pour un développement et un test efficaces de ces scripts, envisagez de mettre en place un environnement de développement dédié, tel qu’une instance de conteneur Azure (ACI) ou une instance Docker. Pour plus d’informations, consultez Créer un environnement de développement.

Syntaxe

Le fichier Bicep suivant est un exemple de ressource de script de déploiement. Pour plus d’informations, consultez le dernier schéma de script de déploiement.

resource <symbolic-name> 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: '<resource-name>'
  location: resourceGroup().location
  tags: {}
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '<user-assigned-identity-id>': {}
    }
  }
  kind: 'AzureCLI'
  properties: {
    storageAccountSettings: {
      storageAccountName: '<storage-account-name>'
      storageAccountKey: '<storage-account-key>'
    }
    containerSettings: {
      containerGroupName: '<container-group-name>'
      subnetIds: [
        {
          id: '<subnet-id>'
        }
      ]
    }
    environmentVariables: []
    azCliVersion: '2.52.0'
    arguments: '<script-arguments>'
    scriptContent: '''<azure-cli-or-azure-powershell-script>''' // or primaryScriptUri: 'https://raw.githubusercontent.com/Azure/azure-docs-bicep-samples/main/samples/deployment-script/inlineScript.ps1'
    supportingScriptUris: []
    timeout: 'P1D'
    cleanupPreference: 'OnSuccess'
    retentionInterval: 'P1D'
    forceUpdateTag: '1'
  }
}

Dans votre script de déploiement, spécifiez ces valeurs de propriété :

  • tags : spécifiez les balises du script de déploiement. Si le service de script de déploiement crée les deux ressources complémentaires (un compte de stockage et une instance de conteneur), les balises sont passées aux deux ressources. Vous pouvez utiliser les balises pour identifier les ressources. Une autre façon d’identifier ces ressources complémentaires consiste à utiliser leurs suffixes, qui contiennent azscripts. Pour plus d’informations, consultez Surveiller et dépanner les scripts de déploiement.

  • identity : pour l’API de script de déploiement version 2020-10-01 ou ultérieure, une identité managée affectée par l’utilisateur est facultative, sauf si vous devez effectuer des actions propres à Azure dans le script ou si vous exécutez le script de déploiement dans un réseau privé. L’API version 2019-10-01-preview nécessite une identité managée, car le service de script de déploiement s’en sert pour exécuter les scripts.

    Quand vous spécifiez la propriété identity, le service de script appelle Connect-AzAccount -Identity avant d’appeler le script utilisateur. Actuellement, seule une identité managée affectée par l’utilisateur est prise en charge. Pour vous connecter avec une identité différente dans le script de déploiement, vous pouvez appeler Connect-AzAccount. Pour plus d’informations, consultez Configurer les autorisations minimales.

  • kind : spécifiez le type de script (AzurePowerShell ou AzureCLI). En plus de kind, vous devez spécifier la propriété azPowerShellVersion ou azCliVersion.

  • storageAccountSettings: Spécifiez les paramètres pour utiliser un compte de stockage existant. Si storageAccountName n’est pas spécifié, un compte de stockage est créé automatiquement. Pour plus d’informations, consultez Utiliser un compte de stockage existant.

  • containerSettings : personnalisez le nom de l’instance de conteneur Azure. Pour plus d’informations sur la configuration du nom de groupe du conteneur, consultez Configurer une instance de conteneur plus loin dans cet article. Pour plus d’informations sur la configuration de subnetIds pour l’exécution du script de déploiement dans un réseau privé, consultez Accéder à un réseau virtuel privé.

  • environmentVariables : spécifiez les variables d’environnement à passer au script.

  • azPowerShellVersion/azCliVersion : spécifiez la version du module à utiliser.

    Consultez la liste des versions de Azure CLI prises en charge.

    Important

    Le script de déploiement utilise les images CLI disponibles dans le Registre des artefacts Microsoft. En général, la certification d’une image CLI pour un script de déploiement nécessite environ un mois. N’utilisez pas les versions de l’interface CLI publiées au cours des 30 derniers jours. Pour trouver les dates de publication des images, consultez les Notes de publication d’Azure CLI. Si vous utilisez une version non prise en charge, le message d’erreur répertorie les versions prises en charge.

  • arguments : Spécifiez les valeurs de paramètre. Les valeurs sont séparées par des espaces.

    Le script de déploiement fractionne les arguments en tableau de chaînes en appelant l’appel système CommandLineToArgvW. Cette étape est nécessaire, car les arguments sont passés en tant que propriété de commande à Azure Container Instances et la propriété de commande est un tableau de chaînes.

    Si les arguments contiennent des caractères placés dans une séquence d’échappement, utilisez une double séquence d’échappement. Par exemple, dans l’exemple de syntaxe Bicep précédent, l’argument est -name \"John Dole\". La chaîne placée dans une séquence d’échappement est -name \\"John Dole\\".

    Pour passer un paramètre Bicep de type object en tant qu’argument, convertissez l’objet en chaîne à l’aide de la fonction string(), puis utilisez la fonction replace() pour remplacer les guillemets (") par des guillemets placés dans une double séquence d’échappement (\\"). Par exemple :

    replace(string(parameters('tables')), '"', '\\"')

    Pour plus d’informations, consultez exemple de fichier Bicep.

  • scriptContent : Spécifiez le contenu du script. Il peut s’agir d’un script inline ou d’un fichier de script externe que vous avez importé à l’aide de la fonction loadTextContent. Pour plus d’informations, consultez Fichier inline ou externe plus loin dans cet article. Pour exécuter un script externe, utilisez plutôt primaryScriptUri.

  • primaryScriptUri : spécifiez une URL accessible publiquement pour le script de déploiement principal avec les extensions de fichier prises en charge. Pour plus d’informations, consultez Utiliser des scripts externes plus loin dans cet article.

  • primaryScriptUri : spécifiez un tableau d’URL accessibles publiquement pour les fichiers de support qui seront appelés dans supportingScriptUris ou scriptContent. Pour plus d’informations, consultez Fichier inline ou externe plus loin dans cet article.

  • timeout : spécifiez la durée maximale autorisée pour l’exécution du script, au format ISO 8601. La valeur par défaut est P1D.

  • forceUpdateTag : la modification de cette valeur entre les déploiements de fichier Bicep force la réexécution du script de déploiement. Si vous utilisez la fonction newGuid() ou utcNow(), vous ne pouvez l’utiliser que dans la valeur par défaut d’un paramètre. Pour en savoir plus, consultez Exécuter un script plusieurs fois plus loin dans cet article.

  • cleanupPreference. Spécifiez la préférence de nettoyage des deux ressources de déploiement complémentaires (le compte de stockage et l’instance de conteneur) quand l’exécution du script arrive à un état terminal. Le paramètre par défaut est Always, ce qui signifie que les ressources complémentaires sont supprimées quel que soit l’état du terminal (Succeeded, Failed ou Canceled). Pour plus d’informations, consultez Nettoyer les ressources de script de déploiement plus loin dans cet article.

  • retentionInterval : Spécifie l’intervalle pendant lequel le service conserve la ressource du script de déploiement quand l’exécution du script arrive à un état terminal. La ressource du script de déploiement est supprimée à la fin de cette période. La durée est basée sur le modèle ISO 8601. L’intervalle de conservation des données est compris entre 1 heure (PT1H) et 26 heures (PT26H). Vous utilisez cette propriété quand cleanupPreference est défini sur OnExpiration. Pour plus d’informations, consultez Nettoyer les ressources de script de déploiement plus loin dans cet article.

Plus d’exemples

  • Exemple 1 : créez un coffre de clés et utilisez un script de déploiement pour affecter un certificat au coffre de clés.
  • Exemple 2 : créez un groupe de ressources au niveau de l’abonnement, créez un coffre de clés dans le groupe de ressources, puis utilisez un script de déploiement pour affecter un certificat au coffre de clés.
  • Exemple 3 : créez une identité managée affectée par l’utilisateur, attribuez le rôle de contributeur à l’identité au niveau du groupe de ressources, créez un coffre de clés, puis utilisez un script de déploiement pour affecter un certificat au coffre de clés.
  • Exemple 4 : créez manuellement une identité managée affectée par l’utilisateur et attribuez-lui l’autorisation d’utiliser l’API Microsoft Graph pour créer des applications Microsoft Entra. Dans le fichier Bicep, utilisez un script de déploiement pour créer une application Microsoft Entra et un principal de service, et pour générer les ID d’objets et l’ID client en sortie.

Fichier inline ou externe

Un script de déploiement peut résider dans un fichier Bicep ou vous pouvez le stocker en externe sous la forme d’un fichier distinct.

Utiliser un script inline

Le fichier Bicep suivant montre comment utiliser un script inline.

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: 'set -e; output="Hello $1"; echo $output'
    retentionInterval: 'P1D'
  }
}

Incluez set -e dans votre script pour activer la sortie immédiate si une commande retourne un état différent de zéro. Cette pratique simplifie le débogage des erreurs.

Charger un fichier de script

Utilisez la fonction loadTextContent pour récupérer un fichier de script en tant que chaîne. Cette fonction vous permet de conserver le script dans un fichier externe et d’y accéder en tant que script de déploiement. Le chemin d’accès spécifié pour le fichier de script est relatif au fichier Bicep.

Vous pouvez extraire le script inline du fichier Bicep précédent dans un fichier hello.sh, puis placer le fichier dans un sous-dossier appelé scripts.

output="Hello $1"
echo $output

Vous pouvez ensuite réviser le fichier Bicep précédent comme dans l’exemple suivant :

param name string = 'John Dole'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'loadTextContentCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    arguments: name
    scriptContent: loadTextContent('./scripts/hello.sh')
    retentionInterval: 'P1D'
  }
}

Utiliser des scripts externes

Vous pouvez utiliser des fichiers de script externes au lieu de scripts inline. Seuls les scripts PowerShell principaux dotés de l’extension .ps1 sont pris en charge. Pour les scripts CLI, les scripts principaux peuvent porter n’importe quelle extension de script Bash valide ou n’avoir aucune extension du tout. Pour utiliser des fichiers de script externes, remplacez scriptContent par primaryScriptUri.

param name string = 'John Dole'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'externalScriptCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    primaryScriptUri: 'https://raw.githubusercontent.com/Azure/azure-docs-bicep-samples/main/samples/deployment-script/hello.sh'
    arguments: '-name ${name}'
    retentionInterval: 'P1D'
  }
}

Les fichiers de script externe doivent être accessibles. Pour sécuriser vos fichiers de script stockés dans des comptes de stockage Azure, générez un jeton de signature d’accès partagé (SAS) et incluez-le dans l’URI du modèle. Définissez le délai d’expiration de façon à ce qu’il y ait suffisamment de temps pour terminer le déploiement. Pour plus d’informations, consultez Déployer un modèle privé ARM avec un jeton SAS.

Vous êtes chargé de garantir l’intégrité du script référencé par le script de déploiement (à savoir primaryScriptUri ou supportingScriptUris). Référencez uniquement les scripts auxquels vous faites confiance.

Utiliser des scripts de prise en charge

Vous pouvez séparer les logiques complexes en un ou plusieurs fichiers de script de prise en charge. Si nécessaire, utilisez la propriété supportingScriptUris pour fournir un tableau d’URI aux fichiers de script complémentaires.

param name string = 'John Dole'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'supportingScriptCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    arguments: name
    scriptContent: 'output="Hello $1"; echo $output; ./hello.sh "$1"'
    supportingScriptUris: [
      'https://raw.githubusercontent.com/Azure/azure-docs-bicep-samples/master/samples/deployment-script/hello.sh'
    ]
    retentionInterval: 'P1D'
  }
}

Vous pouvez appeler des fichiers de script complémentaires à partir de scripts inline et de fichiers de scripts principaux. Les fichiers de script de prise en charge n’ont aucune restriction quant à l’extension de fichier.

Les fichiers complémentaires sont copiés dans azscripts/azscriptinput au moment de l’exécution. Utilisez un chemin relatif pour référencer les fichiers complémentaires à partir de scripts inline et de fichiers de scripts principaux.

Accéder aux ressources Azure

Pour accéder aux ressources Azure, vous devez configurer l’élément identity. Le fichier Bicep suivant montre comment récupérer une liste de coffres de clés Azure. Vous devez également octroyer à l’identité managée affectée par l’utilisateur l’autorisation d’accéder au coffre de clés.

param identity string
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'listKvCLI'
  location: location
  kind: 'AzureCLI'
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '${identity}': {}
    }
  }
  properties: {
    azCliVersion: '2.52.0'
    scriptContent: 'result=$(az keyvault list); echo $result | jq -c \'{Result: map({id: .id})}\' > $AZ_SCRIPTS_OUTPUT_PATH'
    retentionInterval: 'P1D'
  }
}

output result object = deploymentScript.properties.outputs

Remarque

La logique de nouvelle tentative pour la connexion à Azure est désormais intégrée au script wrapper. Si vous accordez des autorisations dans le même fichier Bicep que vos scripts de déploiement, le service de script de déploiement tente de se connecter pendant 10 minutes (à intervalles de 10 secondes) jusqu’à la réplication de l’attribution de rôle de l’identité managée.

Utiliser des sorties

L’approche de gestion des sorties varie en fonction du type de script que vous utilisez : Azure CLI ou Azure PowerShell.

Le script de déploiement Azure CLI utilise une variable d’environnement nommée AZ_SCRIPTS_OUTPUT_PATH pour indiquer l’emplacement du fichier de sorties de script. Quand vous exécutez un script de déploiement dans un fichier Bicep, l’interpréteur de commandes Bash configure automatiquement cette variable d’environnement pour vous. Sa valeur prédéfinie est /mnt/azscripts/azscriptoutput/scriptoutputs.json.

Les sorties doivent être conformes à une structure d’objet de chaîne JSON valide. Le contenu du fichier doit se présenter sous la forme d’une paire clé-valeur. Par exemple, enregistrez un tableau de chaînes comme suit : { "MyResult": [ "foo", "bar"] }. Le fait de stocker uniquement les résultats du tableau, par exemple [ "foo", "bar" ], n’est pas valide.

param name string = 'John Dole'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'outputCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    arguments: name
    scriptContent: 'jq -n -c --arg st "Hello ${name}" \'{"text": $st}\' > $AZ_SCRIPTS_OUTPUT_PATH'
    retentionInterval: 'P1D'
  }
}

output text string = deploymentScript.properties.outputs.text

L’exemple précédent utilise jq pour construire des sorties. L’outil jq est fourni avec les images conteneur. Pour plus d’informations, consultez Configurer un environnement de développement.

Utiliser des variables d’environnement

Passer des chaînes sécurisées à un script de déploiement

Vous pouvez définir des variables d’environnement (EnvironmentVariable) dans vos instances de conteneur pour fournir une configuration dynamique de l’application ou du script exécuté par le conteneur. Un script de déploiement gère les variables d’environnement sécurisées et non sécurisées de la même manière qu’Azure Container Instances. Pour plus d’informations, consultez Définir des variables d’environnement dans des instances de conteneur.

La taille maximale autorisée pour les variables d’environnement est de 64 Ko.

param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'passEnvVariablesCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    environmentVariables: [
      {
        name: 'UserName'
        value: 'jdole'
      }
      {
        name: 'Password'
        secureValue: 'jDolePassword'
      }
    ]
    scriptContent: 'echo "Username is :$Username"; echo "Password is: $Password"'
    retentionInterval: 'P1D'
  }
}

Variables d’environnement définies par le système

Le tableau suivant liste les variables d’environnement définies par le système :

Variable d’environnement Valeur par défaut (CLI) Valeur par défaut (PowerShell) Réservé au système
AZ_SCRIPTS_AZURE_ENVIRONMENT AzureCloud AzureCloud Non
AZ_SCRIPTS_CLEANUP_PREFERENCE Always Always Non
AZ_SCRIPTS_OUTPUT_PATH /mnt/azscripts/azscriptoutput/scriptoutputs.json Non applicable Oui
AZ_SCRIPTS_PATH_INPUT_DIRECTORY /mnt/azscripts/azscriptinput|/mnt/azscripts/azscriptinput Non applicable Oui
AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY /mnt/azscripts/azscriptoutput|/mnt/azscripts/azscriptoutput Non applicable Oui
AZ_SCRIPTS_PATH_USER_SCRIPT_FILE_NAME userscript.sh userscript.ps1 Oui
AZ_SCRIPTS_PATH_PRIMARY_SCRIPT_URI_FILE_NAME primaryscripturi.config primaryscripturi.config Oui
AZ_SCRIPTS_PATH_SUPPORTING_SCRIPT_URI_FILE_NAME supportingscripturi.config supportingscripturi.config Oui
AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME scriptoutputs.json scriptoutputs.json Oui
AZ_SCRIPTS_PATH_EXECUTION_RESULTS_FILE_NAME executionresult.json executionresult.json Oui
AZ_SCRIPTS_USER_ASSIGNED_IDENTITY Non applicable Non applicable Non

Pour obtenir un exemple d’utilisation de AZ_SCRIPTS_OUTPUT_PATH, consultez Utiliser des sorties plus haut dans cet article.

Pour accéder aux variables d’environnement, utilisez le code suivant.

param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'listEnvVariablesCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    scriptContent: 'echo "AZ_SCRIPTS_AZURE_ENVIRONMENT is : $AZ_SCRIPTS_AZURE_ENVIRONMENT",echo "AZ_SCRIPTS_CLEANUP_PREFERENCE	is : $AZ_SCRIPTS_CLEANUP_PREFERENCE",echo "AZ_SCRIPTS_OUTPUT_PATH	is : $AZ_SCRIPTS_OUTPUT_PATH",echo "AZ_SCRIPTS_PATH_INPUT_DIRECTORY is : $AZ_SCRIPTS_PATH_INPUT_DIRECTORY",echo "AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY is : $AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY",echo "AZ_SCRIPTS_PATH_USER_SCRIPT_FILE_NAME is : $AZ_SCRIPTS_PATH_USER_SCRIPT_FILE_NAME",echo "AZ_SCRIPTS_PATH_PRIMARY_SCRIPT_URI_FILE_NAME	is : $AZ_SCRIPTS_PATH_PRIMARY_SCRIPT_URI_FILE_NAME",echo "AZ_SCRIPTS_PATH_SUPPORTING_SCRIPT_URI_FILE_NAME	is : $AZ_SCRIPTS_PATH_SUPPORTING_SCRIPT_URI_FILE_NAME",echo "AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME	is : $AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME",echo "AZ_SCRIPTS_PATH_EXECUTION_RESULTS_FILE_NAME	is : $AZ_SCRIPTS_PATH_EXECUTION_RESULTS_FILE_NAME",echo "AZ_SCRIPTS_USER_ASSIGNED_IDENTITY	is : $AZ_SCRIPTS_USER_ASSIGNED_IDENTITY"'
    retentionInterval: 'P1D'
  }
}

Utiliser un compte de stockage existant

Pour que le script s’exécute et autorise la résolution des problèmes, vous avez besoin d’un compte de stockage et d’une instance de conteneur. Vous pouvez désigner un compte de stockage existant ou laisser le service de script créer automatiquement le compte de stockage et l’instance de conteneur.

Voici les exigences associées à l’utilisation d’un compte de stockage existant :

  • Le tableau suivant liste les types de comptes pris en charge. La colonne des niveaux fait référence à la valeur du paramètre -SkuName ou --sku. La colonne des types pris en charge fait référence au paramètre -Kind ou --kind.

    Niveau Type pris en charge
    Premium_LRS FileStorage
    Premium_ZRS FileStorage
    Standard_GRS Storage, StorageV2
    Standard_GZRS StorageV2
    Standard_LRS Storage, StorageV2
    Standard_RAGRS Storage, StorageV2
    Standard_RAGZRS StorageV2
    Standard_ZRS StorageV2

    Ces combinaisons prennent en charge les partages de fichiers. Pour plus d’informations, consultezCrée un partage de fichiers Azure et Types de compte de stockage.

  • Les règles de pare-feu pour les comptes de stockage ne sont pas encore prises en charge. Pour plus d’informations, consultez Configurer Pare-feu et réseaux virtuels dans Stockage Azure.

  • Le principal de déploiement doit avoir les autorisations nécessaires pour gérer le compte de stockage, ce qui comprend la lecture, la création et la suppression de partages de fichiers. Pour plus d’informations, consultez Configurer les autorisations minimales.

  • La propriété allowSharedKeyAccess du compte de stockage doit être définie sur true. La seule façon de monter un compte de stockage dans Azure Container Instance(ACI) consiste à utiliser une clé d’accès.

Pour spécifier un compte de stockage existant, ajoutez le code Bicep suivant à l’élément de propriété de Microsoft.Resources/deploymentScripts :

param storageAccountName string = 'myStorageAccount'

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  ...
  properties: {
    ...
    storageAccountSettings: {
      storageAccountName: storageAccountName
      storageAccountKey: listKeys(resourceId('Microsoft.Storage/storageAccounts', storageAccountName), '2023-01-01').keys[0].value
    }
  }
}

Pour obtenir un exemple complet de définition de Microsoft.Resources/deploymentScripts, consultez Syntaxe plus haut dans cet article.

Quand vous utilisez un compte de stockage existant, le service de script crée un partage de fichiers portant un nom unique. Pour savoir comment le service de script nettoie le partage de fichiers, consultez Nettoyer les ressources de script de déploiement.

Configurer une instance de conteneur

Un script de déploiement nécessite une nouvelle instance de conteneur Azure. Vous ne pouvez pas spécifier une instance de conteneur existante. Toutefois, vous pouvez personnaliser le nom de groupe du conteneur en utilisant containerGroupName. Si vous ne spécifiez pas de nom de groupe, il est généré automatiquement. Des configurations supplémentaires sont requises pour la création de cette instance de conteneur. Pour plus d’informations, consultez Configurer les autorisations minimales.

Vous pouvez également spécifier des valeurs subnetId pour exécuter le script de déploiement dans un réseau privé. Pour plus d’informations, consultez Accéder à un réseau virtuel privé.

param containerGroupName string = 'mycustomaci'
param subnetId string = '/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/myResourceGroup/providers/Microsoft.Network/virtualNetworks/myVnet/subnets/mySubnet'

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  ...
  properties: {
    ...
    containerSettings: {
      containerGroupName: containerGroupName
      subnetIds: [
        {
          id: subnetId
        }
      ]
    }
  }
}

Exécuter un script plusieurs fois

L’exécution d’un script de déploiement est une opération idempotente. Si aucune modification n’est apportée aux propriétés de la ressource deploymentScripts, y compris le script inline, le script ne s’exécute pas quand vous redéployez le fichier Bicep.

Le service de script de déploiement compare les noms des ressource du fichier Bicep aux ressources existantes dans le même groupe de ressources. Deux options s’offrent à vous si vous souhaitez exécuter le même script de déploiement plusieurs fois :

  • Sélectionnez le nom de votre ressource deploymentScripts. Par exemple, utilisez la fonction utcNow comme nom de ressource ou comme partie du nom de la ressource. Vous pouvez utiliser la fonction utcNow uniquement dans la valeur par défaut d’un paramètre.

    La modification du nom de la ressource crée une nouvelle ressource deploymentScripts. C’est un moyen pratique pour conserver un historique de l’exécution des scripts.

  • Spécifiez une autre valeur dans la propriété forceUpdateTag. Par exemple, utilisez utcNow comme valeur.

Quand vous écrivez des scripts de déploiement, veillez à garantir l’idempotence de façon à ce que les réexécutions accidentelles n’entraînent aucune altération du système. Par exemple, lors de la création d’une ressource Azure via le script de déploiement, validez son absence avant la création pour vous assurer que le script réussit ou évite la création de ressources redondantes.

Utiliser Microsoft Graph dans un script de déploiement

Un script de déploiement peut utiliser Microsoft Graph pour créer et utiliser des objets dans Microsoft Entra ID.

Commandes

Quand vous utilisez des scripts de déploiement Azure CLI, vous pouvez utiliser des commandes du groupe de commandes az ad pour travailler avec des applications, des principaux de service, des groupes et des utilisateurs. Vous pouvez également appeler directement des API Microsoft Graph à l’aide de la commande az rest.

Quand vous utilisez des scripts de déploiement Azure PowerShell, vous pouvez utiliser la cmdlet Invoke-RestMethod pour appeler directement des API Microsoft Graph.

Autorisations

L’identité utilisée par votre script de déploiement doit être autorisée à utiliser l’API Microsoft Graph et doit avoir les autorisations appropriées pour les opérations qu’il effectue. Vous devez autoriser l’identité en dehors de votre fichier Bicep, par exemple en créant au préalable une identité managée affectée par l’utilisateur et en lui attribuant un rôle d’application pour Microsoft Graph. Pour plus d’informations, consultez cet exemple de guide de démarrage rapide.

Nettoyer les ressources de script de déploiement

Les deux ressources complémentaires créées automatiquement ne peuvent jamais survivre à la ressource deploymentScript, sauf si elles sont supprimées à la suite de défaillances. La propriété cleanupPreference contrôle le cycle de vie des ressources complémentaires. La propriété retentionInterval contrôle le cycle de vie de la ressource deploymentScript. Voici comment utiliser ces propriétés :

  • cleanupPreference : spécifie la préférence de nettoyage des deux ressources complémentaires quand l’exécution du script arrive à un état terminal. Les valeurs prises en charge sont :

    • Always : supprime les deux ressources complémentaires une fois que l’exécution du script a atteint un état terminal. Si vous utilisez un compte de stockage existant, le service de script supprime le partage de fichiers créé par le service. Étant donné que la ressource deploymentScripts risque d’être toujours présente après le nettoyage des ressources complémentaires, le service de script conserve les résultats de l’exécution du script (par exemple, stdout), les sorties et la valeur renvoyée avant la suppression des ressources.

    • OnSuccess : supprime les deux ressources complémentaires uniquement quand l’exécution du script réussit. Si vous utilisez un compte de stockage existant, le service de script supprime le partage de fichiers uniquement en cas de réussite de l’exécution du script.

      Si l’exécution du script échoue, le service de script attend l’expiration de la valeur retentionInterval avant de nettoyer les ressources complémentaires, puis la ressource du script de déploiement.

    • OnExpiration : supprime les deux ressources complémentaires uniquement quand le paramètre retentionInterval arrive à expiration. Si vous utilisez un compte de stockage existant, le service de script supprime le partage de fichiers, mais conserve le compte de stockage.

    L’instance de conteneur et le compte de stockage sont supprimés en fonction de la valeur cleanupPreference. Toutefois, si le script échoue et que cleanupPreference n’est pas défini sur Always, le processus de déploiement maintient automatiquement l’exécution du conteneur pendant une heure ou jusqu’au nettoyage du conteneur. Vous pouvez utiliser cette période pour résoudre les problèmes de script.

    Si vous souhaitez laisser le conteneur s’exécuter après des déploiements réussis, ajoutez une étape de mise en veille à votre script. Par exemple, ajoutez Start-Sleep à la fin de votre script. Si vous n’ajoutez pas l’étape de mise en veille, le conteneur est défini sur un état terminal et n’est pas accessible, même si vous ne l’avez pas encore supprimé.

  • retentionInterval : spécifie l’intervalle de temps pendant lequel une ressource deploymentScript est conservée avant son expiration et sa suppression.

Remarque

Nous vous déconseillons d’utiliser le compte de stockage et l’instance de conteneur générés par le service de script à d’autres fins. Les deux ressources peuvent être supprimées en fonction du cycle de vie du script.

Étapes suivantes

Dans cet article, vous avez appris à créer des ressources de script de déploiement. Pour en savoir plus :

Utiliser des scripts de déploiement dans Bicep