Een sjabloonspecificatie maken en publiceren

Voltooid

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 sjablonengebruiken, zodat u delen 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 parameter key 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 parameterdecorators om informatie te geven over de waarden die je verwacht dat de parameters 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 parameter key geheime gegevens bevat.

Wanneer iemand een sjabloonspecificatie implementeert met behulp van de Azure-portal, doet de portal het volgende:

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

In deze schermopname ziet u het invoeren van parameterwaarden:

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

Als u een sjabloonspecificatie wilt maken, gebruikt u de cmdlet New-AzTemplateSpec. 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 waarin 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 opdracht az ts create 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 waarin 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 om de sjabloonspecificatie te creëren.

Fooi

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