Azure Resource Manager-mallspecifikationer i Bicep

  • Artikel

En mallspecifikation är en resurstyp för lagring av en Azure Resource Manager-mall (ARM-mall) för senare distribution. Med den här resurstypen kan du dela ARM-mallar med andra användare i din organisation. Precis som andra Azure-resurser kan du använda rollbaserad åtkomstkontroll i Azure (Azure RBAC) för att dela mallspecifikationen. Du kan använda Azure CLI eller Azure PowerShell för att skapa mallspecifikationer genom att tillhandahålla Bicep-filer. Bicep-filerna överförs till ARM JSON-mallar innan de lagras. För närvarande kan du inte importera en Bicep-fil från Azure-portalen för att skapa en mallspecifikationsresurs.

Microsoft.Resources/templateSpecs är resurstypen för mallspecifikationer. Den består av en huvudmall och valfritt antal länkade mallar. Azure lagrar på ett säkert sätt mallspecifikationer i resursgrupper. Både huvudmallen och de länkade mallarna måste finnas i JSON. Mallspecifikationer stöder versionshantering.

Om du vill distribuera mallspecifikationen använder du azure-standardverktyg som PowerShell, Azure CLI, Azure-portalen, REST och andra SDK:er och klienter som stöds. Du använder samma kommandon som för mallen eller Bicep-filen.

Kommentar

Om du vill använda mallspecifikationer i Bicep med Azure PowerShell måste du installera version 6.3.0 eller senare. Om du vill använda det med Azure CLI använder du version 2.27.0 eller senare.

När du utformar distributionen bör du alltid tänka på resursernas livscykel och gruppera de resurser som delar liknande livscykel i en enda mallspecifikation. Dina distributioner omfattar till exempel flera instanser av Azure Cosmos DB med varje instans som innehåller egna databaser och containrar. Eftersom databaserna och containrarna inte ändras så mycket vill du skapa en mallspecifikation för att inkludera en Cosmo DB-instans och dess underliggande databaser och containrar. Du kan sedan använda villkorsstyrda instruktioner i Bicep tillsammans med kopieringsloopar för att skapa flera instanser av dessa resurser.

Dricks

Valet mellan modulregister och mallspecifikationer är främst en fråga om inställningar. Det finns några saker att tänka på när du väljer mellan de två:

  • Modulregistret stöds endast av Bicep. Om du ännu inte använder Bicep använder du mallspecifikationer.
  • Innehåll i Bicep-modulregistret kan bara distribueras från en annan Bicep-fil. Mallspecifikationer kan distribueras direkt från API:et, Azure PowerShell, Azure CLI och Azure-portalen. Du kan till och med använda UiFormDefinition för att anpassa portaldistributionsupplevelsen.
  • Bicep har vissa begränsade funktioner för inbäddning av andra projektartefakter (inklusive icke-Bicep- och icke-ARM-mallfiler. Till exempel PowerShell-skript, CLI-skript och andra binärfiler) med hjälp loadTextContent av funktionerna och loadFileAsBase64 . Mallspecifikationer kan inte paketera dessa artefakter.

Utbildningsresurser

Mer information om mallspecifikationer och praktisk vägledning finns i Publicera bibliotek med återanvändbar infrastrukturkod med hjälp av mallspecifikationer.

Behörigheter som krävs

Det finns två Azure-inbyggda roller som definierats för mallspecifikationen:

Dessutom behöver du även behörigheter för att distribuera en Bicep-fil. Se Distribuera – CLI eller Distribuera – PowerShell.

Varför ska du använda mallspecifikationer?

Mallspecifikationer ger följande fördelar:

  • Du använder ARM-standardmallar eller Bicep-filer för mallspecifikationen.
  • Du hanterar åtkomst via Azure RBAC i stället för SAS-token.
  • Användare kan distribuera mallspecifikationen utan att ha skrivåtkomst till Bicep-filen.
  • Du kan integrera mallspecifikationen i den befintliga distributionsprocessen, till exempel PowerShell-skript eller DevOps-pipeline.

Med mallspecifikationer kan du skapa kanoniska mallar och dela dem med team i din organisation. Mallspecifikationerna är säkra eftersom de är tillgängliga för Azure Resource Manager för distribution, men inte tillgängliga för användare utan rätt behörighet. Användarna behöver bara läsbehörighet till mallspecifikationen för att distribuera mallen, så att du kan dela mallen utan att låta andra ändra den.

Om du för närvarande har dina mallar på en GitHub-lagringsplats eller ett lagringskonto stöter du på flera utmaningar när du försöker dela och använda mallarna. Om du vill distribuera mallen måste du antingen göra mallen offentligt tillgänglig eller hantera åtkomst med SAS-token. För att komma runt den här begränsningen kan användarna skapa lokala kopior, som så småningom avviker från den ursprungliga mallen. Mallspecifikationer förenklar delningsmallar.

De mallar som du inkluderar i en mallspecifikation bör verifieras av administratörer i din organisation för att följa organisationens krav och vägledning.

Skapa mallspecifikation

I följande exempel visas en enkel Bicep-fil för att skapa ett lagringskonto i 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'
}

Skapa en mallspecifikation med hjälp av:

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

Du kan också skapa mallspecifikationer med hjälp av Bicep-filer. Innehållet mainTemplate i måste dock finnas i JSON. Följande mall skapar en mallspecifikation för att distribuera ett lagringskonto:

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

JSON-mallen som är inbäddad i Bicep-filen måste göra följande ändringar:

  • Ta bort kommatecken i slutet av raderna.
  • Ersätt dubbla citattecken med enkla citattecken.
  • Undvik de enkla citattecknarna i uttrycken. Till exempel "name": '[parameters(\'storageAccountType\')]'.
  • Om du vill komma åt parametrarna och variablerna som definierats i Bicep-filen kan du använda parameternamnen och variabelnamnen direkt. För att komma åt parametrarna och variablerna som definierats i mainTemplatemåste du fortfarande använda ARM JSON-mallsyntaxen. Till exempel "name": '[parameters(\'storageAccountType\')]'.
  • Använd Bicep-syntaxen för att anropa Bicep-funktioner. Till exempel "location": resourceGroup().location.

Storleken på en mallspecifikation är begränsad till cirka 2 MB. Om en mallspecifikationsstorlek överskrider gränsen får du felkoden TemplateSpecTooLarge . Felmeddelandet säger:

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.

Du kan visa alla mallspecifikationer i din prenumeration med hjälp av:

Get-AzTemplateSpec

Du kan visa information om en mallspecifikation, inklusive dess versioner med:

Get-AzTemplateSpec -ResourceGroupName templateSpecsRG -Name storageSpec

Distribuera mallspecifikation

När du har skapat mallspecifikationen kan användare med rollen Läsare av mallspecifikationer distribuera den. Dessutom behöver du även behörigheter för att distribuera en ARM-mall. Se Distribuera – CLI eller Distribuera – PowerShell.

Mallspecifikationer kan distribueras via portalen, PowerShell, Azure CLI eller som en Bicep-modul i en större malldistribution. Användare i en organisation kan distribuera en mallspecifikation till valfritt omfång i Azure (resursgrupp, prenumeration, hanteringsgrupp eller klientorganisation).

I stället för att skicka in en sökväg eller URI för en Bicep-fil distribuerar du en mallspecifikation genom att ange dess resurs-ID. Resurs-ID:t har följande format:

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

Observera att resurs-ID:t innehåller ett versionsnamn för mallspecifikationen.

Du kan till exempel distribuera en mallspecifikation med följande kommando.

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

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

I praktiken kör Get-AzTemplateSpec eller az ts show hämtar du vanligtvis ID:t för mallspecifikationen som du vill distribuera.

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

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

Du kan också öppna en URL i följande format för att distribuera en mallspecifikation:

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}

Parametrar

Att skicka in parametrar till mallspecifikationen liknar att skicka parametrar till en Bicep-fil. Lägg till parametervärdena antingen infogade eller i en parameterfil.

Infogade parametrar

Om du vill skicka en parameter infogad använder du:

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

Parameterfiler

  • Använda Bicep-parameterfilen

    Om du vill skapa en Bicep-parameterfil måste du ange -instruktionen using . Här är ett exempel:

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

param StorageAccountType = 'Standard_GRS'

    Mer information finns i filen med Bicep-parametrar.

    Så här skickar du parameterfilen med:

    För närvarande kan du inte distribuera en mallspecifikation med en .bicepparam-fil med hjälp av Azure PowerShell.

  • Använda JSON-parameterfil

    Följande JSON är en JSON-exempelparameterfil:

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

    Och skicka parameterfilen med:

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

Versionshantering

När du skapar en mallspecifikation anger du ett versionsnamn för den. När du itererar i mallkoden kan du antingen uppdatera en befintlig version (för snabbkorrigeringar) eller publicera en ny version. Versionen är en textsträng. Du kan välja att följa valfritt versionshanteringssystem, inklusive semantisk versionshantering. Användare av mallspecifikationen kan ange det versionsnamn som de vill använda när de distribuerar den. Du kan ha ett olimit antal versioner.

Använd taggar

Taggar hjälper dig att organisera dina resurser logiskt. Du kan lägga till taggar i mallspecifikationer med hjälp av Azure PowerShell och Azure CLI. I följande exempel visas hur du anger taggar när du skapar mallspecifikationen:

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

I nästa exempel visas hur du tillämpar taggar när du uppdaterar en befintlig mallspecifikation:

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

Både mallen och dess versioner kan ha taggar. Taggarna tillämpas eller ärvs beroende på de parametrar du anger.

Mallspecifikation Version Versionsparameter Taggparameter Tagga värden
Exists Ej tillämpligt Har inte angetts Angivet tillämpas på mallspecifikationen
Exists Nytt Angivet Har inte angetts ärvt från mallspecifikationen till versionen
Nytt Nytt Angivet Angivet tillämpas på både mallspecifikation och version
Exists Nytt Angivet Angivet tillämpas på versionen
Exists Exists Angivet Angivet tillämpas på versionen

När du har skapat en mallspecifikation kan du länka till mallspecifikationen i en Bicep-modul. Mallspecifikationen distribueras när du distribuerar Bicep-filen som innehåller modulen. Mer information finns i Arkiv i mallspecifikationen.

Information om hur du skapar alias för mallspecifikationer som är avsedda för modullänkning finns i Alias för moduler.

Nästa steg

Mer information om mallspecifikationer och praktisk vägledning finns i Publicera bibliotek med återanvändbar infrastrukturkod med hjälp av mallspecifikationer.