Een sjabloonspecificatie maken en publiceren

  • 3 minuten

Laten we eens kijken hoe u een sjabloonspecificatie maakt en publiceert.

Een sjabloon maken

Als u een sjabloon wilt maken voor gebruik als sjabloonspecificatie, schrijft u een Azure Resource Manager-sjabloon (ARM-sjabloon), net zoals u dat normaal doet. U kunt parameters, variabelen, resources en uitvoer opnemen.

U kunt gekoppelde sjablonen gebruiken, waarmee u onderdelen van uw implementatie in afzonderlijke bestanden kunt definiëren. Wanneer u met sjabloonspecificaties werkt, kunnen gekoppelde sjablonen worden ingesloten in de sjabloonspecificatie en waarnaar wordt verwezen vanuit de hoofdsjabloon.

Het is belangrijk dat uw sjabloon voor iedereen in uw organisatie gemakkelijk te begrijpen en te gebruiken is, met name de parameters. Zorg ervoor dat u duidelijke en begrijpelijke parameternamen gebruikt. Gebruik parametereigenschappen en sjabloonmetagegevens om informatie op te geven over de waarden die u verwacht dat uw parameters worden opgenomen, zoals in dit voorbeeld:

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

In het voorbeeld gebruiken de sjabloonparameters de allowedValues, maxValueen description eigenschappen om duidelijk te maken waar de parameters voor zijn en wat het effect is van het instellen van hun waarden. De sjabloon bevat ook het secureString type om aan te geven dat de key parameter geheime gegevens bevat.

Het is belangrijk dat uw sjabloon eenvoudig is voor iedereen in uw organisatie om deze te begrijpen en te gebruiken, met name de parameters. Zorg ervoor dat u duidelijke en begrijpelijke parameternamen gebruikt. Gebruik parameter decorators om informatie te geven over de waarden die u verwacht te bevatten, zoals in dit voorbeeld:

@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

In het voorbeeld gebruiken de sjabloonparameters de @allowed, @maxValueen @description decorators om duidelijk te maken waar de parameters voor zijn en wat het effect is van het instellen van hun waarden. De sjabloon bevat ook de secure decorator om aan te geven dat de key parameter geheime gegevens bevat.

Wanneer iemand een sjabloonspecificatie implementeert met behulp van De Azure-portal, is het portal:

  • Geeft de parameternaam en beschrijving weer.
  • Hiermee verbergt u de tekstvermelding voor beveiligde parameters.
  • Hiermee worden de toegestane waarden, lengtelimieten en waardelimieten afgedwongen die u definieert.

In deze schermopname ziet u het invoeren van parameterwaarden:

Screenshot that shows the Azure portal interface for entering parameter values for a template spec deployment.

Het is belangrijk om na te denken over hoe gebruikers uw sjabloonspecificatie gebruiken en ervoor zorgen dat uw parameters duidelijk en begrijpelijk zijn.

De sjabloonspecificatie publiceren naar Azure

Nadat uw sjabloon is geschreven, publiceert u de sjabloonspecificatie in plaats van de sjabloon naar Azure te verzenden voor implementatie.

Belangrijk

Wanneer u een Bicep-bestand publiceert als sjabloonspecificatie, wordt uw Bicep-code geconverteerd naar een JSON-sjabloon. Tijdens het converteren van uw Bicep-code naar JSON worden enkele gegevens in uw Bicep-bestand verwijderd. Uw opmerkingen, symbolische namen voor resources en de volgorde waarin u uw resources definieert, ontbreken of verschillen in JSON. Dit betekent dat u een Bicep-bestand niet eenvoudig kunt publiceren als sjabloonspecificatie en vervolgens het oorspronkelijke Bicep-bestand terug kunt krijgen (ook wel roundtripping genoemd). Het is een goed idee om een kopie van uw oorspronkelijke Bicep-code te bewaren in een codeopslagplaats zoals Git, vooral wanneer u met sjabloonspecificaties werkt.

Gebruik de New-AzTemplateSpec cmdlet om een sjabloonspecificatie te maken. In het volgende voorbeeld ziet u hoe u een sjabloonspecificatie voor uw opslagaccountsjabloon kunt maken:

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

Laten we eens kijken naar elk van de parameters:

  • -Name is de resourcenaam van de sjabloonspecificatie, die geen spaties kan bevatten.
  • -Location is de locatie waar de metagegevens van de sjabloonspecificatie moeten worden gemaakt. U kunt de sjabloonspecificatie echter in elke regio implementeren.
  • -DisplayName is een door mensen leesbare naam, die spaties kan bevatten.
  • -Description is een door mensen leesbare beschrijving, die u kunt gebruiken om details te geven over de inhoud van de sjabloonspecificatie en wanneer iemand deze kan gebruiken.
  • -Version is de versie van de sjabloonspecificatie. Verderop in deze module leert u meer over versies.
  • -TemplateFile is het pad naar de ARM-sjabloon voor het maken van de sjabloonspecificatie.

Gebruik de az ts create opdracht om een sjabloonspecificatie te maken. In het volgende voorbeeld ziet u hoe u een sjabloonspecificatie voor uw opslagaccountsjabloon kunt maken:

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

Laten we eens kijken naar elk van de argumenten:

  • --name is de resourcenaam van de sjabloonspecificatie, die geen spaties kan bevatten.
  • --location is de locatie waar de metagegevens van de sjabloonspecificatie moeten worden gemaakt. U kunt de sjabloonspecificatie echter in elke regio implementeren.
  • --display-name is een door mensen leesbare naam, die spaties kan bevatten.
  • --description is een door mensen leesbare beschrijving, die u kunt gebruiken om details te geven over de inhoud van de sjabloonspecificatie en wanneer iemand deze kan gebruiken.
  • --version is de versie van de sjabloonspecificatie. Verderop in deze module leert u meer over versies.
  • --template-file is het pad naar de ARM-sjabloon voor het maken van de sjabloonspecificatie.

Tip

U kunt ook een sjabloonspecificatie definiëren binnen een ARM-sjabloon. Omdat een sjabloonspecificatie zelf een Azure-resource is, kunt u een sjabloon implementeren waarmee een resource met het type Microsoft.Deployments/templateSpecswordt gedefinieerd.