Dela via

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 att distribuera den senare. 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 JSON ARM-mallar innan de lagras. Du kan inte importera en Bicep-fil från Azure Portal för att skapa en mallspecifikationsresurs just nu.

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 Portal, 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 Portal. Du kan till och med använda UiFormDefinition för att anpassa Azure Portal distributionsmiljön.
  • 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.

Behörigheter som krävs

Två roller är inbyggda i Azure och definieras för mallspecifikationer:

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

Varför 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 signaturtoken för delad åtkomst.
  • Användare kan distribuera mallspecifikationen utan att ha skrivåtkomst till Bicep-filen.
  • Du kan integrera mallspecifikationen i en befintlig distributionsprocess, till exempel ett PowerShell-skript eller en 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@2023-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å använda Bicep-filer för att skapa mallspecifikationer. 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@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\')]'
          }
        }
      ]
    }
  }
}

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 syntaxen för JSON ARM-mallen. 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 megabyte. 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 Mallspecifikationsläsare distribuera den. Kom ihåg att du behöver rätt behörigheter för att distribuera en ARM-mall.

Mallspecifikationer kan distribueras via Azure Portal, 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 (t.ex. en resursgrupp, prenumeration, hanteringsgrupp eller klientorganisation).

Du distribuerar en mallspecifikation genom att ange dess resurs-ID i stället för att skicka den i en sökväg eller URI för en Bicep-fil. Resurs-ID:t har följande format. Observera att den innehåller ett versionsnamn för mallspecifikationen:

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

Du kan distribuera en mallspecifikation med följande kommandon:

$id = "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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å distribuera en mallspecifikation genom att öppna en URL i följande format:

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 parametrar till en mallspecifikation 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änd Bicep-parameterfiler.

    Du måste ange instruktionen using för att skapa en Bicep-parameterfil. Till exempel:

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

param StorageAccountType = 'Standard_GRS'

    Mer information finns i Skapa parameterfiler för Bicep-distribution.

    Skicka parameterfiler med:

    Du kan inte använda PowerShell för att distribuera en mallspecifikation med en .bicepparam fil just nu.

  • Använd JSON-parameterfiler.

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

    Du kan också skicka en parameterfil med:

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

Versionshantering

Du anger ett versionsnamn för en mallspecifikation när du skapar en. 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 mallspecifikationer kan ange det versionsnamn som de vill använda när de distribuerar det och kan ha ett obegränsat antal versioner.

Använd taggar

Taggar hjälper dig att logiskt organisera dina resurser. Du kan använda Azure PowerShell eller Azure CLI för att lägga till taggar i mallspecifikationer. 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 följande 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 som du anger:

Mallspecifikation Version Versionsparameter Taggparameter Tagga värden
Exists Ej tillämpligt Har inte angetts Har angetts tillämpas på mallspecifikationen
Exists Nytt Har angetts Har inte angetts ärvt från mallspecifikationen till versionen
Nytt Nytt Har angetts Har angetts tillämpas på både mallspecifikation och version
Exists Nytt Har angetts Har angetts tillämpas på versionen
Exists Exists Har angetts Har angetts 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 Sökväg till en modul.

  • 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 och praktisk vägledning om mallspecifikationer finns i Modulen Publicera bibliotek för återanvändbar infrastrukturkod med hjälp av mallspecifikationer .