Erstellen und Veröffentlichen einer Vorlagenspezifikation

Abgeschlossen

Sehen wir uns an, wie Sie eine Vorlagenspezifikation erstellen und veröffentlichen.

Erstellen einer Vorlage

Zum Erstellen einer Vorlage, die Sie als Vorlagenspezifikation verwenden möchten, schreiben Sie wie gewohnt eine ARM-Vorlage (Azure Resource Manager-Vorlage). Sie können Parameter, Variablen, Ressourcen und Ausgaben angeben.

Sie können verknüpfte Vorlagen verwenden, mit denen Sie Teile Ihrer Bereitstellung in separaten Dateien definieren können. Wenn Sie mit Vorlagenspezifikationen arbeiten, können verknüpfte Vorlagen in die Vorlagenspezifikation eingebettet werden, auf die dann aus Ihrer Hauptvorlage verwiesen wird.

Es ist wichtig, dass Ihre Vorlage für jeden in Ihrer Organisation leicht zu verstehen und zu verwenden ist, insbesondere die Parameter. Achten Sie darauf, klare und verständliche Parameternamen zu verwenden. Verwenden Sie Parametereigenschaften und Vorlagenmetadaten, um Informationen zu den Werten bereitzustellen, die Ihre Parameter Ihrer Erwartung nach annehmen werden, wie etwa in diesem Beispiel:

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

Im Beispiel verwenden die Vorlagenparameter die Eigenschaften allowedValues, maxValue und description, um deutlich zu machen, wofür die Parameter gelten und welche Auswirkungen das Festlegen ihrer Werte hat. Die Vorlage enthält außerdem den Typ secureString, um anzugeben, dass der Parameter key Geheimnisdaten enthält.

Es ist wichtig, dass Ihre Vorlage für jeden in Ihrer Organisation leicht zu verstehen und zu verwenden ist, insbesondere die Parameter. Achten Sie darauf, klare und verständliche Parameternamen zu verwenden. Verwenden Sie Decorator-Elemente für Parameter, um Informationen zu den Werten bereitzustellen, die Ihre Parameter Ihrer Erwartung nach annehmen werden, wie etwa in diesem Beispiel:

@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

Im Beispiel verwenden die Vorlagenparameter die Decorator-Elemente @allowed, @maxValue und @description, um deutlich zu machen, wofür die Parameter gelten und welche Auswirkungen das Festlegen ihrer Werte hat. Die Vorlage enthält außerdem den Decorator secure, um anzugeben, dass der Parameter key Geheimnisdaten enthält.

Wenn jemand eine Vorlagenspezifikation mithilfe des Azure-Portals bereitstellt, übernimmt das Portal die folgenden Aufgaben:

• Es zeigt den Namen und die Beschreibung von Parametern an.
• Es blendet für sichere Parameter den Texteintrag aus.
• Es erzwingt die von Ihnen definierten zulässigen Werte, Längenbeschränkungen und Wertgrenzwerte.

Dieser Screenshot veranschaulicht die Eingabe von Parameterwerten:

Es ist wichtig, dass Sie überlegen, wie Ihre Vorlagenspezifikation von den Benutzern verwendet wird, und sicherstellen, dass Ihre Parameter klar und verständlich sind.

Veröffentlichen der Vorlagenspezifikation in Azure

Nachdem Sie Ihre Vorlage geschrieben haben, veröffentlichen Sie die Vorlagenspezifikation, anstatt Azure die Vorlage für die Bereitstellung zu übermitteln.

Wichtig

Wenn Sie eine Bicep-Datei als Vorlagenspezifikation veröffentlichen, wird Ihr Bicep-Code in eine JSON-Vorlage konvertiert. Beim Konvertieren Ihres Bicep-Codes in JSON werden einige der Informationen in Ihrer Bicep-Datei entfernt. Beispielsweise können Ihre Kommentare, symbolischen Namen für Ressourcen und die Reihenfolge, in der Sie Ihre Ressourcen definieren, fehlen oder in JSON abweichen. Dies bedeutet, dass Sie nicht einfach eine Bicep-Datei als Vorlagenspezifikation veröffentlichen und anschließend die ursprüngliche Bicep-Datei zurück erhalten können (auch als Roundtripping bezeichnet). Es ist eine gute Idee, eine Kopie Ihres ursprünglichen Bicep-Codes in einem Coderepository wie Git aufzubewahren, insbesondere wenn Sie mit Vorlagenspezifikationen arbeiten.

Verwenden Sie das New-AzTemplateSpec-Cmdlet, um eine Vorlagenspezifikation zu erstellen. Das folgende Beispiel zeigt, wie Sie eine Vorlagenspezifikation für Ihre Speicherkontovorlage erstellen können:

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

Sehen wir uns die Parameter im Einzelnen an:

• -Name ist der Ressourcenname der Vorlagenspezifikation, der keine Leerzeichen enthalten darf.
• -Location ist der Speicherort, an dem die Metadaten der Vorlagenspezifikation erstellt werden sollen. Jedoch können Sie die Vorlagenspezifikation in einer beliebigen Region bereitstellen.
• -DisplayName ist ein für Menschen lesbarer Name, der Leerzeichen enthalten darf.
• -Description ist eine für Menschen lesbare Beschreibung, mit der Sie Details zum Inhalt der Vorlagenspezifikation und zu deren möglicher Verwendung bereitstellen können.
• -Version ist die Version der Vorlagenspezifikation. Sie erfahren mehr über Die Versionen weiter unten in diesem Modul.
• -TemplateFile ist der Pfad zur ARM-Vorlage, für die die Vorlagenspezifikation erstellt werden soll.

Verwenden Sie den az ts create-Befehl, um eine Vorlagenspezifikation zu erstellen. Das folgende Beispiel zeigt, wie Sie eine Vorlagenspezifikation für Ihre Speicherkontovorlage erstellen können:

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

Sehen wir uns die Argumente im Einzelnen an:

• --name ist der Ressourcenname der Vorlagenspezifikation, der keine Leerzeichen enthalten darf.
• --location ist der Speicherort, an dem die Metadaten der Vorlagenspezifikation erstellt werden sollen. Jedoch können Sie die Vorlagenspezifikation in einer beliebigen Region bereitstellen.
• --display-name ist ein für Menschen lesbarer Name, der Leerzeichen enthalten darf.
• --description ist eine für Menschen lesbare Beschreibung, mit der Sie Details zum Inhalt der Vorlagenspezifikation und zu deren möglicher Verwendung bereitstellen können.
• --version ist die Version der Vorlagenspezifikation. Sie erfahren mehr über Die Versionen weiter unten in diesem Modul.
• --template-file ist der Pfad zur ARM-Vorlage, für die die Vorlagenspezifikation erstellt werden soll.

Tipp

Darüber hinaus können Sie auch eine Vorlagenspezifikation in einer ARM-Vorlage definieren! Da eine Vorlagenspezifikation ihrerseits eine Azure-Ressource darstellt, können Sie eine Vorlage bereitstellen, die eine Ressource mit dem Typ Microsoft.Deployments/templateSpecs definiert.