Az Azure Resource Manager-sablon specifikációi a Bicepben

Cikk
02/03/2024

A sablon specifikációja egy erőforrástípus egy Azure Resource Manager-sablon (ARM-sablon) későbbi üzembe helyezéshez való tárolásához. Ez az erőforrástípus lehetővé teszi ARM-sablonok megosztását a szervezet más felhasználóival. A többi Azure-erőforráshoz hasonlóan az Azure szerepköralapú hozzáférés-vezérlésével (Azure RBAC) is megoszthatja a sablon specifikációját. Az Azure CLI vagy az Azure PowerShell használatával sablon-specifikációkat hozhat létre Bicep-fájlok megadásával. A Bicep-fájlok arm JSON-sablonokba vannak lefordítva a tárolás előtt. Jelenleg nem importálhat Bicep-fájlt az Azure Portalról sablon-specifikációs erőforrás létrehozásához.

A Microsoft.Resources/templateSpecs a sablon specifikációinak erőforrástípusa. Ez egy fő sablonból és tetszőleges számú csatolt sablonból áll. Az Azure biztonságosan tárolja a sablon specifikációit erőforráscsoportokban. A fő sablonnak és a csatolt sablonoknak is JSON-ban kell lenniük. A sablon specifikációi támogatják a verziószámozást.

A sablon specifikációjának üzembe helyezéséhez olyan szabványos Azure-eszközöket használ, mint a PowerShell, az Azure CLI, az Azure Portal, a REST és más támogatott SDK-k és -ügyfelek. Ugyanazokat a parancsokat használja, mint a sablonhoz vagy a Bicep-fájlhoz.

Feljegyzés

Ha sablon-specifikációkat szeretne használni a Bicepben az Azure PowerShell-lel, telepítenie kell a 6.3.0-s vagy újabb verziót. Az Azure CLI-vel való használatához használja a 2.27.0-s vagy újabb verziót.

Az üzembe helyezés tervezésekor mindig vegye figyelembe az erőforrások életciklusát, és csoportosítsa a hasonló életciklussal rendelkező erőforrásokat egyetlen sablon specifikációba. Az üzemelő példányok például az Azure Cosmos DB több példányát tartalmazzák, és mindegyik példány saját adatbázisokat és tárolókat tartalmaz. Mivel az adatbázisok és a tárolók nem változnak sokat, létre kell hoznia egy sablon-specifikációt, amely tartalmazza a Cosmo DB-példányt és annak mögöttes adatbázisait és tárolóit. Ezután a Bicep-ben feltételes utasítások és másolási hurkok használatával több példányt is létrehozhat ezekből az erőforrásokból.

Tipp.

A modulregisztrációs adatbázis és a sablon specifikációi közötti választás többnyire preferencia kérdése. Ha a kettő közül választ, érdemes megfontolni néhány dolgot:

A modulregisztrációs adatbázist csak a Bicep támogatja. Ha még nem használja a Bicep-et, használja a sablon specifikációit.
A Bicep-modul beállításjegyzékében lévő tartalom csak egy másik Bicep-fájlból telepíthető. A sablon specifikációi közvetlenül az API-ból, az Azure PowerShellből, az Azure CLI-ből és az Azure Portalról telepíthetők. A portál üzembehelyezési felületének testreszabására is használható UiFormDefinition .
A Bicep bizonyos korlátozott képességekkel rendelkezik más projektösszetevők beágyazásához (beleértve a nem Bicep- és nem ARM-sablonfájlokat is). Például PowerShell-szkriptek, PARANCSSOR-szkriptek és egyéb bináris fájlok) a függvények és loadFileAsBase64 a loadTextContent függvények használatával. A sablon specifikációi nem tudják csomagolni ezeket az összetevőket.

Képzési erőforrások

Ha többet szeretne megtudni a sablon specifikációiról, és gyakorlati útmutatást szeretne, olvassa el az újrafelhasználható infrastruktúrakód kódtárainak közzétételével kapcsolatos témakört sablon-specifikációk használatával.

Szükséges engedélyek

A sablon specifikációhoz két Azure-beli buildelési szerepkör van definiálva:

Emellett szüksége van a Bicep-fájlok üzembe helyezéséhez szükséges engedélyekre is. Lásd: Üzembe helyezés – parancssori felület vagy üzembe helyezés – PowerShell.

Miért érdemes sablon specifikációkat használni?

A sablon specifikációi a következő előnyöket biztosítják:

Szabványos ARM-sablonokat vagy Bicep-fájlokat használ a sablon specifikációjához.
Sas-jogkivonatok helyett az Azure RBAC-vel kezelheti a hozzáférést.
A felhasználók anélkül helyezhetik üzembe a sablon specifikációt, hogy írási hozzáféréssel kellene rendelkezniük a Bicep-fájlhoz.
A sablon specifikációja integrálható a meglévő üzembehelyezési folyamatba, például a PowerShell-szkriptbe vagy a DevOps-folyamatba.

A sablon specifikációi lehetővé teszik a canonical sablonok létrehozását és megosztását a szervezet csapataival. A sablon specifikációi biztonságosak, mert elérhetők az Azure Resource Manager számára az üzembe helyezéshez, de nem érhetők el a felhasználók számára a megfelelő engedély nélkül. A felhasználóknak csak olvasási hozzáférésre van szükségük a sablon specifikációhoz a sablon üzembe helyezéséhez, így anélkül oszthatja meg a sablont, hogy mások is módosíthassák.

Ha jelenleg egy GitHub-adattárban vagy tárfiókban vannak a sablonjai, a sablonok megosztása és használata során számos kihívással kell szembesülnie. A sablon üzembe helyezéséhez nyilvánosan elérhetővé kell tennie a sablont, vagy SAS-jogkivonatokkal kell kezelnie a hozzáférést. A korlátozás megkerüléséhez a felhasználók helyi másolatokat hozhatnak létre, amelyek végül eltérnek az eredeti sablontól. A sablon specifikációi leegyszerűsítik a sablonok megosztását.

A sablonspecifikációkban szereplő sablonokat a szervezet rendszergazdáinak ellenőriznie kell a szervezet követelményeinek és útmutatásának megfelelően.

Sablon specifikáció létrehozása

Az alábbi példa egy egyszerű Bicep-fájlt mutat be egy tárfiók Azure-beli létrehozásához.

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

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

Sablon-specifikáció létrehozása a következő használatával:

PowerShell
Parancssori felület

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

az ts create \
  --name storageSpec \
  --version "1.0a" \
  --resource-group templateSpecRG \
  --location "westus2" \
  --template-file "./mainTemplate.bicep"

A sablon specifikációit Bicep-fájlokkal is létrehozhatja. A tartalomnak mainTemplate azonban JSON-ban kell lennie. A következő sablon létrehoz egy sablon-specifikációt egy tárfiók üzembe helyezéséhez:

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

resource createTemplateSpec 'Microsoft.Resources/templateSpecs@2021-05-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@2021-05-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': '2019-06-01'
          'name': 'store$uniquestring(resourceGroup().id)'
          'location': resourceGroup().location
          'kind': 'StorageV2'
          'sku': {
            'name': '[parameters(\'storageAccountType\')]'
          }
        }
      ]
    }
  }
}

A Bicep-fájlba beágyazott JSON-sablonnak a következő módosításokat kell végrehajtania:

Távolítsa el a vonalak végén lévő vesszőt.
Cserélje le a dupla idézőjeleket egyetlen idézőjelre.
A kifejezésekben lévő idézőjelek feloldása. Például: "name": "[parameters(\'storageAccountType\')]".
A Bicep-fájlban definiált paraméterek és változók eléréséhez közvetlenül használhatja a paraméterneveket és a változóneveket. A megadott mainTemplateparaméterek és változók eléréséhez továbbra is az ARM JSON-sablon szintaxisát kell használnia. Például: "name": "[parameters(\'storageAccountType\')]".
A Bicep-függvények meghívásához használja a Bicep szintaxist. Például a "location" (hely): resourceGroup().location.

A sablon specifikációjának mérete körülbelül 2 MB. Ha egy sablon specifikációjának mérete meghaladja a korlátot, a TemplateSpecTooLarge hibakód jelenik meg. A hibaüzenet a következőt mondja:

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.

Az előfizetés összes sablon-specifikációját a következőkkel tekintheti meg:

PowerShell
Parancssori felület

Get-AzTemplateSpec

az ts list

Megtekintheti a sablon specifikációinak részleteit, beleértve annak verzióit a következőkkel:

PowerShell
Parancssori felület

Get-AzTemplateSpec -ResourceGroupName templateSpecsRG -Name storageSpec

az ts show \
    --name storageSpec \
    --resource-group templateSpecRG \
    --version "1.0a"

Sablon specifikáció üzembe helyezése

Miután létrehozta a sablon specifikációját, a Sablon specifikációi olvasó szerepkörrel rendelkező felhasználók üzembe helyezhetik azt. Emellett szüksége van az ARM-sablon üzembe helyezéséhez szükséges engedélyekre is. Lásd: Üzembe helyezés – parancssori felület vagy üzembe helyezés – PowerShell.

A sablon specifikációi üzembe helyezhetők a portálon, a PowerShellen, az Azure CLI-en vagy bicep modulként egy nagyobb sablontelepítésben. A szervezet felhasználói az Azure bármely hatókörében (erőforráscsoportban, előfizetésben, felügyeleti csoportban vagy bérlőben) üzembe helyezhetnek egy sablon-specifikációt.

Ahelyett, hogy egy Bicep-fájl elérési útján vagy URI-jában halad át, egy sablonspektrálist helyez üzembe az erőforrás-azonosító megadásával. Az erőforrás-azonosító formátuma a következő:

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

Figyelje meg, hogy az erőforrás-azonosító tartalmazza a sablon specifikációjának verziónevét.

Például a következő paranccsal helyez üzembe egy sablon specifikációt.

PowerShell
Parancssori felület

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

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

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

az deployment group create \
  --resource-group demoRG \
  --template-spec $id

A gyakorlatban általában futtatja Get-AzTemplateSpec vagy az ts show lekéri az üzembe helyezni kívánt sablon-specifikáció azonosítóját.

PowerShell
Parancssori felület

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

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

id = $(az ts show --name storageSpec --resource-group templateSpecRG --version "1.0a" --query "id")

az deployment group create \
  --resource-group demoRG \
  --template-spec $id

Egy URL-címet a következő formátumban is megnyithat a sablon specifikációjának üzembe helyezéséhez:

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}

Paraméterek

A paraméterek sablonspektrálnak való átadása hasonló a paraméterek Bicep-fájlba való továbbításához. Adja hozzá a paraméterértékeket beágyazott vagy paraméterfájlban.

Beágyazott paraméterek

Paraméter beágyazott átadásához használja a következőt:

PowerShell
Parancssori felület

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

az deployment group create \
  --resource-group demoRG \
  --template-spec $id \
  --parameters storageAccountType='Standard_GRS'

Paraméterfájlok

Bicep paraméterfájl használata

Bicep-paraméterfájl létrehozásához meg kell adnia az utasítást using . Egy példa:
```
using 'using 'ts:<subscription-id>/<resource-group-name>/<template-spec-name>:<tag>'

param StorageAccountType = 'Standard_GRS'
```
További információ: Bicep parameters file.

Paraméterfájl átadása a következővel:
- PowerShell
- Parancssori felület
Az Azure PowerShell használatával jelenleg nem helyezhet üzembe sablonspektrest .bicepparam fájllal.
```
az deployment group create \
  --resource-group demoRG \
  --parameters "./mainTemplate.bicepparam"
```
using A bicepparam fájlban lévő utasítás miatt. Nem kell megadnia a paramétert --template-spec .

JSON-paraméterfájl használata

A következő JSON-minta JSON-paraméterfájl:

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

És adja át a paraméterfájlt a következővel:

PowerShell
Parancssori felület

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

az deployment group create \
  --resource-group demoRG \
  --template-spec $id \
  --parameters "./mainTemplate.parameters.json"

Verziókezelés

Amikor létrehoz egy sablon-specifikációt, meg kell adnia annak egy verziónevét. A sablonkód iterációja során frissíthet egy meglévő verziót (gyorsjavításokhoz), vagy közzétehet egy új verziót. A verzió egy szöveges sztring. Bármilyen verziószámozási rendszert követhet, beleértve a szemantikai verziókövetést is. A sablon specifikációjának felhasználói megadhatják a telepítéskor használni kívánt verziónevet. Korlátlan számú verzióval rendelkezhet.

Címkék használata

A címkék segítenek az erőforrások logikus rendszerezésében. Címkéket adhat hozzá a sablon specifikációihoz az Azure PowerShell és az Azure CLI használatával. Az alábbi példa bemutatja, hogyan adhat meg címkéket a sablon specifikációjának létrehozásakor:

PowerShell
Parancssori felület

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

az ts create \
  --name storageSpec \
  --version "1.0a" \
  --resource-group templateSpecRG \
  --location "westus2" \
  --template-file "./mainTemplate.bicep" \
  --tags Dept=Finance Environment=Production

A következő példa bemutatja, hogyan alkalmazhat címkéket egy meglévő sablon specifikációjának frissítésekor:

PowerShell
Parancssori felület

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

az ts update \
  --name storageSpec \
  --version "1.0a" \
  --resource-group templateSpecRG \
  --location "westus2" \
  --template-file "./mainTemplate.bicep" \
  --tags Dept=Finance Environment=Production

A sablon és a verziók is tartalmazhatnak címkéket. A címkék a megadott paraméterektől függően lesznek alkalmazva vagy örökölve.

Sablon specifikációja	Verzió	Verzióparaméter	Címkeparaméter	Értékek címkézése
Létezik	n/a	Nincs megadva	Megadott	sablon specifikációra alkalmazva
Létezik	Új	Megadott	Nincs megadva	a sablon specifikációjától a verzióig öröklődik
Új	Új	Megadott	Megadott	sablon specifikációra és verzióra is alkalmazva
Létezik	Új	Megadott	Megadott	a verzióra alkalmazva
Létezik	Létezik	Megadott	Megadott	a verzióra alkalmazva

Hivatkozás a sablon specifikációira

Miután létrehozott egy sablon-specifikációt, hivatkozhat a sablon specifikációra egy Bicep-modulban. A sablon specifikációja a modult tartalmazó Bicep-fájl üzembe helyezésekor lesz üzembe helyezve. További információ: Fájl a sablon specifikációjában.

A modul csatolásához használt sablon-specifikációk aliasainak létrehozásához tekintse meg a modulok aliasait.