Specyfikacje szablonu usługi Azure Resource Manager
Specyfikacja szablonu to typ zasobu do przechowywania szablonu usługi Azure Resource Manager (szablonu arm) na platformie Azure 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.
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. 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.
Uwaga
Aby użyć specyfikacji szablonu w programie Azure PowerShell, musisz zainstalować wersję 5.0.0 lub nowszą. Aby używać go z interfejsem wiersza polecenia platformy Azure, użyj wersji 2.14.2 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 usługi Cosmos DB i jego bazowe bazy danych i kontenery. Następnie możesz użyć instrukcji warunkowych w szablonach wraz z pętlami kopiowania, aby utworzyć wiele wystąpień tych zasobó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.
Napiwek
Zalecamy Bicep , ponieważ oferuje te same możliwości co szablony usługi ARM, a składnia jest łatwiejsza w użyciu. Aby dowiedzieć się więcej, zobacz Specyfikacje szablonu usługi Azure Resource Manager w aplikacji Bicep.
Dlaczego warto używać specyfikacji szablonu?
Specyfikacje szablonu zapewniają następujące korzyści:
- Używasz standardowych szablonów usługi ARM dla specyfikacji szablonu.
- 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 szablonie.
- 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.
Wymagane uprawnienia
Istnieją dwie role kompilacji 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.
Tworzenie specyfikacji szablonu
Poniższy przykład przedstawia prosty szablon tworzenia konta magazynu na platformie Azure.
{
"$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": "[concat('store', uniquestring(resourceGroup().id))]",
"location": "[resourceGroup().location]",
"kind": "StorageV2",
"sku": {
"name": "[parameters('storageAccountType')]"
}
}
]
}
Podczas tworzenia specyfikacji szablonu polecenia programu PowerShell lub interfejsu wiersza polecenia są przekazywane główny plik szablonu. Jeśli główny szablon odwołuje się do połączonych szablonów, polecenia znajdą i spakują je w celu utworzenia specyfikacji szablonu. Aby dowiedzieć się więcej, zobacz Tworzenie specyfikacji szablonu za pomocą połączonych szablonów.
Utwórz specyfikację szablonu przy użyciu:
New-AzTemplateSpec -Name storageSpec -Version 1.0a -ResourceGroupName templateSpecsRg -Location westus2 -TemplateFile ./mainTemplate.json
Można również utworzyć specyfikacje szablonu przy użyciu szablonów usługi ARM. Poniższy szablon tworzy specyfikację szablonu w celu wdrożenia konta magazynu:
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"templateSpecName": {
"type": "string",
"defaultValue": "CreateStorageAccount"
},
"templateSpecVersionName": {
"type": "string",
"defaultValue": "0.1"
},
"location": {
"type": "string",
"defaultValue": "[resourceGroup().location]"
}
},
"resources": [
{
"type": "Microsoft.Resources/templateSpecs",
"apiVersion": "2021-05-01",
"name": "[parameters('templateSpecName')]",
"location": "[parameters('location')]",
"properties": {
"description": "A basic templateSpec - creates a storage account.",
"displayName": "Storage account (Standard_LRS)"
}
},
{
"type": "Microsoft.Resources/templateSpecs/versions",
"apiVersion": "2021-05-01",
"name": "[format('{0}/{1}', parameters('templateSpecName'), parameters('templateSpecVersionName'))]",
"location": "[parameters('location')]",
"dependsOn": [
"[resourceId('Microsoft.Resources/templateSpecs', parameters('templateSpecName'))]"
],
"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": "[concat('store', uniquestring(resourceGroup().id))]",
"location": "[resourceGroup().location]",
"kind": "StorageV2",
"sku": {
"name": "[parameters('storageAccountType')]"
}
}
]
}
}
}
]
}
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:
Get-AzTemplateSpec
Możesz wyświetlić szczegóły specyfikacji szablonu, w tym jego wersje z następującymi wersjami:
Get-AzTemplateSpec -ResourceGroupName templateSpecsRG -Name storageSpec
Wdrażanie specyfikacji szablonu
Po utworzeniu specyfikacji szablonu użytkownicy z rolą czytelnika specyfikacji szablonu mogą ją 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 jako połączonego szablonu 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 szablonu, 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.
$id = "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/templateSpecsRG/providers/Microsoft.Resources/templateSpecs/storageSpec/versions/1.0a"
New-AzResourceGroupDeployment `
-TemplateSpecId $id `
-ResourceGroupName demoRG
W praktyce zazwyczaj uruchamiasz Get-AzTemplateSpec polecenie lub az ts show uzyskujesz identyfikator specyfikacji szablonu, którą chcesz wdrożyć.
$id = (Get-AzTemplateSpec -Name storageSpec -ResourceGroupName templateSpecsRg -Version 1.0a).Versions.Id
New-AzResourceGroupDeployment `
-ResourceGroupName demoRG `
-TemplateSpecId $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 dokładnie takie jak przekazywanie parametrów do szablonu usługi ARM. Dodaj wartości parametrów w tekście lub w pliku parametrów.
Aby przekazać parametr w tekście, użyj:
New-AzResourceGroupDeployment `
-TemplateSpecId $id `
-ResourceGroupName demoRG `
-StorageAccountType Standard_GRS
Aby utworzyć plik parametrów lokalnych, użyj:
{
"$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 :
New-AzResourceGroupDeployment `
-TemplateSpecId $id `
-ResourceGroupName demoRG `
-TemplateParameterFile ./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:
New-AzTemplateSpec `
-Name storageSpec `
-Version 1.0a `
-ResourceGroupName templateSpecsRg `
-Location westus2 `
-TemplateFile ./mainTemplate.json `
-Tag @{Dept="Finance";Environment="Production"}
Set-AzTemplateSpec `
-Name storageSpec `
-Version 1.0a `
-ResourceGroupName templateSpecsRg `
-Location westus2 `
-TemplateFile ./mainTemplate.json `
-Tag @{Dept="Finance";Environment="Production"}
Podczas tworzenia lub modyfikowania specyfikacji szablonu z określonym parametrem wersji, ale bez parametru tagu/tagów:
- Jeśli specyfikacja szablonu istnieje i zawiera tagi, ale wersja nie istnieje, nowa wersja dziedziczy te same tagi co istniejąca specyfikacja szablonu.
Podczas tworzenia lub modyfikowania specyfikacji szablonu za pomocą parametru tag/tags i parametru wersji określono:
- Jeśli zarówno specyfikacja szablonu, jak i wersja nie istnieją, tagi są dodawane zarówno do nowej specyfikacji szablonu, jak i nowej wersji.
- Jeśli specyfikacja szablonu istnieje, ale wersja nie istnieje, tagi są dodawane tylko do nowej wersji.
- Jeśli istnieją zarówno specyfikacje szablonu, jak i wersja, tagi dotyczą tylko wersji.
Podczas modyfikowania szablonu przy użyciu określonego parametru tagu/tagów, ale bez określonego parametru wersji tagi są dodawane tylko do specyfikacji szablonu.
Tworzenie specyfikacji szablonu z połączonymi szablonami
Jeśli główny szablon specyfikacji szablonu odwołuje się do połączonych szablonów, polecenia programu PowerShell i interfejsu wiersza polecenia mogą automatycznie znajdować i pakować połączone szablony z dysku lokalnego. Nie musisz ręcznie konfigurować kont magazynu ani repozytoriów w celu hostowania specyfikacji szablonu — wszystko jest samodzielnie zawarte w zasobie specyfikacji szablonu.
Poniższy przykład składa się z głównego szablonu z dwoma połączonymi szablonami. Przykład jest tylko fragmentem szablonu. Zwróć uwagę, że używa właściwości o nazwie relativePath , aby połączyć się z innymi szablonami. Musisz użyć apiVersion lub nowszego 2020-06-01 zasobu wdrożeń.
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
...
"resources": [
{
"type": "Microsoft.Resources/deployments",
"apiVersion": "2020-06-01",
...
"properties": {
"mode": "Incremental",
"templateLink": {
"relativePath": "artifacts/webapp.json"
}
}
},
{
"type": "Microsoft.Resources/deployments",
"apiVersion": "2020-06-01",
...
"properties": {
"mode": "Incremental",
"templateLink": {
"relativePath": "artifacts/database.json"
}
}
}
],
"outputs": {}
}
Gdy polecenie programu PowerShell lub interfejsu wiersza polecenia służące do utworzenia specyfikacji szablonu jest wykonywane w poprzednim przykładzie, polecenie znajduje trzy pliki — główny szablon, szablon aplikacji internetowej (webapp.json) i szablon bazy danych (database.json) — i pakuje je do specyfikacji szablonu.
Aby uzyskać więcej informacji, zobacz Samouczek: tworzenie specyfikacji szablonu z połączonymi szablonami.
Wdrażanie specyfikacji szablonu jako szablonu połączonego
Po utworzeniu specyfikacji szablonu można łatwo użyć jej z szablonu usługi ARM lub innej specyfikacji szablonu. Możesz utworzyć link do specyfikacji szablonu, dodając jego identyfikator zasobu do szablonu. Specyfikacja połączonego szablonu jest wdrażana automatycznie podczas wdrażania głównego szablonu. To zachowanie umożliwia opracowanie specyfikacji szablonu modułowego i ponowne użycie ich w razie potrzeby.
Można na przykład utworzyć specyfikację szablonu, która wdraża zasoby sieciowe, oraz inną specyfikację szablonu, która wdraża zasoby magazynu. W szablonach usługi ARM połączysz się z tymi dwoma specyfikacjami szablonów w dowolnym momencie, aby skonfigurować zasoby sieciowe lub magazynowe.
Poniższy przykład jest podobny do poprzedniego przykładu, ale użyjesz id właściwości , aby połączyć się ze specyfikacją szablonu, a nie relativePath z właściwością, aby połączyć się z szablonem lokalnym. Użyj dla 2020-06-01 wersji interfejsu API dla zasobu wdrożeń. W tym przykładzie specyfikacje szablonu znajdują się w grupie zasobów o nazwie templateSpecsRG.
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
...
"resources": [
{
"type": "Microsoft.Resources/deployments",
"apiVersion": "2020-06-01",
"name": "networkingDeployment",
...
"properties": {
"mode": "Incremental",
"templateLink": {
"id": "[resourceId('templateSpecsRG', 'Microsoft.Resources/templateSpecs/versions', 'networkingSpec', '1.0a')]"
}
}
},
{
"type": "Microsoft.Resources/deployments",
"apiVersion": "2020-06-01",
"name": "storageDeployment",
...
"properties": {
"mode": "Incremental",
"templateLink": {
"id": "[resourceId('templateSpecsRG', 'Microsoft.Resources/templateSpecs/versions', 'storageSpec', '1.0a')]"
}
}
}
],
"outputs": {}
}
Aby uzyskać więcej informacji na temat łączenia specyfikacji szablonu, zobacz Samouczek: wdrażanie specyfikacji szablonu jako szablonu połączonego.
Następne kroki
Aby utworzyć i wdrożyć specyfikację szablonu, zobacz Szybki start: tworzenie i wdrażanie specyfikacji szablonu.
Aby uzyskać więcej informacji na temat łączenia szablonów w specyfikacji szablonu, zobacz Samouczek: tworzenie specyfikacji szablonu z połączonymi szablonami.
Aby uzyskać więcej informacji na temat wdrażania specyfikacji szablonu jako szablonu połączonego, zobacz Samouczek: wdrażanie specyfikacji szablonu jako szablonu połączonego.