Specifikationer för Azure Resource Manager-mallar

  • Artikel

En mallspecifikation är en resurstyp för lagring av en Azure Resource Manager-mall (ARM-mall) i Azure 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.

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

Kommentar

Om du vill använda mallspecifikation med Azure PowerShell måste du installera version 5.0.0 eller senare. Om du vill använda det med Azure CLI använder du version 2.14.2 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, där varje instans innehåller egna databaser och containrar. Eftersom databaserna och containrarna inte ändras så mycket vill du skapa en mallspecifikation för att inkludera en Cosmos DB-instans och dess underliggande databaser och containrar. Du kan sedan använda villkorsstyrda instruktioner i dina mallar tillsammans med kopieringsloopar för att skapa flera instanser av dessa resurser.

Utbildningsresurser

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

Dricks

Vi rekommenderar Bicep eftersom det erbjuder samma funktioner som ARM-mallar och syntaxen är enklare att använda. Mer information finns i Azure Resource Manager-mallspecifikationer i Bicep.

Varför ska du använda mallspecifikationer?

Mallspecifikationer ger följande fördelar:

  • Du använder ARM-standardmallar 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 mallen.
  • 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.

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.

Skapa mallspecifikation

I följande exempel visas en enkel mall för att skapa ett lagringskonto i Azure.

{
  "$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": "[concat('store', uniquestring(resourceGroup().id))]",
      "location": "[resourceGroup().location]",
      "kind": "StorageV2",
      "sku": {
        "name": "[parameters('storageAccountType')]"
      }
    }
  ]
}

När du skapar mallspecifikationen skickas PowerShell- eller CLI-kommandona huvudmallfilen. Om huvudmallen refererar till länkade mallar kommer kommandona att hitta och paketera dem för att skapa mallspecifikationen. Mer information finns i Skapa en mallspecifikation med länkade mallar.

Skapa en mallspecifikation med hjälp av:

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

Du kan också skapa mallspecifikationer med hjälp av ARM-mallar. Följande mall skapar en mallspecifikation för att distribuera ett lagringskonto:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "templateSpecName": {
      "type": "string",
      "defaultValue": "CreateStorageAccount"
    },
    "templateSpecVersionName": {
      "type": "string",
      "defaultValue": "0.1"
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/templateSpecs",
      "apiVersion": "2021-05-01",
      "name": "[parameters('templateSpecName')]",
      "location": "[parameters('location')]",
      "properties": {
        "description": "A basic templateSpec - creates a storage account.",
        "displayName": "Storage account (Standard_LRS)"
      }
    },
    {
      "type": "Microsoft.Resources/templateSpecs/versions",
      "apiVersion": "2021-05-01",
      "name": "[format('{0}/{1}', parameters('templateSpecName'), parameters('templateSpecVersionName'))]",
      "location": "[parameters('location')]",
      "dependsOn": [
        "[resourceId('Microsoft.Resources/templateSpecs', parameters('templateSpecName'))]"
      ],
      "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": "[concat('store', uniquestring(resourceGroup().id))]",
              "location": "[resourceGroup().location]",
              "kind": "StorageV2",
              "sku": {
                "name": "[parameters('storageAccountType')]"
              }
            }
          ]
        }
      }
    }
  ]
}

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 för mallspecifikationsläsare 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 länkad mall 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 mall 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 är precis som att skicka parametrar till en ARM-mall. Lägg till parametervärdena antingen infogade eller i en parameterfil.

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

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

Om du vill skapa en lokal parameterfil använder du:

{
  "$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:

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

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

När du skapar eller ändrar en mallspecifikation med den angivna versionsparametern, men utan parametern tag/tags:

  • Om mallspecifikationen finns och har taggar, men versionen inte finns, ärver den nya versionen samma taggar som den befintliga mallspecifikationen.

När du skapar eller ändrar en mallspecifikation med både parametern tag/tags och den angivna versionsparametern:

  • Om både mallspecifikationen och versionen inte finns läggs taggarna till i både den nya mallspecifikationen och den nya versionen.
  • Om mallspecifikationen finns, men versionen inte finns, läggs taggarna bara till i den nya versionen.
  • Om både mallspecifikationen och versionen finns gäller taggarna endast för versionen.

När du ändrar en mall med parametern tag/tags angiven, men utan den angivna versionsparametern, läggs taggarna bara till i mallspecifikationen.

Skapa en mallspecifikation med länkade mallar

Om huvudmallen för mallspecifikationen refererar till länkade mallar kan PowerShell- och CLI-kommandona automatiskt hitta och paketera de länkade mallarna från den lokala enheten. Du behöver inte konfigurera lagringskonton eller lagringsplatser manuellt för att vara värd för mallspecifikationerna – allt är fristående i mallspecifikationsresursen.

Följande exempel består av en huvudmall med två länkade mallar. Exemplet är bara ett utdrag av mallen. Observera att den använder en egenskap med namnet relativePath för att länka till de andra mallarna. Du måste använda apiVersion2020-06-01 eller senare för distributionsresursen.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  ...
  "resources": [
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2020-06-01",
      ...
      "properties": {
        "mode": "Incremental",
        "templateLink": {
          "relativePath": "artifacts/webapp.json"
        }
      }
    },
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2020-06-01",
      ...
      "properties": {
        "mode": "Incremental",
        "templateLink": {
          "relativePath": "artifacts/database.json"
        }
      }
    }
  ],
  "outputs": {}
}

När PowerShell- eller CLI-kommandot för att skapa mallspecifikationen körs för föregående exempel hittar kommandot tre filer – huvudmallen, webbappmallen (webapp.json) och databasmallen (database.json) – och paketerar dem i mallspecifikationen.

Mer information finns i Självstudie: Skapa en mallspecifikation med länkade mallar.

Distribuera mallspecifikation som en länkad mall

När du har skapat en mallspecifikation är det enkelt att återanvända den från en ARM-mall eller en annan mallspecifikation. Du länkar till en mallspecifikation genom att lägga till dess resurs-ID i mallen. Den länkade mallspecifikationen distribueras automatiskt när du distribuerar huvudmallen. Med det här beteendet kan du utveckla modulära mallspecifikationer och återanvända dem efter behov.

Du kan till exempel skapa en mallspecifikation som distribuerar nätverksresurser och en annan mallspecifikation som distribuerar lagringsresurser. I ARM-mallar länkar du till dessa två mallspecifikationer när du behöver konfigurera nätverks- eller lagringsresurser.

Följande exempel liknar det tidigare exemplet, men du använder id egenskapen för att länka till en mallspecifikation i stället för egenskapen relativePath för att länka till en lokal mall. Använd 2020-06-01 för API-version för distributionsresursen. I exemplet finns mallspecifikationerna i en resursgrupp med namnet templateSpecsRG.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  ...
  "resources": [
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2020-06-01",
      "name": "networkingDeployment",
      ...
      "properties": {
        "mode": "Incremental",
        "templateLink": {
          "id": "[resourceId('templateSpecsRG', 'Microsoft.Resources/templateSpecs/versions', 'networkingSpec', '1.0a')]"
        }
      }
    },
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2020-06-01",
      "name": "storageDeployment",
      ...
      "properties": {
        "mode": "Incremental",
        "templateLink": {
          "id": "[resourceId('templateSpecsRG', 'Microsoft.Resources/templateSpecs/versions', 'storageSpec', '1.0a')]"
        }
      }
    }
  ],
  "outputs": {}
}

Mer information om hur du länkar mallspecifikationer finns i Självstudie: Distribuera en mallspecifikation som en länkad mall.

Nästa steg