Azure Resource Manager-sjabloonspecificaties in Bicep

Artikel
09/26/2024

Een sjabloonspecificatie is een resourcetype voor het opslaan van een Azure Resource Manager-sjabloon (ARM-sjabloon) voor latere implementatie. 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 ARM JSON-sjablonen voordat ze worden opgeslagen. Op dit moment kunt u 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 de 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.

Trainingsmateriaal

Zie Bibliotheken met herbruikbare infrastructuurcode publiceren met behulp van sjabloonspecificaties voor meer informatie over sjabloonspecificaties en voor praktische richtlijnen.

Vereiste machtigingen

Er zijn twee ingebouwde Azure-rollen gedefinieerd voor sjabloonspecificatie:

Daarnaast hebt u ook de machtigingen nodig voor het implementeren van een Bicep-bestand. Zie Implementeren - CLI of Implementeren - 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 SAS-tokens.
Gebruikers kunnen de sjabloonspecificatie implementeren zonder schrijftoegang te hebben tot het Bicep-bestand.
U kunt de sjabloonspecificatie integreren in een bestaand implementatieproces, zoals PowerShell-script of 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:

PowerShell
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 sjabloonspecificaties maken met bicep-bestanden. 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. Voor toegang tot de parameters en variabelen die zijn gedefinieerd in mainTemplate, moet u nog steeds de syntaxis van de ARM JSON-sjabloon 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 MB. 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:

PowerShell
CLI

Get-AzTemplateSpec

az ts list

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

PowerShell
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. Daarnaast hebt u ook de machtigingen nodig voor het implementeren van een ARM-sjabloon. Zie Implementeren - CLI of Implementeren - PowerShell.

Sjabloonspecificaties kunnen worden geïmplementeerd via de 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 (resourcegroep, abonnement, beheergroep of tenant).

In plaats van een pad of URI door te geven voor een Bicep-bestand, implementeert u een sjabloonspecificatie door de resource-id op te geven. De resource-id heeft de volgende indeling:

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

U ziet dat de resource-id een versienaam bevat voor de sjabloonspecificatie.

U implementeert bijvoorbeeld een sjabloonspecificatie met de volgende opdracht.

PowerShell
CLI

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

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

id = "/subscriptions/11111111-1111-1111-1111-111111111111/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.

PowerShell
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 URL in de volgende indeling openen om een sjabloonspecificatie te implementeren:

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 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:

PowerShell
CLI

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

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

Parameterbestanden

Bicep-parametersbestand gebruiken

Als u een Bicep-parameterbestand wilt maken, moet u de using instructie opgeven. Hier volgt een voorbeeld:
```
using 'using 'ts:<subscription-id>/<resource-group-name>/<template-spec-name>:<tag>'

param StorageAccountType = 'Standard_GRS'
```
Zie het bicep-parametersbestand voor meer informatie.

Parameterbestand doorgeven met:
- PowerShell
- CLI
Op dit moment kunt u geen sjabloonspecificatie implementeren met een BICEPPARAM-bestand met behulp van Azure PowerShell.
```
az deployment group create \
  --resource-group demoRG \
  --parameters "./mainTemplate.bicepparam"
```
Vanwege de using instructie in het bicepparam-bestand. U hoeft de --template-spec parameter niet op te geven.

JSON-parametersbestand gebruiken

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"
    }
  }
}

Geef dat parameterbestand door met:

PowerShell
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

Wanneer u een sjabloonspecificatie maakt, geeft u er een versienaam voor op. 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. Gebruikers van de sjabloonspecificatie kunnen de versienaam opgeven die ze willen gebruiken bij het implementeren ervan. U kunt een onbeperkt aantal versies hebben.

Tags gebruiken

Tags zijn een hulpmiddel bij het logisch ordenen van uw resources. U kunt tags toevoegen aan sjabloonspecificaties met behulp van Azure PowerShell en Azure CLI. In het volgende voorbeeld ziet u hoe u tags opgeeft bij het maken van de sjabloonspecificatie:

PowerShell
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:

PowerShell
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 Bestand in sjabloonspecificatie voor meer informatie.

Zie Aliassen voor modules voor het maken van aliassen voor sjabloonspecificaties die zijn bedoeld voor modulekoppeling.

Volgende stappen