Créer des fichiers de paramètres pour le déploiement Bicep

  • Article

Plutôt que de passer des paramètres en tant que valeurs incluses dans votre script, vous pouvez utiliser un fichier de paramètres Bicep avec l’extension de .bicepparam fichier ou un fichier de paramètres JSON qui contient les valeurs de paramètre. Cet article explique comment créer des fichiers de paramètres.

Remarque

Le fichier de paramètres Bicep est uniquement pris en charge dans Bicep CLI version 0.18.4 ou ultérieure, Azure CLI version 2.47.0 ou ultérieure et Azure PowerShell version 9.7.1 ou ultérieure.

Un seul fichier Bicep peut être associé à plusieurs fichiers de paramètres Bicep. Toutefois, chaque fichier de paramètres Bicep est destiné à un fichier Bicep particulier. Cette relation est établie à l’aide de l’instruction using dans le fichier de paramètres Bicep.

Vous pouvez compiler des fichiers de paramètres Bicep dans des fichiers de paramètres JSON à déployer avec un fichier Bicep. Voir build-params. Vous pouvez également décompiler un fichier de paramètres JSON dans un fichier de paramètres Bicep. Si vous souhaitez en savoir plus, veuillez consulter la rubrique decompile-params.

Fichier de paramètres

Un fichier de paramètres utilise le format suivant :

using '<path>/<file-name>.bicep'

param <first-parameter-name> = <first-value>
param <second-parameter-name> = <second-value>

Vous pouvez utiliser l’instruction using avec le fichier Bicep, les modèles ARM JSON, les modules Bicep et les spécifications de modèle. Par exemple :

using './main.bicep'
...

using './azuredeploy.json'
...

using 'br/public:storage/storage-account:3.0.1'
...

using 'br:myacr.azurecr.io/bicep/modules/storage:v1'
...

using 'ts:00000000-0000-0000-0000-000000000000/myResourceGroup/storageSpec:1.0'
...

Pour plus d’informations, consultez using, instruction.

Vous pouvez utiliser des expressions avec la valeur par défaut. Par exemple :

using 'main.bicep'

param storageName = toLower('MyStorageAccount')
param intValue = 2 + 2

Vous pouvez référencer des variables d’environnement en tant que valeurs de paramètre. Par exemple :

using './main.bicep'

param intFromEnvironmentVariables = int(readEnvironmentVariable('intEnvVariableName'))

Vous pouvez définir et utiliser des variables. L’interface CLI Bicep version 0.21.X ou ultérieure est nécessaire pour utiliser des variables dans le fichier .bicepparam. Voici quelques exemples :

using './main.bicep'

var storagePrefix = 'myStorage'
param primaryStorageName = '${storagePrefix}Primary'
param secondaryStorageName = '${storagePrefix}Secondary'

using './main.bicep'

var testSettings = {
  instanceSize: 'Small'
  instanceCount: 1
}

var prodSettings = {
  instanceSize: 'Large'
  instanceCount: 4
}

param environmentSettings = {
  test: testSettings
  prod: prodSettings
}

Notez que le fichier de paramètres enregistre les valeurs de paramètre en texte brut. Pour des raisons de sécurité, cette approche n’est pas recommandée pour les valeurs sensibles comme les mots de passe. Si vous devez passer un paramètre avec une valeur sensible, conservez la valeur dans un coffre de clés. Au lieu d’ajouter la valeur sensible à votre fichier de paramètres, utilisez la fonction getSecret pour la récupérer. Pour plus d'informations, consultez Utiliser Azure Key Vault pour transmettre une valeur de paramètre sécurisée pendant le déploiement Bicep.

Formats de types de paramètres

L’exemple suivant illustre les formats de différents types de paramètres : chaîne, entier, booléen, tableau et objet.

using './main.bicep'

param exampleString = 'test string'
param exampleInt = 2 + 2
param exampleBool = true
param exampleArray = [
  'value 1'
  'value 2'
]
param exampleObject = {
  property1: 'value 1'
  property2: 'value 2'
}

Utilisez la syntaxe Bicep pour déclarer des objets et des tableaux.

Nom de fichier

Le fichier de paramètres Bicep a l’extension de fichier ..bicepparam

Pour effectuer un déploiement dans différents environnements, créez plusieurs fichiers de paramètres. Lorsque vous nommez les fichiers de paramètres, identifiez leur utilisation, comme le développement ou la production. Par exemple, utilisez main.dev.bicepparam et main.prod.bicepparam pour déployer des ressources.

Définissez des valeurs de paramètre

Pour déterminer comment définir les noms et les valeurs des paramètres, ouvrez votre fichier Bicep. Consultez la section Paramètres du fichier Bicep. Les exemples suivants illustrent les paramètres d'un fichier Bicep appelé main.bicep.

@maxLength(11)
param storagePrefix string

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
param storageAccountType string = 'Standard_LRS'

Dans le fichier de paramètres, le premier détail à noter est le nom de chaque paramètre. Les noms des paramètres de votre fichier de paramètres doivent correspondre à ceux de votre fichier Bicep.

using 'main.bicep'

param storagePrefix
param storageAccountType

L’instruction using lie le fichier de paramètres Bicep à un fichier Bicep. Si vous souhaitez en savoir plus, veuillez consulter la rubrique Instruction using.

Après avoir tapé le mot clé param dans Visual Studio Code, il vous demande les paramètres disponibles et leurs descriptions à partir du fichier Bicep lié :

Capture d’écran de l’invite des paramètres disponibles.

Lorsque vous pointez sur un nom de param, vous pouvez voir le type de données et la description du paramètre.

Capture d’écran du type et de la description de la donnée paramètre.

Notez le type de paramètre. Les types de paramètres de votre fichier de paramètres doivent utiliser les mêmes types que votre fichier Bicep. Dans cet exemple, les deux types de paramètres sont des chaînes.

using 'main.bicep'

param storagePrefix = ''
param storageAccountType = ''

Vérifiez dans le fichier Bicep les paramètres comportant une valeur par défaut. Si un paramètre a une valeur par défaut, vous pouvez fournir une valeur dans le fichier de paramètres, mais ce n’est pas obligatoire. La valeur du fichier de paramètres remplace la valeur par défaut du fichier Bicep.

using 'main.bicep'

param storagePrefix = '' // This value must be provided.
param storageAccountType = '' // This value is optional. Bicep will use default value if not provided.

Vérifiez les valeurs autorisées du fichier Bicep et les éventuelles restrictions, comme la longueur maximale. Ces valeurs spécifient la plage de valeurs que vous pouvez fournir pour un paramètre. Dans cet exemple, storagePrefix peut avoir un maximum de 11 caractères et storageAccountType doit spécifier une valeur autorisée.

using 'main.bicep'

param storagePrefix = 'storage'
param storageAccountType = 'Standard_ZRS'

Générer un fichier de paramètres

Pour générer un fichier de paramètres, vous avez deux options : via Visual Studio Code ou à l’aide de l’interface CLI Bicep. Les deux méthodes vous permettent de dériver le fichier de paramètres d’un fichier Bicep. Dans Visual Studio Code, consultez Générer un fichier de paramètres. À partir de l’interface CLI Bicep, consultez Générer un fichier de paramètres.

Construire un fichier de paramètres Bicep

À partir de l’interface CLI Bicep, vous pouvez générer un fichier de paramètres Bicep dans un fichier de paramètres JSON. Pour plus d’informations, consultez Créer un fichier de paramètres.

Déployer le fichier Bicep avec le fichier de paramètres

Azure CLI

Depuis Azure CLI, vous pouvez transmettre un fichier de paramètres avec votre déploiement de fichiers Bicep.

Avec Azure CLI version 2.53.0 ou ultérieure et l’interface CLI Bicep version 0.22 ou ultérieure, vous pouvez déployer un fichier Bicep en utilisant un fichier de paramètres Bicep. Avec l’instruction using dans le fichier de paramètres Bicep, vous n’avez pas besoin de fournir le commutateur --template-file quand vous spécifiez un fichier de paramètres Bicep pour le commutateur --parameters.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --parameters storage.bicepparam

Vous pouvez utiliser des paramètres inclus et un fichier de paramètres d’emplacement pendant la même opération de déploiement. Par exemple :

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --parameters storage.bicepparam \
  --parameters storageAccountType=Standard_LRS

Pour plus d'informations, consultez Déployer des ressources à l'aide de Bicep et d'Azure CLI.

Azure PowerShell

À partir de Azure PowerShell, transmettez un fichier de paramètres local à l'aide du paramètre TemplateParameterFile.

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateFile C:\MyTemplates\storage.bicep `
  -TemplateParameterFile C:\MyTemplates\storage.bicepparam

Vous pouvez utiliser des paramètres inclus et un fichier de paramètres d’emplacement pendant la même opération de déploiement. Par exemple :

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateFile C:\MyTemplates\storage.bicep `
  -TemplateParameterFile C:\MyTemplates\storage.bicepparam `
  -storageAccountType Standard_LRS

Pour plus d'informations, consultez Déployer des ressources à l'aide de Bicep et d'Azure PowerShell. Pour déployer des fichiers .bicep, vous avez besoin d’Azure PowerShell version 5.6.0 ou ultérieure.

Priorité des paramètres

Vous pouvez utiliser des paramètres inclus et un fichier de paramètres local pendant la même opération de déploiement. Par exemple, vous pouvez spécifier certaines valeurs dans le fichier de paramètres local et ajouter d’autres valeurs incluses pendant le déploiement. Si vous fournissez des valeurs pour un paramètre à la fois dans le fichier de paramètres local et inclus, la valeur incluse est prioritaire.

Il est possible d’utiliser un fichier de paramètres JSON externe, en indiquant l’URI du fichier. Le fichier de paramètres Bicep externe n’est actuellement pas pris en charge. Quand vous utilisez un fichier de paramètres externe, vous ne pouvez pas transmettre d’autres valeurs, qu’elles soient incluses ou extraites d’un fichier local. Tous les paramètres inline sont ignorés. Fournissez toutes les valeurs de paramètre dans le fichier externe.

Conflits de noms de paramètre

Si votre fichier Bicep inclut un paramètre utilisant le même nom que l'un des paramètres de la commande PowerShell, PowerShell présente le paramètre de votre fichier Bicep avec le suffixe FromTemplate. Par exemple, un paramètre nommé ResourceGroupName dans votre fichier Bicep est en conflit avec le paramètre ResourceGroupName dans la cmdlet New-AzResourceGroupDeployment. Vous êtes invité à fournir une valeur pour ResourceGroupNameFromTemplate. Pour éviter cette confusion, utilisez des noms de paramètres qui ne sont pas utilisés pour les commandes de déploiement.

Étapes suivantes