Freigeben über

Azure Resource Manager-Vorlagenspezifikationen in Bicep

  • Artikel

Eine Vorlagenspezifikation ist ein Ressourcentyp zum Speichern einer Azure Resource Manager-Vorlage (ARM-Vorlage) für die spätere Bereitstellung. Mit diesem Ressourcentyp können Sie ARM-Vorlagen mit anderen Benutzer in Ihrer Organisation teilen. Wie jede andere Azure-Ressource können Sie die rollenbasierte Zugriffssteuerung von Azure (Azure RBAC) verwenden, um die Vorlagenspezifikation gemeinsam zu nutzen. Sie können die Azure CLI oder Azure PowerShell verwenden, um Vorlagenspezifikationen zu erstellen, indem Sie Bicep-Dateien bereitstellen. Die Bicep-Dateien werden in ARM JSON-Vorlagen transpiliert, bevor sie gespeichert werden. Derzeit können Sie keine Bicep-Datei aus dem Azure-Portal importieren, um eine Vorlagenspezifikationenressource zu erstellen.

Microsoft.Resources/templateSpecs ist der Ressourcentyp für Vorlagenspezifikationen. Er besteht aus einer Hauptvorlage und einer beliebigen Anzahl von verknüpften Vorlagen. Azure speichert Vorlagenspezifikationen sicher in Ressourcengruppen. Sowohl die Hauptvorlage als auch die verknüpften Vorlagen müssen in JSON enthalten sein. Vorlagenspezifikationen unterstützen Versionsverwaltung.

Zum Bereitstellen der Vorlagenspezifikation verwenden Sie Azure-Standardtools wie PowerShell, Azure CLI, Azure-Portal, REST und andere unterstützte SDKs und Clients. Sie verwenden dieselben Befehle wie für die Vorlage oder die Bicep-Datei.

Hinweis

Um Vorlagenspezifikationen mit Azure PowerShell zu verwenden, müssen Sie mindestens Version 6.3.0 installieren. Zur Anwendung von Azure CLI verwenden Sie mindestens Version 2.27.0 oder höher.

Berücksichtigen Sie beim Entwerfen Ihre Bereitstellung immer den Lebenszyklus der Ressourcen, und gruppieren Sie Ressourcen mit demselben Lebenszyklus in eine einzige Vorlagenspezifikation. Beispiel: Ihre Bereitstellungen umfassen mehrere Instanzen von Azure Cosmos DB, wobei jede Instanz eigene Datenbanken und Container enthält. Unter der Annahme, dass sich die Datenbanken und Container nur wenig ändern werden, sollten Sie eine Vorlagenspezifikation für eine Cosmos DB-Instanz und ihre zugrunde liegenden Datenbanken und Container erstellen. Anschließend können Sie bedingte Anweisungen in Ihrem Bicep zusammen mit Kopierschleifen verwenden, um mehrere Instanzen dieser Ressourcen zu erstellen.

Tipp

Die Wahl zwischen Modulregistrierung und Vorlagenspezifikationen ist meist eine Frage der Präferenz. Es gibt einige Aspekte, die Sie beachten sollten, wenn Sie sich für eine Variante entscheiden:

  • Die Modulregistrierung wird nur von Bicep unterstützt. Wenn Sie Bicep noch nicht nutzen, verwenden Sie Vorlagenspezifikationen.
  • Inhalte in der Bicep-Modulregistrierung können nur aus einer anderen Bicep-Datei bereitgestellt werden. Vorlagenspezifikationen können direkt über die API, Azure PowerShell, Azure CLI und das Azure-Portal bereitgestellt werden. Sie können sogar UiFormDefinition verwenden, um die Bereitstellung über das Portal anzupassen.
  • Bicep verfügt über einige eingeschränkte Funktionen zum Einbetten anderer Projektartefakte (einschließlich Nicht-Bicep- und Nicht-ARM-Vorlagendateien, beispielsweise PowerShell-Skripts, CLI-Skripts und andere Binärdateien) mithilfe der Funktionen loadTextContent und loadFileAsBase64. Diese Artefakte können nicht in Vorlagenspezifikationen gepackt werden.

Schulungsressourcen

Weitere Informationen zu Vorlagenspezifikationen und praktische Anleitungen finden Sie unter Veröffentlichen von Bibliotheken mit wiederverwendbarem Infrastrukturcode mithilfe von Vorlagenspezifikationen.

Erforderliche Berechtigungen

Für die Vorlagenspezifikation sind zwei integrierte Azure-Rollen definiert:

Darüber hinaus benötigen Sie auch die Berechtigungen für die Bereitstellung einer Bicep-Datei. Weitere Informationen finden Sie unter Verwenden von ARM-Bereitstellungsvorlagen (Azure Resource Manager) mit der Azure CLI bzw. Bereitstellen von Ressourcen mit ARM-Vorlagen und Azure PowerShell.

Gründe zur Verwendung von Vorlagenspezifikationen

Vorlagenspezifikationen bieten die folgenden Vorteile:

  • Sie verwenden Standard ARM Vorlagen oder Bicep-Dateien für Ihre Vorlagenspezifikation.
  • Sie verwalten den Zugriff über Azure RBAC, statt mit SAS-Token.
  • Benutzer können die Vorlagenspezifikation bereitstellen, ohne Zugriff auf die Bicep-Datei zu haben.
  • Sie können die Vorlagenspezifikation in den vorhandenen Bereitstellungsprozess integrieren, z. B. ein PowerShell-Skript oder eine DevOps-Pipeline.

Vorlagenspezifikationen ermöglichen es Ihnen, kanonische Vorlagen zu erstellen und mit Teams in Ihrer Organisation zu teilen. Die Vorlagenspezifikationen sind sicher, weil sie für die Bereitstellung für den Azure Resource Manager verfügbar aber nicht für Benutzer ohne die richtigen Berechtigungen zugänglich sind. Benutzer benötigen nur Lesezugriff auf die Vorlagenspezifikation, um die zugehörige Vorlage bereitzustellen, sodass Sie die Vorlage teilen können, ohne anderen Benutzern das Ändern zu gestatten.

Wenn Sie Ihre Vorlagen derzeit in einem GitHub-Repository oder Speicherkonto aufbewahren, stellen sich mehrere Herausforderungen in Ihren Weg, wenn Sie versuchen, die Vorlagen freizugeben und zu verwenden. Zum Bereitstellen der Vorlage müssen Sie entweder die Vorlage öffentlich zugänglich machen oder den Zugriff mit SAS-Token verwalten. Um diese Einschränkung zu umgehen, können Benutzer lokale Kopien erstellen, die letztendlich von Ihrer ursprünglichen Vorlage abweichen. Vorlagenspezifikationen vereinfachen das Teilen von Vorlagen.

Die Vorlagen, die Sie in eine Vorlagenspezifikation aufnehmen, sollten von Administratoren in Ihrer Organisation überprüft werden, damit sie die Anforderungen und Richtlinien der Organisation einhalten.

Erstellen von Vorlagenspezifikationen

Das folgende Beispiel zeigt eine einfache Bicep-Datei zum Erstellen eines Speicherkontos in Azure.

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
param storageAccountType string = 'Standard_LRS'

resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name:  'store${uniqueString(resourceGroup().id)}'
  location: resourceGroup().location
  sku: {
    name: storageAccountType
  }
  kind:'StorageV2'
}

Erstellen einer Vorlagenspezifikation mittels:

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

Sie können auch Spezifikationsvorlagen mit Hilfe einer Bicep-Dateien erstellen. Der Inhalt von muss mainTemplate jedoch in JSON enthalten sein. Die folgende Vorlage erstellt eine Vorlagenspezifikation zum Bereitstellen eines Speicherkontos:

param templateSpecName string = 'CreateStorageAccount'
param templateSpecVersionName string = '0.1'
param location string = resourceGroup().location

resource createTemplateSpec 'Microsoft.Resources/templateSpecs@2022-02-01' = {
  name: templateSpecName
  location: location
  properties: {
    description: 'A basic templateSpec - creates a storage account.'
    displayName: 'Storage account (Standard_LRS)'
  }
}

resource createTemplateSpecVersion 'Microsoft.Resources/templateSpecs/versions@2022-02-01' = {
  parent: createTemplateSpec
  name: templateSpecVersionName
  location: location
  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': '2023-04-01'
          'name': 'store$uniquestring(resourceGroup().id)'
          'location': resourceGroup().location
          'kind': 'StorageV2'
          'sku': {
            'name': '[parameters(\'storageAccountType\')]'
          }
        }
      ]
    }
  }
}

Die in die Bicep-Datei eingebettete JSON-Vorlage muss die folgenden Änderungen vornehmen:

  • Entfernen Sie die Kommas am Ende der Zeilen.
  • Ersetzen Sie doppelte Anführungszeichen durch einfache Anführungszeichen.
  • Erstellen Sie ein Escapezeichen aus den einzelnen Anführungszeichen in den Ausdrücken. Beispiel: 'name': '[parameters(\'storageAccountType\')]'.
  • Für den Zugriff auf die in der Bicep-Datei definierten Parameter und Variablen können Sie die Parameternamen und die Variablennamen direkt verwenden. Für den Zugriff auf die in definierten Parameter und Variablen müssen Sie weiterhin die mainTemplate JSON ARM Vorlagensyntax verwenden. Beispiel: 'name': '[parameters(\'storageAccountType\')]'.
  • Rufen Sie mithilfe der Bicep-Syntax die Bicep-Funktionen auf. Beispiel: 'location': resourceGroup().location.

Die Größe einer Vorlagenspezifikation ist auf ca. 2 MB begrenzt. Wenn die Größe einer Vorlagenspezifikation den Grenzwert überschreitet, erhalten Sie den Fehlercode TemplateSpecTooLarge. Die Fehlermeldung lautet:

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.

Sie können alle Vorlagenspezifikationen in Ihrem Abonnement anzeigen mithilfe von:

Get-AzTemplateSpec

Sie können Details einer Vorlagenspezifikation anzeigen, einschließlich ihrer Versionen, mittels:

Get-AzTemplateSpec -ResourceGroupName templateSpecsRG -Name storageSpec

Bereitstellen von Vorlagenspezifikationen

Nachdem Sie die Vorlagenspezifikation erstellt haben, können Benutzer mit der Rolle Vorlagenspezifikationsleser diese bereitstellen. Darüber hinaus benötigen Sie auch die Berechtigungen für die Bereitstellung einer ARM-Vorlage. Weitere Informationen finden Sie unter Verwenden von ARM-Bereitstellungsvorlagen (Azure Resource Manager) mit der Azure CLI bzw. Bereitstellen von Ressourcen mit ARM-Vorlagen und Azure PowerShell.

Vorlagenspezifikationen können über das Portal, mittels PowerShell, Azure CLI oder als Bicep-Modul in einer größeren Vorlagenbereitstellung bereitgestellt werden. Benutzer in einer Organisation können eine Vorlagenspezifikation in einem beliebigen Bereich in Azure (Ressourcengruppe, Abonnement, Verwaltungsgruppe oder Mandant) bereitstellen.

Anstatt einen Pfad oder URI als Eingabe für eine Vorlage zu übergeben, stellen Sie eine Vorlagenspezifikation bereit, indem Sie deren Ressourcen-ID angeben. Die Ressourcen-ID hat folgendes Format:

/subscriptions/{Abonnement-ID}/resourceGroups/{Ressourcengruppe}/providers/Microsoft.Resources/templateSpecs/{Vorlagenspezifikation-Name}/versions/{Vorlagenspezifikation-Version}

Beachten Sie, dass die Ressourcen-ID ein Versionsname für die Vorlagenspezifikation enthält.

Beispielsweise stellen Sie eine Vorlagenspezifikation mit dem folgenden Befehl bereit.

$id = "/subscriptions/11111111-1111-1111-1111-111111111111/resourceGroups/templateSpecsRG/providers/Microsoft.Resources/templateSpecs/storageSpec/versions/1.0a"

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

In der Praxis führen Sie in der Regel Get-AzTemplateSpec oder az ts show aus, um die ID der Vorlagenspezifikation abzurufen, die Sie bereitstellen möchten.

$id = (Get-AzTemplateSpec -Name storageSpec -ResourceGroupName templateSpecsRg -Version 1.0a).Versions.Id

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

Sie können auch eine URL im folgenden Format öffnen, um eine Vorlagenspezifikation bereitzustellen:

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}

Parameter

Das Übergeben von Parametern an eine Vorlagenspezifikation ist ähnlich wie das Übergeben von Parametern an eine Bicep-Datei. Fügen Sie die Parameterwerte entweder inline oder in einer Parameterdatei hinzu.

Inlineparameter

Verwenden Sie für die Inlineübergabe eines Parameters:

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

Parameterdateien

  • Verwenden der Bicep-Parameterdatei

    Zum Erstellen einer Bicep-Parameterdatei müssen Sie die using-Anweisung angeben. Ein Beispiel:

    using 'using 'ts:<subscription-id>/<resource-group-name>/<template-spec-name>:<tag>'

param StorageAccountType = 'Standard_GRS'

    Weitere Informationen finden Sie unter Bicep-Parameterdatei.

    Übergeben der Parameterdatei mit:

    Derzeit können Sie eine Vorlagenspezifikation nicht mit einer .bicepparam-Datei mithilfe von Azure PowerShell bereitstellen.

  • Verwenden der JSON-Parameterdatei

    Der folgende JSON-Code ist ein Beispiel für die JSON-Parameterdatei:

    {
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "StorageAccountType": {
      "value": "Standard_GRS"
    }
  }
}

    Und übergeben Sie diese Parameterdatei mit:

    New-AzResourceGroupDeployment `
  -TemplateSpecId $id `
  -ResourceGroupName demoRG `
  -TemplateParameterFile ./mainTemplate.parameters.json

Versionsverwaltung

Wenn Sie eine Vorlagenspezifikation erstellen, geben Sie einen Versionsnamen dafür an. Wenn Sie den Vorlagencode durchlaufen, können Sie entweder eine vorhandene Version aktualisieren (für Hotfixes) oder eine neue Version veröffentlichen. Die Version ist eine Textzeichenfolge. Sie können sich für ein beliebiges Versionskontrollsystem entscheiden, einschließlich einer semantischen Versionsverwaltung. Benutzer der Vorlagenspezifikation können den Versionsnamen angeben, die sie bei der Bereitstellung verwenden möchten. Sie können über eine unbegrenzte Anzahl von Versionen verfügen.

Verwenden von Tags

Tags helfen Ihnen dabei, Ihre Ressourcen logisch zu organisieren. Mithilfe von Azure PowerShell und der Azure CLI können Sie Tags zu Vorlagenspezifikationen hinzufügen. Das folgende Beispiel zeigt, wie Tags beim Erstellen der Vorlagenspezifikation angegeben werden:

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

Das nächste Beispiel zeigt, wie Tags beim Aktualisieren einer vorhandenen Vorlagenspezifikation angewendet werden:

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

Sowohl die Vorlage als auch ihre Versionen können Tags aufweisen. Die Tags werden in Abhängigkeit von den von Ihnen angegebenen Parametern angewendet oder geerbt.

Vorlagenspezifikation Version Versionsparameter Tagparameter Tagwerte
Exists – Nicht angegeben Angegeben auf die Vorlagenspezifikation angewendet
Exists Neu Angegeben Nicht angegeben von der Vorlagenspezifikation an die Version geerbt
Neu Neu Angegeben Angegeben auf Vorlagenspezifikation und -version angewendet
Exists Neu Angegeben Angegeben auf die Version angewendet
Exists Exists Angegeben Angegeben auf die Version angewendet

Nach dem Erstellen einer Vorlagenspezifikation können Sie in einem Bicep-Modul eine Verknüpfung zu dieser Vorlagenspezifikation erstellen. Die Vorlagenspezifikation wird bereitgestellt, wenn Sie die Bicep-Datei bereitstellen, die dieses Modul enthält. Weitere Informationen finden Sie unter Datei in Vorlagenspezifikation.

Informationen zum Erstellen von Aliasen für Vorlagenspezifikationen, die für die Modulverknüpfung vorgesehen sind, finden Sie unter Aliase für Module.

Nächste Schritte

Weitere Informationen zu Vorlagenspezifikationen und praktische Anleitungen finden Sie unter Veröffentlichen von Bibliotheken mit wiederverwendbarem Infrastrukturcode mithilfe von Vorlagenspezifikationen.