Créer et publier un spec de modèle

  • 3 minutes

Examinons comment créer et publier un spec de modèle.

Créer un modèle

Pour créer un modèle à utiliser comme spécification de modèle, vous écrivez un modèle Azure Resource Manager (modèle ARM) comme vous le faites normalement. Vous pouvez inclure des paramètres, variables, ressources et sorties.

Vous pouvez utiliser des modèles liés, qui vous permettent de définir des parties de votre déploiement dans des fichiers distincts. Lorsque vous travaillez avec des specs de modèle, les modèles liés peuvent être incorporés dans les specs de modèle et référencés à partir de votre modèle principal.

Il est important que votre modèle soit facile à comprendre et à utiliser pour tous les membres de votre organisation, en particulier ses paramètres. Veillez à utiliser des noms de paramètres clairs et compréhensibles. Utilisez les propriétés de paramètre et les métadonnées de modèle pour fournir des informations sur les valeurs que vous prévoyez d’inclure dans vos paramètres, comme dans cet exemple :

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "environmentType": {
      "type": "string",
      "allowedValues": [
        "Production",
        "NonProduction"
      ],
      "metadata": {
        "description": "The type of the environment to deploy. This will determine the SKUs and cost of the resources."
      }
    },
    "key": {
      "type": "secureString",
      "metadata": {
        "description": "The secret key to use."
      }
    },
    "location": {
      "type": "string",
      "metadata": {
        "description": "The Azure region into which the resources should be deployed."
      }
    },
    "sqlServerCount": {
      "type": "int",
      "maxValue": 5,
      "metadata": {
        "description": "The number of Azure SQL logical servers to create."
      }
    }
  },
  "resources": []
}

Dans l’exemple, les paramètres de modèle utilisent les propriétés allowedValues, maxValueet description pour clarifier les paramètres et l’effet de définition de leurs valeurs. Le modèle inclut également le type secureString pour indiquer que le paramètre key contient des données secrètes.

Il est important que votre modèle soit facile à comprendre et à utiliser pour tous les membres de votre organisation, en particulier les paramètres. Veillez à utiliser des noms de paramètres clairs et compréhensibles. Utilisez des décorateurs de paramètre pour fournir des informations sur les valeurs que vous prévoyez d’inclure dans vos paramètres, comme dans cet exemple :

@description('The type of the environment to deploy. This will determine the SKUs and cost of the resources.')
@allowed([
  'Production'
  'NonProduction'
])
param environmentType string

@secure()
@description('The secret key to use.')
param key string

@description('The Azure region into which the resources should be deployed.')
param location string

@description('The number of Azure SQL logical servers to create.')
@maxValue(5)
param sqlServerCount int

Dans l’exemple, les paramètres de modèle utilisent les @allowed, les @maxValueet les décorateurs @description pour clarifier les paramètres et l’effet de définition de leurs valeurs. Le modèle inclut également le type secure pour indiquer que le décorateur key contient des données secrètes.

Quand un utilisateur déploie un spec de modèle à l’aide du portail Azure, le portail :

  • Affiche le nom et la description du paramètre.
  • Masque l’entrée de texte pour les paramètres sécurisés.
  • Applique les valeurs autorisées, les limites de longueur et les limites de valeur que vous définissez.

Cette capture d’écran illustre l’entrée des valeurs de paramètre :

Screenshot that shows the Azure portal interface for entering parameter values for a template spec deployment.

Il est important de réfléchir à la façon dont les utilisateurs utilisent votre spec de modèle et de s’assurer que vos paramètres sont clairs et compréhensibles.

Publier le spec de modèle dans Azure

Une fois votre modèle écrit, au lieu d’envoyer le modèle à Azure pour le déploiement, vous publiez la spécification du modèle.

Important

Lorsque vous publiez un fichier Bicep en tant que spec de modèle, votre code Bicep est converti en modèle JSON. Le processus de conversion de votre code Bicep en JSON supprime certaines informations de votre fichier Bicep. Par exemple, vos commentaires, les noms symboliques pour les ressources et l’ordre dans lequel vous définissez vos ressources peuvent être absents ou différents en JSON. Cela signifie que vous ne pouvez pas publier facilement un fichier Bicep en tant que spec de modèle, puis obtenir à nouveau le fichier Bicep d’origine (ce qu’on appelle également roundtripping). Il est judicieux de conserver une copie de votre code Bicep d’origine dans un référentiel de code tel que Git, en particulier lorsque vous travaillez avec des specs de modèle.

Pour créer un spec de modèle, utilisez la cmdlet New-AzTemplateSpec. L’exemple suivant montre comment vous pouvez créer un spec de modèle pour votre modèle de compte de stockage :

New-AzTemplateSpec `
  -Name StorageWithoutSAS `
  -Location westus `
  -DisplayName 'Storage account with SAS disabled' `
  -Description 'This template spec creates a storage account, which is preconfigured to disable SAS authentication.' `
  -Version '1.0' `
  -TemplateFile main.bicep

New-AzTemplateSpec `
  -Name StorageWithoutSAS `
  -Location westus `
  -DisplayName 'Storage account with SAS disabled' `
  -Description 'This template spec creates a storage account, which is preconfigured to disable SAS authentication.' `
  -Version '1.0' `
  -TemplateFile azuredeploy.json

Examinons chacun des paramètres :

  • -Name est le nom de ressource du spec de modèle. Il ne peut pas contenir d’espaces.
  • -Location est l’emplacement dans lequel les métadonnées du spec de modèle doivent être créées. Vous pouvez cependant déployer les specs de modèle dans n’importe quelle région.
  • -DisplayName est un nom lisible par l’utilisateur, qui peut inclure des espaces.
  • -Description est une description explicite, que vous pouvez utiliser pour fournir des détails sur le contenu du spec de modèle et quand une personne peut l’utiliser.
  • -Version est la version de la spécification du modèle. Vous en apprendrez plus loin sur les versions de ce module.
  • -TemplateFile est le chemin d’accès au modèle ARM pour lequel le spec de modèle doit être créé.

Pour créer un spec de modèle, utilisez la commande az ts create. L’exemple suivant montre comment vous pouvez créer un spec de modèle pour votre modèle de compte de stockage :

az ts create \
  --name StorageWithoutSAS \
  --location westus \
  --display-name "Storage account with SAS disabled" \
  --description "This template spec creates a storage account, which is preconfigured to disable SAS authentication." \
  --version 1.0 \
  --template-file main.bicep

az ts create \
  --name StorageWithoutSAS \
  --location westus \
  --display-name "Storage account with SAS disabled" \
  --description "This template spec creates a storage account, which is preconfigured to disable SAS authentication." \
  --version 1.0 \
  --template-file azuredeploy.json

Examinons chacun des arguments :

  • --name est le nom de ressource du spec de modèle. Il ne peut pas contenir d’espaces.
  • --location est l’emplacement dans lequel les métadonnées du spec de modèle doivent être créées. Vous pouvez cependant déployer les specs de modèle dans n’importe quelle région.
  • --display-name est un nom lisible par l’utilisateur, qui peut inclure des espaces.
  • --description est une description explicite, que vous pouvez utiliser pour fournir des détails sur le contenu du spec de modèle et quand une personne peut l’utiliser.
  • --version est la version de la spécification du modèle. Vous en apprendrez plus loin sur les versions de ce module.
  • --template-file est le chemin d’accès au modèle ARM pour lequel le spec de modèle doit être créé.

Conseil

Vous pouvez également définir un spec de modèle dans un modèle ARM ! Étant donné qu’un spec de modèle est lui-même une ressource Azure, vous pouvez déployer un modèle qui définit une ressource avec le type Microsoft.Deployments/templateSpecs.