Azure Resource Manager-sjabloonspecificaties in Bicep

Artikel
01/11/2025

Een sjabloonspecificatie is een resourcetype voor het opslaan van een Azure Resource Manager-sjabloon (ARM-sjabloon) om deze later te implementeren. Met dit resourcetype kunt u ARM-sjablonen delen met andere gebruikers in uw organisatie. Net als elke andere Azure-resource kunt u op rollen gebaseerd toegangsbeheer van Azure (Azure RBAC) gebruiken om de sjabloonspecificatie te delen. U kunt Azure CLI of Azure PowerShell gebruiken om sjabloonspecificaties te maken door Bicep-bestanden op te geven. De Bicep-bestanden worden getranspileerd in JSON ARM-sjablonen voordat ze worden opgeslagen. U kunt op dit moment geen Bicep-bestand importeren vanuit Azure Portal om een sjabloonspecificatieresource te maken.

Microsoft.Resources/templateSpecs is het resourcetype voor sjabloonspecificaties . Het bestaat uit een hoofdsjabloon en een willekeurig aantal gekoppelde sjablonen. In Azure worden sjabloonspecificaties veilig opgeslagen in resourcegroepen. Zowel de hoofdsjabloon als de gekoppelde sjablonen moeten zich in JSON bevinden. Sjabloonspecificaties ondersteunen versiebeheer.

Als u de sjabloonspecificatie wilt implementeren, gebruikt u standaard Azure-hulpprogramma's zoals PowerShell, Azure CLI, Azure Portal, REST en andere ondersteunde SDK's en clients. U gebruikt dezelfde opdrachten als voor de sjabloon of het Bicep-bestand.

Notitie

Als u sjabloonspecificaties wilt gebruiken in Bicep met Azure PowerShell, moet u versie 6.3.0 of hoger installeren. Als u deze wilt gebruiken met Azure CLI, gebruikt u versie 2.27.0 of hoger.

Houd bij het ontwerpen van uw implementatie altijd rekening met de levenscyclus van de resources en groepeer de resources die een vergelijkbare levenscyclus delen in één sjabloonspecificatie. Uw implementaties bevatten bijvoorbeeld meerdere exemplaren van Azure Cosmos DB met elk exemplaar met eigen databases en containers. Gezien de databases en de containers niet veel veranderen, wilt u één sjabloonspecificatie maken om een Cosmo DB-exemplaar en de onderliggende databases en containers op te nemen. Vervolgens kunt u voorwaardelijke instructies in uw Bicep gebruiken, samen met kopieerlussen om meerdere exemplaren van deze resources te maken.

Tip

De keuze tussen moduleregister en sjabloonspecificaties is meestal een kwestie van voorkeur. Er zijn enkele dingen die u moet overwegen wanneer u kiest tussen de twee:

Moduleregister wordt alleen ondersteund door Bicep. Als u bicep nog niet gebruikt, gebruikt u sjabloonspecificaties.
Inhoud in het Bicep-moduleregister kan alleen worden geïmplementeerd vanuit een ander Bicep-bestand. Sjabloonspecificaties kunnen rechtstreeks vanuit de API, Azure PowerShell, Azure CLI en Azure Portal worden geïmplementeerd. U kunt zelfs de implementatie-ervaring van Azure Portal aanpassen UiFormDefinition .
Bicep heeft een aantal beperkte mogelijkheden voor het insluiten van andere projectartefacten (waaronder niet-Bicep- en niet-ARM-sjabloonbestanden). Bijvoorbeeld PowerShell-scripts, CLI-scripts en andere binaire bestanden) met behulp van de loadTextContent en loadFileAsBase64 functies. Sjabloonspecificaties kunnen deze artefacten niet verpakken.

Vereiste machtigingen

Er zijn twee rollen ingebouwd in Azure en gedefinieerd voor sjabloonspecificaties:

Daarnaast hebt u ook de machtigingen nodig voor het implementeren van een Bicep-bestand. Zie Bicep-bestanden implementeren met de Azure CLI of Azure PowerShell.

Waarom sjabloonspecificaties gebruiken

Sjabloonspecificaties bieden de volgende voordelen:

U gebruikt standaard ARM-sjablonen of Bicep-bestanden voor uw sjabloonspecificatie.
U beheert de toegang via Azure RBAC in plaats van handtekeningentokens voor gedeelde toegang.
Gebruikers kunnen de sjabloonspecificatie implementeren zonder schrijftoegang te hebben tot het Bicep-bestand.
U kunt de sjabloonspecificatie integreren in een bestaand implementatieproces, zoals een PowerShell-script of een DevOps-pijplijn.

Met sjabloonspecificaties kunt u canonieke sjablonen maken en deze delen met teams in uw organisatie. De sjabloonspecificaties zijn veilig omdat ze beschikbaar zijn voor Azure Resource Manager voor implementatie, maar niet toegankelijk zijn voor gebruikers zonder de juiste machtiging. Gebruikers hebben alleen leestoegang tot de sjabloonspecificatie nodig om de sjabloon te implementeren, zodat u de sjabloon kunt delen zonder dat anderen deze mogen wijzigen.

Als u momenteel uw sjablonen in een GitHub-opslagplaats of opslagaccount hebt, ondervindt u verschillende uitdagingen bij het delen en gebruiken van de sjablonen. Als u de sjabloon wilt implementeren, moet u de sjabloon openbaar toegankelijk maken of toegang beheren met SAS-tokens. Om deze beperking te omzeilen, kunnen gebruikers lokale kopieën maken, die uiteindelijk afwijken van de oorspronkelijke sjabloon. Sjabloonspecificaties vereenvoudigen het delen van sjablonen.

De sjablonen die u in een sjabloonspecificatie opneemt, moeten worden geverifieerd door beheerders in uw organisatie om de vereisten en richtlijnen van de organisatie te volgen.

Sjabloonspecificatie maken

In het volgende voorbeeld ziet u een eenvoudig Bicep-bestand voor het maken van een opslagaccount in 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'
}

Maak een sjabloonspecificatie met behulp van:

Azure PowerShell
Azure-CLI

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

az ts create \
  --name storageSpec \
  --version "1.0a" \
  --resource-group templateSpecRG \
  --location "westus2" \
  --template-file "./mainTemplate.bicep"

U kunt ook Bicep-bestanden gebruiken om sjabloonspecificaties te maken. De inhoud moet mainTemplate echter in JSON staan. Met de volgende sjabloon wordt een sjabloonspecificatie gemaakt voor het implementeren van een opslagaccount:

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\')]'
          }
        }
      ]
    }
  }
}

De JSON-sjabloon die is ingesloten in het Bicep-bestand, moet deze wijzigingen aanbrengen:

Verwijder de komma's aan het einde van de regels.
Vervang dubbele aanhalingstekens door enkele aanhalingstekens.
Escape de enkele aanhalingstekens binnen de expressies. Bijvoorbeeld 'name': '[parameters(\'storageAccountType\')].
Voor toegang tot de parameters en variabelen die zijn gedefinieerd in het Bicep-bestand, kunt u rechtstreeks de parameternamen en de namen van de variabelen gebruiken. Als u toegang wilt krijgen tot de parameters en variabelen die zijn gedefinieerd in mainTemplate, moet u nog steeds de JSON ARM-sjabloonsyntaxis gebruiken. Bijvoorbeeld 'name': '[parameters(\'storageAccountType\')].
Gebruik de Bicep-syntaxis om Bicep-functies aan te roepen. Bijvoorbeeld 'location': resourceGroup().location.

De grootte van een sjabloonspecificatie is beperkt tot ongeveer 2 megabytes. Als een sjabloonspecificatie groter is dan de limiet, krijgt u de foutcode TemplateSpecTooLarge . Het foutbericht zegt:

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.

U kunt alle sjabloonspecificaties in uw abonnement bekijken met behulp van:

Azure PowerShell
Azure-CLI

Get-AzTemplateSpec

az ts list

U kunt details van een sjabloonspecificatie bekijken, inclusief de versies met:

Azure PowerShell
Azure-CLI

Get-AzTemplateSpec -ResourceGroupName templateSpecsRG -Name storageSpec

az ts show \
    --name storageSpec \
    --resource-group templateSpecRG \
    --version "1.0a"

Sjabloonspecificatie implementeren

Nadat u de sjabloonspecificatie hebt gemaakt, kunnen gebruikers met de rol Sjabloonspecificatielezer deze implementeren. Houd er rekening mee dat u de juiste machtigingen nodig hebt om een ARM-sjabloon te implementeren.

Sjabloonspecificaties kunnen worden geïmplementeerd via Azure Portal, PowerShell, Azure CLI of als bicep-module in een grotere sjabloonimplementatie. Gebruikers in een organisatie kunnen een sjabloonspecificatie implementeren in elk bereik in Azure (bijvoorbeeld een resourcegroep, abonnement, beheergroep of tenant).

U implementeert een sjabloonspecificatie door de resource-id op te geven in plaats van deze door te geven in een pad of URI voor een Bicep-bestand. De resource-id heeft de volgende indeling; u ziet dat deze een versienaam bevat voor de sjabloonspecificatie:

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

U kunt een sjabloonspecificatie implementeren met de volgende opdrachten:

Azure PowerShell
Azure-CLI

$id = "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/templateSpecsRG/providers/Microsoft.Resources/templateSpecs/storageSpec/versions/1.0a"

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

id = "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/templateSpecsRG/providers/Microsoft.Resources/templateSpecs/storageSpec/versions/1.0a"

az deployment group create \
  --resource-group demoRG \
  --template-spec $id

In de praktijk voert u doorgaans uit Get-AzTemplateSpec of az ts show haalt u de id op van de sjabloonspecificatie die u wilt implementeren.

Azure PowerShell
Azure-CLI

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

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

id = $(az ts show --name storageSpec --resource-group templateSpecRG --version "1.0a" --query "id")

az deployment group create \
  --resource-group demoRG \
  --template-spec $id

U kunt ook een sjabloonspecificatie implementeren door een URL te openen in de volgende indeling:

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}

Parameters

Het doorgeven van parameters aan een sjabloonspecificatie is vergelijkbaar met het doorgeven van parameters aan een Bicep-bestand. Voeg de parameterwaarden inline of in een parameterbestand toe.

Inlineparameters

Als u een parameter inline wilt doorgeven, gebruikt u:

Azure PowerShell
Azure-CLI

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

az deployment group create \
  --resource-group demoRG \
  --template-spec $id \
  --parameters storageAccountType='Standard_GRS'

Parametersbestanden

Gebruik Bicep-parametersbestanden.

U moet de using instructie opgeven om een Bicep-parametersbestand te maken. Voorbeeld:
```
using 'using 'ts:<subscription-id>/<resource-group-name>/<template-spec-name>:<tag>'

param StorageAccountType = 'Standard_GRS'
```
Zie Parametersbestanden maken voor bicep-implementatie voor meer informatie.

Parametersbestanden doorgeven met:
- Azure PowerShell
- Azure-CLI
U kunt PowerShell op dit moment niet gebruiken om een sjabloonspecificatie met een .bicepparam bestand te implementeren.
```
az deployment group create \
  --resource-group demoRG \
  --parameters "./mainTemplate.bicepparam"
```
U hoeft de --template-spec parameter niet op te geven vanwege de using instructie in het .bicepparam bestand.

Gebruik JSON-parametersbestanden.

De volgende JSON is een voorbeeldbestand met JSON-parameters:

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

U kunt ook een parameterbestand doorgeven met:

Azure PowerShell
Azure-CLI

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

az deployment group create \
  --resource-group demoRG \
  --template-spec $id \
  --parameters "./mainTemplate.parameters.json"

Versiebeheer

U geeft een versienaam op voor een sjabloonspecificatie wanneer u er een maakt. Tijdens het herhalen van de sjablooncode kunt u een bestaande versie (voor hotfixes) bijwerken of een nieuwe versie publiceren. De versie is een tekenreeks. U kunt ervoor kiezen om elk versiebeheersysteem te volgen, inclusief semantische versiebeheer. Sjabloonspecificatiegebruikers kunnen de versienaam opgeven die ze willen gebruiken bij de implementatie en kunnen een onbeperkt aantal versies hebben.

Tags gebruiken

Met tags kunt u uw resources logisch ordenen. U kunt Azure PowerShell of Azure CLI gebruiken om tags toe te voegen aan sjabloonspecificaties. In het volgende voorbeeld ziet u hoe u tags opgeeft bij het maken van de sjabloonspecificatie:

Azure PowerShell
Azure-CLI

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

az ts create \
  --name storageSpec \
  --version "1.0a" \
  --resource-group templateSpecRG \
  --location "westus2" \
  --template-file "./mainTemplate.bicep" \
  --tags Dept=Finance Environment=Production

In het volgende voorbeeld ziet u hoe u tags toepast bij het bijwerken van een bestaande sjabloonspecificatie:

Azure PowerShell
Azure-CLI

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

az ts update \
  --name storageSpec \
  --version "1.0a" \
  --resource-group templateSpecRG \
  --location "westus2" \
  --template-file "./mainTemplate.bicep" \
  --tags Dept=Finance Environment=Production

Zowel de sjabloon als de bijbehorende versies kunnen tags bevatten. De tags worden toegepast of overgenomen, afhankelijk van de parameters die u opgeeft:

Sjabloonspecificatie	Versie	Versieparameter	Tagparameter	Tagwaarden
Exists	N.v.t.	Niet opgegeven	Gespecificeerd	toegepast op de sjabloonspecificatie
Exists	Nieuw	Gespecificeerd	Niet opgegeven	overgenomen van de sjabloonspecificatie naar de versie
Nieuw	Nieuw	Gespecificeerd	Gespecificeerd	toegepast op zowel sjabloonspecificatie als versie
Exists	Nieuw	Gespecificeerd	Gespecificeerd	toegepast op de versie
Exists	Exists	Gespecificeerd	Gespecificeerd	toegepast op de versie

Koppeling naar sjabloonspecificaties

Nadat u een sjabloonspecificatie hebt gemaakt, kunt u een koppeling maken naar die sjabloonspecificatie in een Bicep-module. De sjabloonspecificatie wordt geïmplementeerd wanneer u het Bicep-bestand met die module implementeert. Zie Pad naar een module voor meer informatie.
Zie Aliassen voor modules voor het maken van aliassen voor sjabloonspecificaties die zijn bedoeld voor modulekoppeling.

Volgende stappen

Zie de publicatiebibliotheken van herbruikbare infrastructuurcode met behulp van sjabloonspecificaties Learn-module voor meer informatie en praktische richtlijnen over sjabloonspecificaties.

Delen via