Specyfikacje szablonu usługi Azure Resource Manager w aplikacji Bicep

Artykuł
09/26/2024

Specyfikacja szablonu to typ zasobu do przechowywania szablonu usługi Azure Resource Manager (szablon usługi ARM) na potrzeby późniejszego wdrożenia. Ten typ zasobu umożliwia udostępnianie szablonów usługi ARM innym użytkownikom w organizacji. Podobnie jak każdy inny zasób platformy Azure, możesz użyć kontroli dostępu opartej na rolach (RBAC) platformy Azure, aby udostępnić specyfikację szablonu. Interfejs wiersza polecenia platformy Azure lub program Azure PowerShell umożliwia tworzenie specyfikacji szablonu, dostarczając pliki Bicep. Pliki Bicep są transpilowane do szablonów JSON usługi ARM przed ich zapisaniem. Obecnie nie można zaimportować pliku Bicep z witryny Azure Portal, aby utworzyć zasób specyfikacji szablonu.

Microsoft.Resources/templateSpecs to typ zasobu dla specyfikacji szablonu. Składa się z głównego szablonu i dowolnej liczby połączonych szablonów. Platforma Azure bezpiecznie przechowuje specyfikacje szablonów w grupach zasobów. Zarówno główny szablon, jak i połączone szablony muszą znajdować się w formacie JSON. Specyfikacje szablonu obsługują przechowywanie wersji.

Aby wdrożyć specyfikację szablonu, użyj standardowych narzędzi platformy Azure, takich jak program PowerShell, interfejs wiersza polecenia platformy Azure, witryna Azure Portal, interfejs REST i inne obsługiwane zestawy SDK i klienci. Używasz tych samych poleceń, co w przypadku szablonu lub pliku Bicep.

Uwaga

Aby użyć specyfikacji szablonu w programie Bicep w programie Azure PowerShell, musisz zainstalować wersję 6.3.0 lub nowszą. Aby używać go z interfejsem wiersza polecenia platformy Azure, użyj wersji 2.27.0 lub nowszej.

Podczas projektowania wdrożenia zawsze należy wziąć pod uwagę cykl życia zasobów i grupować zasoby, które współużytkują podobny cykl życia w jedną specyfikację szablonu. Na przykład wdrożenia obejmują wiele wystąpień usługi Azure Cosmos DB z każdym wystąpieniem zawierającym własne bazy danych i kontenery. Biorąc pod uwagę, że bazy danych i kontenery nie zmieniają się zbytnio, chcesz utworzyć jedną specyfikację szablonu, aby uwzględnić wystąpienie bazy danych Cosmo DB i jego bazowych baz danych i kontenerów. Następnie możesz użyć instrukcji warunkowych w Bicep wraz z pętlami kopiowania, aby utworzyć wiele wystąpień tych zasobów.

Napiwek

Wybór między rejestrem modułów a specyfikacjami szablonów jest głównie kwestią preferencji. Istnieje kilka kwestii, które należy wziąć pod uwagę podczas wyboru między nimi:

Rejestr modułów jest obsługiwany tylko przez Bicep. Jeśli jeszcze nie używasz Bicep, użyj specyfikacji szablonu.
Zawartość rejestru modułów Bicep można wdrożyć tylko z innego pliku Bicep. Specyfikacje szablonów można wdrażać bezpośrednio z poziomu interfejsu API, programu Azure PowerShell, interfejsu wiersza polecenia platformy Azure i witryny Azure Portal. Możesz nawet użyć UiFormDefinition polecenia , aby dostosować środowisko wdrażania portalu.
Bicep ma pewne ograniczone możliwości osadzania innych artefaktów projektu (w tym plików szablonów innych niż Bicep i innych niż ARM. Na przykład skrypty programu PowerShell, skrypty interfejsu wiersza polecenia i inne pliki binarne) przy użyciu loadTextContent funkcji i loadFileAsBase64 . Specyfikacje szablonu nie mogą spakować tych artefaktów.

Zasoby szkoleniowe

Aby dowiedzieć się więcej na temat specyfikacji szablonu i praktycznych wskazówek, zobacz Publikowanie bibliotek kodu infrastruktury wielokrotnego użytku przy użyciu specyfikacji szablonu.

Wymagane uprawnienia

Istnieją dwie wbudowane role platformy Azure zdefiniowane dla specyfikacji szablonu:

Ponadto potrzebne są również uprawnienia do wdrażania pliku Bicep. Zobacz Wdrażanie — interfejs wiersza polecenia lub wdrażanie — PowerShell.

Dlaczego warto używać specyfikacji szablonu?

Specyfikacje szablonu zapewniają następujące korzyści:

Dla specyfikacji szablonu szablonu są używane standardowe szablony usługi ARM lub pliki Bicep.
Dostęp można zarządzać za pośrednictwem kontroli dostępu opartej na rolach platformy Azure, a nie tokenów SAS.
Użytkownicy mogą wdrażać specyfikację szablonu bez konieczności uzyskiwania dostępu do zapisu w pliku Bicep.
Specyfikację szablonu można zintegrować z istniejącym procesem wdrażania, takim jak skrypt programu PowerShell lub potok DevOps.

Specyfikacje szablonów umożliwiają tworzenie szablonów kanonicznych i udostępnianie ich zespołom w organizacji. Specyfikacje szablonu są bezpieczne, ponieważ są dostępne dla usługi Azure Resource Manager do wdrożenia, ale nie są dostępne dla użytkowników bez odpowiednich uprawnień. Użytkownicy potrzebują tylko dostępu do odczytu do specyfikacji szablonu, aby wdrożyć jego szablon, więc możesz udostępnić szablon bez zezwolenia innym osobom na jego modyfikowanie.

Jeśli obecnie masz szablony w repozytorium GitHub lub koncie magazynu, napotkasz kilka wyzwań podczas próby udostępnienia szablonów i korzystania z nich. Aby wdrożyć szablon, musisz udostępnić szablon publicznie lub zarządzać dostępem za pomocą tokenów SAS. Aby obejść to ograniczenie, użytkownicy mogą tworzyć kopie lokalne, które ostatecznie różnią się od oryginalnego szablonu. Specyfikacje szablonów upraszczają udostępnianie szablonów.

Szablony uwzględnione w specyfikacji szablonu powinny być weryfikowane przez administratorów w organizacji w celu przestrzegania wymagań i wskazówek organizacji.

Tworzenie specyfikacji szablonu

Poniższy przykład przedstawia prosty plik Bicep na potrzeby tworzenia konta magazynu na platformie 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'
}

Utwórz specyfikację szablonu przy użyciu:

Program PowerShell
Interfejs wiersza polecenia

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"

Można również utworzyć specyfikacje szablonu przy użyciu plików Bicep. Jednak zawartość elementu mainTemplate musi znajdować się w formacie JSON. Poniższy szablon tworzy specyfikację szablonu w celu wdrożenia konta magazynu:

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

Szablon JSON osadzony w pliku Bicep musi wprowadzić następujące zmiany:

Usuń przecinki na końcu wierszy.
Zastąp cudzysłowy podwójnymi cudzysłowami pojedynczymi.
Uniknie pojedynczych cudzysłowów w wyrażeniach. Na przykład "name": "[parameters(\'storageAccountType\')]".
Aby uzyskać dostęp do parametrów i zmiennych zdefiniowanych w pliku Bicep, możesz bezpośrednio użyć nazw parametrów i nazw zmiennych. Aby uzyskać dostęp do parametrów i zmiennych zdefiniowanych w programie mainTemplate, nadal musisz użyć składni szablonu JSON usługi ARM. Na przykład "name": "[parameters(\'storageAccountType\')]".
Użyj składni Bicep, aby wywołać funkcje Bicep. Na przykład "location": resourceGroup().location.

Rozmiar specyfikacji szablonu jest ograniczony do przybliżonych 2 MB. Jeśli rozmiar specyfikacji szablonu przekracza limit, otrzymasz kod błędu TemplateSpecTooLarge . Komunikat o błędzie mówi:

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.

Wszystkie specyfikacje szablonów w subskrypcji można wyświetlić przy użyciu:

Program PowerShell
Interfejs wiersza polecenia

Get-AzTemplateSpec

az ts list

Możesz wyświetlić szczegóły specyfikacji szablonu, w tym jego wersje z następującymi wersjami:

Program PowerShell
Interfejs wiersza polecenia

Get-AzTemplateSpec -ResourceGroupName templateSpecsRG -Name storageSpec

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

Wdrażanie specyfikacji szablonu

Po utworzeniu specyfikacji szablonu użytkownicy z rolą Czytelnik specyfikacji szablonu mogą go wdrożyć. Ponadto potrzebne są również uprawnienia do wdrażania szablonu usługi ARM. Zobacz Wdrażanie — interfejs wiersza polecenia lub wdrażanie — PowerShell.

Specyfikacje szablonów można wdrożyć za pośrednictwem portalu, programu PowerShell, interfejsu wiersza polecenia platformy Azure lub modułu Bicep w większym wdrożeniu szablonu. Użytkownicy w organizacji mogą wdrażać specyfikację szablonu w dowolnym zakresie na platformie Azure (grupa zasobów, subskrypcja, grupa zarządzania lub dzierżawa).

Zamiast przekazywać ścieżkę lub identyfikator URI dla pliku Bicep, należy wdrożyć specyfikację szablonu, podając jego identyfikator zasobu. Identyfikator zasobu ma następujący format:

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

Zwróć uwagę, że identyfikator zasobu zawiera nazwę wersji specyfikacji szablonu.

Można na przykład wdrożyć specyfikację szablonu za pomocą następującego polecenia.

Program PowerShell
Interfejs wiersza polecenia

$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

W praktyce zazwyczaj uruchamiasz Get-AzTemplateSpec polecenie lub az ts show uzyskujesz identyfikator specyfikacji szablonu, którą chcesz wdrożyć.

Program PowerShell
Interfejs wiersza polecenia

$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

Możesz również otworzyć adres URL w następującym formacie, aby wdrożyć specyfikację szablonu:

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

Przekazywanie parametrów do specyfikacji szablonu jest podobne do przekazywania parametrów do pliku Bicep. Dodaj wartości parametrów w tekście lub w pliku parametrów.

Parametry wbudowane

Aby przekazać parametr w tekście, użyj:

Program PowerShell
Interfejs wiersza polecenia

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

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

Pliki parametrów

Korzystanie z pliku parametrów Bicep

Aby utworzyć plik parametrów Bicep, należy określić instrukcję using . Oto przykład:
```
using 'using 'ts:<subscription-id>/<resource-group-name>/<template-spec-name>:<tag>'

param StorageAccountType = 'Standard_GRS'
```
Aby uzyskać więcej informacji, zobacz plik parametrów Bicep.

Aby przekazać plik parametrów za pomocą polecenia:
- Program PowerShell
- Interfejs wiersza polecenia
Obecnie nie można wdrożyć specyfikacji szablonu z plikiem bicepparam przy użyciu programu Azure PowerShell.
```
az deployment group create \
  --resource-group demoRG \
  --parameters "./mainTemplate.bicepparam"
```
Ze względu na instrukcję using w pliku bicepparam. Nie trzeba określać parametru --template-spec .

Korzystanie z pliku parametrów JSON

Poniższy kod JSON to przykładowy plik parametrów JSON:

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

Przekaż ten plik parametrów za pomocą polecenia :

Program PowerShell
Interfejs wiersza polecenia

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

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

Wersje

Podczas tworzenia specyfikacji szablonu należy podać dla niego nazwę wersji. Podczas iteracji kodu szablonu możesz zaktualizować istniejącą wersję (w przypadku poprawek) lub opublikować nową wersję. Wersja jest ciągiem tekstowym. Możesz skorzystać z dowolnego systemu przechowywania wersji, w tym semantycznego przechowywania wersji. Użytkownicy specyfikacji szablonu mogą podać nazwę wersji, której chcą użyć podczas wdrażania. Możesz mieć nielimitową liczbę wersji.

Korzystanie z tagów

Tagi ułatwiają logiczne organizowanie zasobów. Tagi można dodawać do specyfikacji szablonu przy użyciu programu Azure PowerShell i interfejsu wiersza polecenia platformy Azure. W poniższym przykładzie pokazano, jak określić tagi podczas tworzenia specyfikacji szablonu:

Program PowerShell
Interfejs wiersza polecenia

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

W następnym przykładzie pokazano, jak zastosować tagi podczas aktualizowania istniejącej specyfikacji szablonu:

Program PowerShell
Interfejs wiersza polecenia

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

Zarówno szablon, jak i jego wersje mogą mieć tagi. Tagi są stosowane lub dziedziczone w zależności od podanych parametrów.

Specyfikacja szablonu	Wersja	Parametr wersji	Parametr tagu	Wartości tagów
Exists	Nie dotyczy	Nieokreślona	Określone	zastosowane do specyfikacji szablonu
Exists	Nowe	Określone	Nieokreślona	dziedziczone ze specyfikacji szablonu do wersji
Nowe	Nowe	Określone	Określone	stosowane do specyfikacji i wersji szablonu
Exists	Nowe	Określone	Określone	zastosowane do wersji
Exists	Exists	Określone	Określone	zastosowane do wersji

Łącze do specyfikacji szablonu

Po utworzeniu specyfikacji szablonu możesz połączyć się ze specyfikacją tego szablonu w module Bicep. Specyfikacja szablonu jest wdrażana podczas wdrażania pliku Bicep zawierającego ten moduł. Aby uzyskać więcej informacji, zobacz Plik w specyfikacji szablonu.

Aby utworzyć aliasy dla specyfikacji szablonu przeznaczonych do łączenia modułów, zobacz Aliasy dla modułów.

Następne kroki