Azure Resource Manager-sjabloonspecificaties in Bicep
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
loadTextContentenloadFileAsBase64functies. 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:
New-AzTemplateSpec -Name storageSpec -Version 1.0a -ResourceGroupName templateSpecsRg -Location westus2 -TemplateFile ./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:
Get-AzTemplateSpec
U kunt details van een sjabloonspecificatie bekijken, inclusief de versies met:
Get-AzTemplateSpec -ResourceGroupName templateSpecsRG -Name storageSpec
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.
$id = "/subscriptions/11111111-1111-1111-1111-111111111111/resourceGroups/templateSpecsRG/providers/Microsoft.Resources/templateSpecs/storageSpec/versions/1.0a"
New-AzResourceGroupDeployment `
-TemplateSpecId $id `
-ResourceGroupName demoRG
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.
$id = (Get-AzTemplateSpec -Name storageSpec -ResourceGroupName templateSpecsRg -Version 1.0a).Versions.Id
New-AzResourceGroupDeployment `
-ResourceGroupName demoRG `
-TemplateSpecId $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:
New-AzResourceGroupDeployment `
-TemplateSpecId $id `
-ResourceGroupName demoRG `
-StorageAccountType Standard_GRS
Parameterbestanden
Bicep-parametersbestand gebruiken
Als u een Bicep-parameterbestand wilt maken, moet u de
usinginstructie 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:
Op dit moment kunt u geen sjabloonspecificatie implementeren met een BICEPPARAM-bestand met behulp van Azure PowerShell.
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:
New-AzResourceGroupDeployment ` -TemplateSpecId $id ` -ResourceGroupName demoRG ` -TemplateParameterFile ./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:
New-AzTemplateSpec `
-Name storageSpec `
-Version 1.0a `
-ResourceGroupName templateSpecsRg `
-Location westus2 `
-TemplateFile ./mainTemplate.bicep `
-Tag @{Dept="Finance";Environment="Production"}
In het volgende voorbeeld ziet u hoe u tags toepast bij het bijwerken van een bestaande sjabloonspecificatie:
Set-AzTemplateSpec `
-Name storageSpec `
-Version 1.0a `
-ResourceGroupName templateSpecsRg `
-Location westus2 `
-TemplateFile ./mainTemplate.bicep `
-Tag @{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 | Opgegeven | toegepast op de sjabloonspecificatie |
| Exists | Nieuw | Opgegeven | Niet opgegeven | overgenomen van de sjabloonspecificatie naar de versie |
| Nieuw | Nieuw | Opgegeven | Opgegeven | toegepast op zowel sjabloonspecificatie als versie |
| Exists | Nieuw | Opgegeven | Opgegeven | toegepast op de versie |
| Exists | Exists | Opgegeven | Opgegeven | 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
Zie Bibliotheken met herbruikbare infrastructuurcode publiceren met behulp van sjabloonspecificaties voor meer informatie over sjabloonspecificaties en voor praktische richtlijnen.