Skapa och publicera en mallspecifikation

Slutförd

Nu ska vi titta på hur du skapar och publicerar en mallspecifikation.

Skapa en mall

Om du vill skapa en mall för användning som en mallspecifikation skriver du en Azure Resource Manager-mall (ARM-mall) precis som vanligt. Du kan inkludera parametrar, variabler, resurser och utdata.

Du kan använda länkade mallar, som gör att du kan definiera delar av distributionen i separata filer. När du arbetar med mallspecifikationer kan länkade mallar bäddas in i mallspecifikationen och refereras från huvudmallen.

Det är viktigt att mallen är enkel för alla i organisationen att förstå och använda, särskilt dess parametrar. Se till att du använder tydliga och begripliga parameternamn. Använd parameteregenskaper och mallmetadata för att ge information om de värden som du förväntar dig att dina parametrar ska inkludera, som i det här exemplet:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "environmentType": {
      "type": "string",
      "allowedValues": [
        "Production",
        "NonProduction"
      ],
      "metadata": {
        "description": "The type of the environment to deploy. This will determine the SKUs and cost of the resources."
      }
    },
    "key": {
      "type": "secureString",
      "metadata": {
        "description": "The secret key to use."
      }
    },
    "location": {
      "type": "string",
      "metadata": {
        "description": "The Azure region into which the resources should be deployed."
      }
    },
    "sqlServerCount": {
      "type": "int",
      "maxValue": 5,
      "metadata": {
        "description": "The number of Azure SQL logical servers to create."
      }
    }
  },
  "resources": []
}

I exemplet använder mallparametrarna egenskaperna allowedValues, maxValueoch description för att tydliggöra vad parametrarna är till för och vad effekten av att ange deras värden är. Mallen innehåller även secureString typ som anger att parametern key innehåller hemliga data.

Det är viktigt att mallen är enkel för alla i organisationen att förstå och använda, särskilt parametrarna. Se till att du använder tydliga och begripliga parameternamn. Använd parameterdekoratörer för att ge information om de värden som du förväntar dig att dina parametrar ska inkludera, som i det här exemplet:

@description('The type of the environment to deploy. This will determine the SKUs and cost of the resources.')
@allowed([
  'Production'
  'NonProduction'
])
param environmentType string

@secure()
@description('The secret key to use.')
param key string

@description('The Azure region into which the resources should be deployed.')
param location string

@description('The number of Azure SQL logical servers to create.')
@maxValue(5)
param sqlServerCount int

I exemplet använder mallparametrarna @allowed, @maxValueoch @description dekoratörer för att klargöra vad parametrarna är till för och vad effekten av att ange sina värden är. Mallen innehåller även secure dekoratör som anger att parametern key innehåller hemliga data.

När någon distribuerar en mallspecifikation med hjälp av Azure-portalen, portalen:

• Visar parameternamnet och beskrivningen.
• Döljer textposten för säkra parametrar.
• Framtvingar de tillåtna värden, längdgränser och värdegränser som du definierar.

Den här skärmbilden illustrerar inmatning av parametervärden.

Det är viktigt att tänka på hur användarna använder mallspecifikationen och se till att parametrarna är tydliga och begripliga.

Publicera mallspecifikationen till Azure

När mallen har skrivits publicerar du mallspecifikationen i stället för att skicka mallen till Azure för distribution.

Viktig

När du publicerar en Bicep-fil som en mallspecifikation konverteras din Bicep-kod till en JSON-mall. Processen med att konvertera Bicep-koden till JSON tar bort en del av informationen i Bicep-filen. Dina kommentarer, symboliska namn för resurser och i vilken ordning du definierar dina resurser kan till exempel saknas eller skilja sig åt i JSON. Det innebär att du inte enkelt kan publicera en Bicep-fil som en mallspecifikation och sedan få tillbaka den ursprungliga Bicep-filen (kallas även avrundning). Det är en bra idé att behålla en kopia av din ursprungliga Bicep-kod på en kodlagringsplats som Git, särskilt när du arbetar med mallspecifikationer.

Om du vill skapa en mallspecifikation använder du cmdleten New-AzTemplateSpec. I följande exempel visas hur du kan skapa en mallspecifikation för lagringskontomallen:

New-AzTemplateSpec `
  -Name StorageWithoutSAS `
  -Location westus `
  -DisplayName 'Storage account with SAS disabled' `
  -Description 'This template spec creates a storage account, which is preconfigured to disable SAS authentication.' `
  -Version '1.0' `
  -TemplateFile main.bicep

New-AzTemplateSpec `
  -Name StorageWithoutSAS `
  -Location westus `
  -DisplayName 'Storage account with SAS disabled' `
  -Description 'This template spec creates a storage account, which is preconfigured to disable SAS authentication.' `
  -Version '1.0' `
  -TemplateFile azuredeploy.json

Nu ska vi titta på var och en av parametrarna:

• -Name är resursnamnet för mallspecifikationen, som inte kan innehålla mellanslag.
• -Location är den plats där mallspecifikationens metadata ska skapas. Du kan dock distribuera mallspecifikationen till valfri region.
• -DisplayName är ett läsbart namn som kan innehålla blanksteg.
• -Description är en läsbar beskrivning som du kan använda för att ge information om innehållet i mallspecifikationen och när någon kan använda den.
• -Version är versionen av mallspecifikationen. Du lär dig mer om versioner senare i den här modulen.
• -TemplateFile är sökvägen till ARM-mallen för att skapa mallspecifikationen för.

Om du vill skapa en mallspecifikation använder du kommandot az ts create. I följande exempel visas hur du kan skapa en mallspecifikation för lagringskontomallen:

az ts create \
  --name StorageWithoutSAS \
  --location westus \
  --display-name "Storage account with SAS disabled" \
  --description "This template spec creates a storage account, which is preconfigured to disable SAS authentication." \
  --version 1.0 \
  --template-file main.bicep

az ts create \
  --name StorageWithoutSAS \
  --location westus \
  --display-name "Storage account with SAS disabled" \
  --description "This template spec creates a storage account, which is preconfigured to disable SAS authentication." \
  --version 1.0 \
  --template-file azuredeploy.json

Nu ska vi titta på vart och ett av argumenten:

• --name är resursnamnet för mallspecifikationen, som inte kan innehålla mellanslag.
• --location är den plats där mallspecifikationens metadata ska skapas. Du kan dock distribuera mallspecifikationen till valfri region.
• --display-name är ett läsbart namn som kan innehålla blanksteg.
• --description är en läsbar beskrivning som du kan använda för att ge information om innehållet i mallspecifikationen och när någon kan använda den.
• --version är versionen av mallspecifikationen. Du lär dig mer om versioner senare i den här modulen.
• --template-file är sökvägen till ARM-mallen för att skapa mallspecifikationen för.

Tips

Du kan också definiera en mallspecifikation i en ARM-mall! Eftersom en mallspecifikation i sig är en Azure-resurs kan du distribuera en mall som definierar en resurs med typen Microsoft.Deployments/templateSpecs.