Specs de modèle Azure Resource Manager dans Bicep

  • Article

Une spec de modèle est un type de ressource permettant de stocker un modèle Resource Manager en vue d’un déploiement ultérieur. Ce type de ressource vous permet de partager des modèles Ressource Manager avec d’autres utilisateurs de votre organisation. Comme toute autre ressource Azure, vous pouvez utiliser le contrôle d’accès basé sur les rôles Azure (Azure RBAC) pour partager les specs de modèle. Vous pouvez utiliser Azure CLI ou Azure PowerShell pour créer des specs de modèle en fournissant des fichiers Bicep. Les fichiers Bicep sont transposés en modèles JSON ARM avant d’être stockés. Actuellement, vous ne pouvez pas importer un fichier Bicep à partir du portail Azure pour créer une ressource de spec de modèle.

Microsoft.Resources/templateSpecs est le type de ressource pour les specs de modèle. Il se compose d’un modèle principal et d’un nombre quelconque de modèles liés. Azure stocke en toute sécurité les specs de modèle dans des groupes de ressources. Le modèle principal et les modèles liés doivent être en JSON. Specs de modèle prend en charge le contrôle de version.

Pour déployer la spec de modèle, vous utilisez des outils Azure standard tels que PowerShell, Azure CLI, Portail Azure, REST et d’autres Kits de développement logiciel (SDK) et clients pris en charge. Vous utilisez les mêmes commandes que pour le modèle ou fichier Bicep.

Notes

Pour utiliser des specs de modèle dans Bicep avec Azure PowerShell, vous devez installer la version 6.3.0 ou ultérieure. Pour l’utiliser avec Azure CLI, utilisez la version 2.27.0 ou ultérieure.

Lors de la conception de votre déploiement, tenez toujours compte du cycle de vie des ressources et regroupez dans un seul spec de modèle celles qui partagent un cycle de vie similaire. Par exemple, vos déploiements comprennent plusieurs instances d’Azure Cosmos DB et chaque instance contient ses propres bases de données et conteneurs. Comme les bases de données et les conteneurs ne changent pas beaucoup, vous pouvez créer un spec de modèle pour une instance Cosmos DB, et ses bases de données et conteneurs sous-jacents. Vous pouvez ensuite utiliser des instructions conditionnelles dans le fichier Bicep ainsi que des boucles de copie pour créer plusieurs instances de ces ressources.

Conseil

Le choix entre un registre de modules et des specs de modèle est principalement une question de préférence. Vous devez prendre en compte certaines choses quand vous choisissez entre les deux :

  • Le registre de modules n’est pris en charge que par Bicep. Si vous n’utilisez pas encore Bicep, utilisez les specs de modèle.
  • Le contenu du registre du modules Bicep ne peut être déployé qu’à partir d’un autre fichier Bicep. Les specs de modèle peuvent être déployées directement à partir de l’API, d’Azure PowerShell, d’Azure CLI et du portail Azure. Vous pouvez même utiliser UiFormDefinition pour personnaliser l’expérience de déploiement du portail.
  • Bicep a des fonctionnalités limitées pour incorporer d’autres artefacts de projet (notamment des fichiers qui ne sont ni Bicep ni des modèles ARM. Par exemple, des scripts PowerShell, des scripts d’interface CLI et d’autres fichiers binaires) en utilisant les fonctions loadTextContent et loadFileAsBase64. Les specs de modèle ne peuvent pas empaqueter ces artefacts.

Ressources de formation

Pour en savoir plus sur les specs de modèle et pour obtenir des conseils d’aide pratiques, consultez Publier des bibliothèques de code d’infrastructure réutilisable à l’aide de specs de modèle.

Autorisations requises

Il existe deux rôles intégrés Azure définis pour la spec de modèle :

En outre, vous avez également besoin des autorisations pour le déploiement d’un fichier Bicep. Consultez Déployer - CLI ou Déployer - PowerShell.

Pourquoi utiliser des spécifications de modèle ?

Les specs de modèle permettent de bénéficier des avantages suivants :

  • Vous utilisez des modèles ARM standard ou fichiers Bicep pour votre spec de modèle.
  • Vous gérez l’accès par le biais d’Azure RBAC, plutôt que des jetons SAP.
  • Les utilisateurs peuvent déployer la spec de modèle sans avoir d’accès en écriture au fichier Bicep.
  • Vous pouvez intégrer la spec de modèle dans un processus de déploiement existant, tel qu’un script PowerShell ou un pipeline DevOps.

Les specs de modèle vous permettent de créer des modèles canoniques et de les partager avec des équipes de votre organisation. Les specs de modèle sont sécurisées, car elles sont disponibles pour Azure Resource Manager pour le déploiement, mais ne sont pas accessibles aux utilisateurs qui n’ont pas l’autorisation appropriée. Les utilisateurs ont uniquement besoin d’un accès en lecture à la spec de modèle pour en déployer le modèle, de sorte que vous pouvez partager le modèle sans permettre à d’autres utilisateurs de le modifier.

Si vous avez actuellement vos modèles dans un GitHub référentiel ou un compte de stockage, vous rencontrez plusieurs défis quand vous essayez de partager et d’utiliser les modèles. Pour déployer le modèle, vous devez rendre le modèle accessible publiquement ou gérer l’accès avec des jetons SAP. Pour contourner cette limite, les utilisateurs peuvent créer des copies locales, qui finissent par diverger de votre modèle original. Les specs de modèle simplifient le partage des modèles.

Les modèles que vous incluez dans une spec de modèle doivent être vérifiés par les administrateurs de votre organisation afin de respecter les exigences et les directives de l’organisation.

Créer une spec de modèle

L’exemple suivant montre un fichier Bicep simple pour la création d’un compte de stockage dans Azure.

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

resource stg 'Microsoft.Storage/storageAccounts@2021-04-01' = {
  name:  'store${uniqueString(resourceGroup().id)}'
  location: resourceGroup().location
  sku: {
    name: storageAccountType
  }
  kind:'StorageV2'
}

Créez une spec de modèle en utilisant :

New-AzTemplateSpec -Name storageSpec -Version 1.0a -ResourceGroupName templateSpecsRg -Location westus2 -TemplateFile ./mainTemplate.bicep

Vous pouvez également créer des spécifications de modèle à l’aide de fichiers Bicep. Toutefois, le contenu de mainTemplate doit être en JSON. Le modèle suivant crée une spécification de modèle pour déployer un compte de stockage :

param templateSpecName string = 'CreateStorageAccount'
param templateSpecVersionName string = '0.1'
param location string = resourceGroup().location

resource createTemplateSpec 'Microsoft.Resources/templateSpecs@2021-05-01' = {
  name: templateSpecName
  location: location
  properties: {
    description: 'A basic templateSpec - creates a storage account.'
    displayName: 'Storage account (Standard_LRS)'
  }
}

resource createTemplateSpecVersion 'Microsoft.Resources/templateSpecs/versions@2021-05-01' = {
  parent: createTemplateSpec
  name: templateSpecVersionName
  location: location
  properties: {
    mainTemplate: {
      '$schema': 'https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#'
      'contentVersion': '1.0.0.0'
      'parameters': {
        'storageAccountType': {
          'type': 'string'
          'defaultValue': 'Standard_LRS'
          'allowedValues': [
            'Standard_LRS'
            'Standard_GRS'
            'Standard_ZRS'
            'Premium_LRS'
          ]
        }
      }
      'resources': [
        {
          'type': 'Microsoft.Storage/storageAccounts'
          'apiVersion': '2019-06-01'
          'name': 'store$uniquestring(resourceGroup().id)'
          'location': resourceGroup().location
          'kind': 'StorageV2'
          'sku': {
            'name': '[parameters(\'storageAccountType\')]'
          }
        }
      ]
    }
  }
}

Le modèle JSON incorporé au fichier Bicep doit apporter ces modifications :

  • Supprimez les virgules à la fin des lignes.
  • Remplacez les guillemets doubles par des guillemets simples.
  • Échappez les guillemets dans les expressions. Par exemple, ’name’: ’[parameters(\’storageAccountType\’)]’.
  • Pour accéder aux paramètres et variables définis dans le fichier Bicep, vous pouvez utiliser directement les noms des paramètres et les noms des variables. Pour accéder aux paramètres et variables définis dans mainTemplate, vous devez toujours utiliser la syntaxe du modèle ARM JSON. Par exemple, ’name’: ’[parameters(\’storageAccountType\’)]’.
  • Utilisez la syntaxe Bicep pour appeler des fonctions Bicep. Par exemple, ’location’: resourceGroup().location.

La taille des specs d’un modèle est limitée à environ 2 Mo. Si la taille d’une spécification de modèle dépasse la limite, vous recevez le code d’erreur TemplateSpecTooLarge. Le message d’erreur indique :

The size of the template spec content exceeds the maximum limit. For large template specs with many artifacts, the recommended course of action is to split it into multiple template specs and reference them modularly via TemplateLinks.

Vous pouvez afficher toutes les specs de modèle dans votre abonnement en utilisant :

Get-AzTemplateSpec

Vous pouvez afficher les détails d’une spec de modèle, notamment ses versions, avec :

Get-AzTemplateSpec -ResourceGroupName templateSpecsRG -Name storageSpec

Déployer une spec de modèle

Une fois que vous avez créé la spec de modèle, les utilisateurs ayant le rôle Lecteur de specs de modèle peuvent déployer le modèle. En outre, vous avez également besoin des autorisations pour le déploiement d’un modèle ARM. Consultez Déployer - CLI ou Déployer - PowerShell.

Les specs de modèle peuvent être déployées via le portail, PowerShell, Azure CLI ou en tant que module Bicep dans un plus grand déploiement de modèle. Les utilisateurs d’une organisation peuvent déployer une spec de modèle sur n’importe quelle étendue d’Azure (groupe de ressources, abonnement, groupe d’administration ou locataire).

Au lieu de passer par un chemin d’accès ou un URI pour un fichier Bicep, vous déployez une spec de modèle en fournissant son ID de ressource. L’ID de ressource possède le format suivant :

/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.Resources/templateSpecs/{template-spec-name}/versions/{template-spec-version}

Notez que l’ID de la ressource contient un nom de version pour la spec de modèle.

Par exemple, vous déployez une spec de modèle à l’aide de la commande suivante.

$id = "/subscriptions/11111111-1111-1111-1111-111111111111/resourceGroups/templateSpecsRG/providers/Microsoft.Resources/templateSpecs/storageSpec/versions/1.0a"

New-AzResourceGroupDeployment `
  -TemplateSpecId $id `
  -ResourceGroupName demoRG

En pratique, vous exécutez généralement Get-AzTemplateSpec ou az ts show pour obtenir l’ID de la spec de modèle à déployer.

$id = (Get-AzTemplateSpec -Name storageSpec -ResourceGroupName templateSpecsRg -Version 1.0a).Versions.Id

New-AzResourceGroupDeployment `
  -ResourceGroupName demoRG `
  -TemplateSpecId $id

Vous pouvez également ouvrir une URL au format suivant pour déployer une spec de modèle :

https://portal.azure.com/#create/Microsoft.Template/templateSpecVersionId/%2fsubscriptions%2f{subscription-id}%2fresourceGroups%2f{resource-group-name}%2fproviders%2fMicrosoft.Resources%2ftemplateSpecs%2f{template-spec-name}%2fversions%2f{template-spec-version}

Paramètres

Passer des paramètres au spec de modèle est similaire à passer des paramètres à un fichier Bicep. Ajoutez les valeurs de paramètres en ligne ou dans un fichier de paramètres.

Paramètres inline

Pour passer un paramètre en ligne, utilisez :

New-AzResourceGroupDeployment `
  -TemplateSpecId $id `
  -ResourceGroupName demoRG `
  -StorageAccountType Standard_GRS

Fichiers de paramètres

  • Utiliser un fichier de paramètres Bicep

    Pour créer un fichier de paramètres Bicep, vous devez spécifier l’instruction using. Voici un exemple :

    using 'using 'ts:<subscription-id>/<resource-group-name>/<template-spec-name>:<tag>'

param StorageAccountType = 'Standard_GRS'

    Si vous souhaitez obtenir plus d’informations, consultez Fichier de paramètres Bicep.

    Pour passer le fichier de paramètres avec :

    Actuellement, vous ne pouvez pas déployer de spec de modèle avec un fichier .bicepparam à l’aide d’Azure PowerShell.

  • Utiliser un fichier de paramètres JSON

    Le code JSON suivant est un échantillon de fichier de paramètres JSON :

    {
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "StorageAccountType": {
      "value": "Standard_GRS"
    }
  }
}

    Puis transmettez ce fichier de paramètres avec :

    New-AzResourceGroupDeployment `
  -TemplateSpecId $id `
  -ResourceGroupName demoRG `
  -TemplateParameterFile ./mainTemplate.parameters.json

Gestion de version

Quand vous créez une spec de modèle, vous indiquez son nom de version. Lorsque vous itérez sur le code du modèle, vous pouvez mettre à jour une version existante (pour les correctifs logiciels) ou publier une nouvelle version. La version est une chaîne de texte. Vous êtes libre de choisir le système de contrôle de version, notamment le contrôle de version sémantique. Les utilisateurs de la spec de modèle peuvent fournir le nom de version à utiliser au moment de son déploiement. Vous pouvez avoir un nombre illimité de versions.

Utiliser des balises

Les étiquettes vous aident à organiser logiquement vos ressources. Vous pouvez ajouter des étiquettes aux spécifications de modèle à l’aide d’Azure PowerShell et d’Azure CLI. L’exemple suivant montre comment spécifier des étiquettes lors de la création de la spécification du modèle :

New-AzTemplateSpec `
  -Name storageSpec `
  -Version 1.0a `
  -ResourceGroupName templateSpecsRg `
  -Location westus2 `
  -TemplateFile ./mainTemplate.bicep `
  -Tag @{Dept="Finance";Environment="Production"}

L’exemple suivant montre comment appliquer des étiquettes lors de la mise à jour d’une spécification de modèle existante :

Set-AzTemplateSpec `
  -Name storageSpec `
  -Version 1.0a `
  -ResourceGroupName templateSpecsRg `
  -Location westus2 `
  -TemplateFile ./mainTemplate.bicep `
  -Tag @{Dept="Finance";Environment="Production"}

Le modèle et ses versions peuvent avoir des étiquettes. Les étiquettes sont appliquées ou héritées selon les paramètres que vous spécifiez.

Spécification de modèle Version Paramètre de version Paramètre d’étiquettes Valeurs des étiquettes
Exists N/A Non spécifié Spécifié appliquées à la spécification de modèle
Exists Nouveau Spécifié Non spécifié héritées de la spécification de modèle vers la version
Nouveau Nouveau Spécifié Spécifié appliquées à la spécification de modèle et à la version
Exists Nouveau Spécifié Spécifié appliquées à la version
Exists Exists Spécifié Spécifié appliquées à la version

Après avoir créé une spec de modèle, vous pouvez créer un lien vers cette spec de modèle dans un module Bicep. La spécification de modèle est déployée lorsque vous déployez le fichier Bicep contenant ce module. Pour plus d’informations, consultez Fichier dans les spécifications du modèle.

Pour créer des alias pour les specs de modèle destinées à la liaison de modules, consultez Alias pour les modules.

Étapes suivantes

Pour en savoir plus sur les specs de modèle et pour obtenir des conseils d’aide pratiques, consultez Publier des bibliothèques de code d’infrastructure réutilisable à l’aide de specs de modèle.