Specifikace šablon Azure Resource Manageru v Bicep

  • Článek

Specifikace šablony je typ prostředku pro uložení šablony Azure Resource Manageru (šablony ARM) pro pozdější nasazení. Tento typ prostředku umožňuje sdílet šablony ARM s ostatními uživateli ve vaší organizaci. Stejně jako jakýkoli jiný prostředek Azure můžete ke sdílení specifikace šablony použít řízení přístupu na základě role v Azure (Azure RBAC). Pomocí Azure CLI nebo Azure PowerShellu můžete vytvořit specifikace šablon tím, že poskytnete soubory Bicep. Soubory Bicep se před uložením překládají do šablon JSON ARM. V současné době nemůžete importovat soubor Bicep z webu Azure Portal a vytvořit prostředek specifikace šablony.

Microsoft.Resources/templateSpecs je typ prostředku pro specifikace šablon. Skládá se z hlavní šablony a libovolného počtu propojených šablon. Azure bezpečně ukládá specifikace šablon ve skupinách prostředků. Hlavní i propojené šablony musí být ve formátu JSON. Specifikace šablon podporují správu verzí.

K nasazení specifikace šablony použijete standardní nástroje Azure, jako jsou PowerShell, Azure CLI, Azure Portal, REST a další podporované sady SDK a klienti. Použijete stejné příkazy jako pro šablonu nebo soubor Bicep.

Poznámka:

Pokud chcete použít specifikace šablon v Bicep s Azure PowerShellem, musíte nainstalovat verzi 6.3.0 nebo novější. Pokud ho chcete použít s Azure CLI, použijte verzi 2.27.0 nebo novější.

Při navrhování nasazení vždy zvažte životní cyklus prostředků a seskupte prostředky, které sdílejí podobný životní cyklus, do specifikace jedné šablony. Vaše nasazení například zahrnují několik instancí služby Azure Cosmos DB s každou instancí, která obsahuje vlastní databáze a kontejnery. Vzhledem k tomu, že databáze a kontejnery se moc nemění, chcete vytvořit jednu specifikaci šablony, která zahrnuje instanci databáze Cosmo a její podkladové databáze a kontejnery. Podmíněné příkazy pak můžete použít v Bicep spolu se smyčkami kopírování k vytvoření více instancí těchto prostředků.

Tip

Volba mezi registrem modulů a specifikacemi šablon je většinou otázkou preference. Při výběru mezi těmito dvěma možnostmi je potřeba vzít v úvahu několik věcí:

  • Registr modulů podporuje pouze Bicep. Pokud ještě nepoužíváte Bicep, použijte specifikace šablon.
  • Obsah v registru modulu Bicep lze nasadit pouze z jiného souboru Bicep. Specifikace šablon je možné nasadit přímo z rozhraní API, Azure PowerShellu, Azure CLI a webu Azure Portal. Můžete dokonce použít UiFormDefinition k přizpůsobení prostředí nasazení portálu.
  • Bicep má několik omezených možností pro vkládání jiných artefaktů projektu (včetně souborů mimo Bicep a souborů bez šablony ARM). Například skripty PowerShellu, skripty rozhraní příkazového řádku a další binární soubory) pomocí funkcí loadTextContent a loadFileAsBase64 funkcí. Specifikace šablon nemohou tyto artefakty zabalit.

Školicí materiály

Další informace o specifikacích šablon a praktické pokyny najdete v tématu Publikování knihoven opakovaně použitelného kódu infrastruktury pomocí specifikací šablon.

Požadována oprávnění

Pro specifikaci šablony jsou definované dvě předdefinované role Azure:

Kromě toho potřebujete také oprávnění k nasazení souboru Bicep. Viz Nasazení – rozhraní příkazového řádku nebo nasazení – PowerShell.

Proč používat specifikace šablon?

Specifikace šablon poskytují následující výhody:

  • Pro specifikaci šablony použijete standardní šablony ARM nebo soubory Bicep.
  • Přístup spravujete prostřednictvím Azure RBAC místo tokenů SAS.
  • Uživatelé mohou nasadit specifikaci šablony bez přístupu k zápisu do souboru Bicep.
  • Specifikaci šablony můžete integrovat do existujícího procesu nasazení, jako je skript PowerShellu nebo kanál DevOps.

Specifikace šablon umožňují vytvářet kanonické šablony a sdílet je s týmy ve vaší organizaci. Specifikace šablon jsou zabezpečené, protože jsou dostupné pro Azure Resource Manager pro nasazení, ale nejsou přístupné uživatelům bez správného oprávnění. Uživatelé potřebují ke specifikaci šablony přístup jen pro čtení, abyste mohli šablonu nasadit, abyste ji mohli sdílet bez toho, aby ji ostatní mohli upravovat.

Pokud aktuálně máte šablony v úložišti GitHubu nebo účtu úložiště, při pokusu o sdílení a používání šablon narazíte na několik problémů. Pokud chcete šablonu nasadit, musíte šablonu nastavit jako veřejně přístupnou nebo spravovat přístup pomocí tokenů SAS. Pokud chcete toto omezení obejít, můžou uživatelé vytvářet místní kopie, které se nakonec liší od původní šablony. Specifikace šablon zjednodušují sdílení šablon.

Šablony, které zahrnete do specifikace šablony, by měli ověřit správci ve vaší organizaci, aby postupovali podle požadavků a pokynů organizace.

Vytvoření specifikace šablony

Následující příklad ukazuje jednoduchý soubor Bicep pro vytvoření účtu úložiště v 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'
}

Vytvořte specifikaci šablony pomocí:

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

Specifikace šablon můžete vytvořit také pomocí souborů Bicep. Obsah mainTemplate však musí být ve formátu JSON. Následující šablona vytvoří specifikaci šablony pro nasazení účtu úložiště:

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\')]'
          }
        }
      ]
    }
  }
}

Šablona JSON vložená do souboru Bicep musí provést tyto změny:

  • Odeberte čárky na konci řádků.
  • Dvojité uvozovky nahraďte jednoduchými uvozovkami.
  • Uvozovky v rámci výrazů uvozovek uvozovek. Například 'name': '[parameters(\'storageAccountType\')]'.
  • Pokud chcete získat přístup k parametrům a proměnným definovaným v souboru Bicep, můžete přímo použít názvy parametrů a názvy proměnných. Pokud chcete získat přístup k parametrům a proměnným definovaným v mainTemplatesouboru , musíte stále použít syntaxi šablony JSON ARM. Například 'name': '[parameters(\'storageAccountType\')]'.
  • K volání funkcí Bicep použijte syntaxi Bicep. Například location: resourceGroup().location.

Velikost specifikace šablony je omezená na přibližnou velikost 2 MB. Pokud velikost specifikace šablony překročí limit, získáte kód chyby TemplateSpecTooLarge . Chybová zpráva říká:

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.

Všechny specifikace šablon ve vašem předplatném můžete zobrazit pomocí:

Get-AzTemplateSpec

Můžete zobrazit podrobnosti o specifikaci šablony, včetně jeho verzí:

Get-AzTemplateSpec -ResourceGroupName templateSpecsRG -Name storageSpec

Nasazení specifikace šablony

Po vytvoření specifikace šablony ji můžou uživatelé s rolí Čtenář specifikací šablony nasadit. Kromě toho potřebujete také oprávnění k nasazení šablony ARM. Viz Nasazení – rozhraní příkazového řádku nebo nasazení – PowerShell.

Specifikace šablon je možné nasadit prostřednictvím portálu, PowerShellu, Azure CLI nebo modulu Bicep ve větším nasazení šablony. Uživatelé v organizaci můžou nasadit specifikaci šablony do libovolného oboru v Azure (skupina prostředků, předplatné, skupina pro správu nebo tenant).

Místo předání cesty nebo identifikátoru URI pro soubor Bicep nasadíte specifikaci šablony zadáním ID prostředku. ID prostředku má následující formát:

/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.Resources/templateSpecs/{template-spec-name}/versions/{template-spec-version}

Všimněte si, že ID prostředku obsahuje název verze specifikace šablony.

Například nasadíte specifikaci šablony pomocí následujícího příkazu.

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

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

V praxi obvykle spustíte Get-AzTemplateSpec nebo az ts show získáte ID specifikace šablony, kterou chcete nasadit.

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

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

Pokud chcete nasadit specifikaci šablony, můžete také otevřít adresu URL v následujícím formátu:

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}

Parametry

Předávání parametrů do specifikace šablony se podobá předávání parametrů do souboru Bicep. Přidejte hodnoty parametrů buď vložené, nebo do souboru parametrů.

Vložené parametry

Pokud chcete předat vložený parametr, použijte:

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

Soubory parametrů

  • Použití souboru parametrů Bicep

    Chcete-li vytvořit soubor parametrů Bicep, musíte zadat using příkaz. Tady je příklad:

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

param StorageAccountType = 'Standard_GRS'

    Další informace naleznete v souboru parametrů Bicep.

    Předání souboru parametrů pomocí:

    V současné době nemůžete nasadit specifikaci šablony se souborem .bicepparam pomocí Azure PowerShellu.

  • Použití souboru parametrů JSON

    Následující JSON je ukázkový soubor parametrů JSON:

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

    A tento soubor parametrů předejte takto:

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

Vytváření verzí

Když vytvoříte specifikaci šablony, zadáte pro ni název verze. Při iteraci kódu šablony můžete buď aktualizovat existující verzi (pro opravy hotfix), nebo publikovat novou verzi. Verze je textový řetězec. Můžete postupovat podle libovolného systému správy verzí, včetně sémantické správy verzí. Uživatelé specifikace šablony můžou zadat název verze, kterou chtějí použít při nasazení. Můžete mít neomezený počet verzí.

Použití značek

Značky pomáhají logicky uspořádat prostředky. Ke specifikacím šablon můžete přidat značky pomocí Azure PowerShellu a Azure CLI. Následující příklad ukazuje, jak určit značky při vytváření specifikace šablony:

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

Následující příklad ukazuje, jak použít značky při aktualizaci existující specifikace šablony:

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

Šablona i její verze můžou mít značky. Značky se použijí nebo zdědí v závislosti na zadaných parametrech.

Specifikace šablony Verze Parametr verze Parametr značky Hodnoty značek
Exists – Neurčeno Určeno použité na specifikaci šablony
Exists Nová Určeno Neurčeno zděděno ze specifikace šablony do verze
Nová Nová Určeno Určeno použito pro specifikaci šablony i verzi
Exists Nová Určeno Určeno použitou na verzi
Exists Exists Určeno Určeno použitou na verzi

Po vytvoření specifikace šablony můžete tuto specifikaci šablony propojit v modulu Bicep. Specifikace šablony se nasadí při nasazení souboru Bicep obsahujícího tento modul. Další informace naleznete v části Soubor ve specifikaci šablony.

Pokud chcete vytvořit aliasy pro specifikace šablon určené pro propojení modulů, přečtěte si téma Aliasy pro moduly.

Další kroky

Další informace o specifikacích šablon a praktické pokyny najdete v tématu Publikování knihoven opakovaně použitelného kódu infrastruktury pomocí specifikací šablon.