Partager via

Specs de modèle Azure Resource Manager dans Bicep

  • Article

Une spéc de modèle est un type de ressource permettant de stocker un modèle Azure Resource Manager (modèle ARM) afin de le déployer ultérieurement. 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 ARM JSON avant d'être stockés. 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, 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 Azure.
  • 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.

Autorisations requises

Deux rôles sont intégrés à Azure et définis pour les spécifications de modèle :

En outre, vous avez également besoin des autorisations pour le déploiement d’un fichier Bicep. Voir Déployer des fichiers Bicep avec Azure CLI ou Azure 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 via Azure RBAC plutôt que par des jetons de signature d'accès partagés.
  • Les utilisateurs peuvent déployer la spec de modèle sans avoir d’accès en écriture au fichier Bicep.
  • Vous pouvez intégrer le modèle de spécification 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@2023-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 utiliser les fichiers Bicep pour créer des modèles de spécifications. 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@2022-02-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@2022-02-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': '2023-04-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 avec 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 d'un modèle de spécification est limitée à environ 2 mégaoctets. Si une taille de spécification de modèle dépasse la limite, vous obtenez 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 spec de modèle peuvent déployer le modèle. N’oubliez pas que vous avez besoin des autorisations de appropriées pour déployer un modèle ARM.

Les specs de modèle peuvent être déployées via le portail Azure, 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 (par ex, un groupe de ressources, abonnement, groupe d’administration ou locataire).

Vous déployez un modèle de spec en fournissant son identifiant de ressource au lieu de le transmettre dans un chemin ou un URI pour un fichier Bicep. L'ID de la ressource a le format suivant ; notez qu'il inclut un nom de version pour la spec du modèle :

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

Vous pouvez déployer un modèle de spec à l'aide des commandes suivantes :

$id = "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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 déployer un modèle de spec en ouvrant une URL au format suivant :

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

Le passage de paramètres à un modèle de spec est similaire au passage de 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

Fichier de paramètres

  • Utiliser des fichiers de paramètres Bicep.

    Vous devez spécifier l'instruction using pour créer un fichier de paramètres Bicep. Par exemple :

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

param StorageAccountType = 'Standard_GRS'

    Pour plus d'informations, voir Créer des fichiers de paramètres pour le déploiement de Bicep.

    Passer des fichiers de paramètres avec :

    Vous ne pouvez pas utiliser PowerShell pour déployer une spécification de modèle avec un .bicepparam fichier pour l’instant.

  • Utiliser des fichiers 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"
    }
  }
}

    Vous pouvez également transmettre un fichier de paramètres avec :

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

Contrôle de version

Vous indiquez un nom de version pour un modèle de spécification lorsque vous en créez un. 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 spécifications de modèle peuvent fournir le nom de version qu’ils souhaitent utiliser lors du déploiement et peuvent avoir un nombre illimité de versions.

Utiliser des balises

Les étiquettes vous aident à organiser logiquement vos ressources. Vous pouvez utiliser Azure PowerShell ou Azure CLI pour ajouter des balises aux spécifications des modèles. 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 balises sont appliquées ou héritées en fonction des paramètres spécifiés :

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 Chemin d’accès à un module.

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

Étapes suivantes

Voir le module d'apprentissage Publier des bibliothèques de code d'infrastructure réutilisable en utilisant des spécifications de modèle pour plus d'informations et de conseils pratiques sur les spécifications de modèle.