Spesifikasi templat Azure Resource Manager

  • Artikel

Spesifikasi templat adalah jenis sumber daya untuk menyimpan templat Azure Resource Manager (templat ARM) di Azure untuk penyebaran nanti. Jenis sumber daya ini memungkinkan Anda berbagi templat ARM dengan pengguna lain di organisasi Anda. Sama seperti sumber daya Azure lainnya, Anda dapat menggunakan kontrol akses berbasis peran Azure (Azure RBAC) untuk berbagi spesifikasi templat.

Microsoft.Resources/templatSpecs adalah jenis sumber daya untuk spesifikasi templat. Ini terdiri dari templat utama dan sejumlah templat yang ditautkan. Azure menyimpan spesifikasi templat dengan aman dalam grup sumber daya. Penerapan versi dukungan Spesifikasi Templat.

Untuk menyebarkan spesifikasi templat, Anda menggunakan alat Azure standar seperti PowerShell, Azure CLI, portal Microsoft Azure, REST, serta SDK dan klien lain yang didukung. Anda menggunakan perintah yang sama seperti yang Anda gunakan untuk templat.

Catatan

Untuk menggunakan spesifikasi templat dengan Azure PowerShell, Anda harus menginstal versi 5.0.0 atau yang lebih baru. Untuk menggunakannya dengan Azure CLI, gunakan versi 2.14.2 atau yang lebih baru.

Saat merancang penyebaran Anda, selalu pertimbangkan siklus hidup sumber daya dan kelompokkan sumber daya yang berbagi siklus hidup serupa ke dalam satu spesifikasi templat. Misalnya, penyebaran Anda menyertakan beberapa instans Azure Cosmos DB, dengan setiap instans berisi database dan kontainernya sendiri. Mengingat database dan kontainer tidak banyak berubah, Anda ingin membuat satu spesifikasi templat untuk menyertakan instans Cosmos DB dan database dan kontainer yang mendasarnya. Kemudian, Anda dapat menggunakan pernyataan bersyarat dalam template Anda bersama dengan loop salinan untuk membuat beberapa instans sumber daya ini.

Sumber daya pelatihan

Untuk mempelajari selengkapnya tentang spesifikasi template, dan untuk panduan langsung, lihat Menerbitkan pustaka kode infrastruktur yang dapat digunakan kembali dengan menggunakan spesifikasi template.

Tip

Kami merekomendasikan Bicep karena menawarkan kemampuan yang sama dengan templat ARM dan sintaksnya lebih mudah digunakan. Untuk mempelajari selengkapnya, lihat Spesifikasi templat Azure Resource Manager di Bicep.

Mengapa menggunakan spesifikasi templat?

Spesifikasi templat memberi manfaat berikut:

  • Anda menggunakan templat ARM standar untuk spesifikasi templat Anda.
  • Anda mengelola akses melalui Azure RBAC, bukan token SAS.
  • Pengguna dapat menggunakan spesifikasi templat tanpa memiliki akses tulis ke templat.
  • Anda dapat mengintegrasikan spesifikasi templat ke dalam proses penyebaran yang ada, seperti skrip PowerShell atau alur Azure DevOps.

Spesifikasi templat memungkinkan Anda membuat templat kanonis dan membagikannya dengan tim di organisasi Anda. Spesifikasi templat aman karena tersedia untuk Azure Resource Manager untuk penyebaran, tetapi tidak dapat diakses oleh pengguna tanpa izin yang benar. Pengguna hanya membutuhkan akses baca ke spesifikasi templat untuk menyebarkan templatnya, sehingga Anda dapat berbagi templat tanpa mengizinkan orang lain mengubahnya.

Jika saat ini Anda memiliki templat di repositori GitHub atau akun penyimpanan, Anda mengalami beberapa tantangan ketika mencoba untuk berbagi dan menggunakan templat. Untuk menyebarkan templat, Anda harus membuat templat dapat diakses secara publik atau mengelola akses dengan token SAS. Untuk mengatasi batasan ini, pengguna mungkin membuat salinan lokal, yang akhirnya berbeda dari templat asli Anda. Spesifikasi templat menyederhanakan berbagi templat.

Templat yang Anda sertakan dalam spesifikasi templat harus diverifikasi oleh administrator di organisasi Anda untuk mengikuti persyaratan dan panduan organisasi.

Memerlukan izin

Ada dua peran build-in Azure yang ditentukan untuk spesifikasi templat:

Selain itu, Anda juga memerlukan izin untuk menyebarkan file Bicep. Lihat Menyebarkan - CLI atau Menyebarkan - PowerShell.

Membuat spesifikasi templat

Contoh berikut menunjukkan templat sederhana untuk membuat akun penyimpanan di 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')]"
      }
    }
  ]
}

Saat Anda membuat spesifikasi templat, perintah PowerShell atau CLI akan diteruskan ke file templat utama. Jika templat utama mereferensikan templat yang ditautkan, perintah akan menemukan dan mengemasnya untuk membuat spesifikasi templat. Untuk mempelajari selengkapnya, lihat Membuat spesifikasi templat dengan templat yang ditautkan.

Buat spesifikasi templat dengan menggunakan:

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

Anda juga dapat membuat spesifikasi templat dengan menggunakan templat ARM. Templat berikut membuat spesifikasi templat untuk menyebarkan akun penyimpanan:

{
  "$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')]"
              }
            }
          ]
        }
      }
    }
  ]
}

Ukuran spesifikasi templat dibatasi kurang lebih hingga 2 MB. Jika ukuran spesifikasi templat melebihi batas, Anda akan mendapatkan kode kesalahan TemplateSpecTooLarge. Pesan kesalahan mengatakan:

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.

Anda bisa menampilkan semua spesifikasi templat di langganan Anda dengan menggunakan:

Get-AzTemplateSpec

Anda bisa menampilkan detail spesifikasi templat, termasuk versinya dengan:

Get-AzTemplateSpec -ResourceGroupName templateSpecsRG -Name storageSpec

Menyebarkan spesifikasi templat

Setelah Anda membuat spesifikasi templat, pengguna dengan peran pembaca spesifikasi templat dapat menyebarkannya. Selain itu, Anda juga memerlukan izin untuk menyebarkan templat ARM. Lihat Menyebarkan - CLI atau Menyebarkan - PowerShell.

Spesifikasi templat dapat digunakan melalui portal, PowerShell, Azure CLI, atau sebagai templat tertaut dalam penyebaran templat yang lebih besar. Pengguna dalam organisasi bisa menyebarkan spesifikasi templat ke cakupan apa pun di Azure (grup sumber daya, langganan, grup manajemen, atau penyewa).

Sebagai ganti melewati jalur atau URI untuk templat, Anda menyebarkan spesifikasi templat dengan menyediakan ID sumber dayanya. ID sumber daya memiliki format berikut:

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

Perhatikan bahwa ID sumber daya menyertakan nama versi untuk spesifikasi templat.

Misalnya, Anda menyebarkan spesifikasi templat dengan perintah berikut.

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

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

Dalam praktiknya, Anda biasanya akan menjalankan Get-AzTemplateSpec atau az ts show untuk mendapatkan ID spesifikasi templat yang ingin Anda sebarkan.

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

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

Anda juga bisa membuka URL dalam format berikut untuk menyebarkan spesifikasi templat:

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

Meneruskan parameter ke spesifikasi templat persis seperti meneruskan parameter ke templat ARM. Tambahkan nilai parameter sebaris atau dalam file parameter.

Untuk meneruskan parameter sebaris, gunakan:

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

Untuk membuat file parameter lokal, gunakan:

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

Dan, teruskan file parameter itu dengan:

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

Penerapan versi

Saat Anda membuat spesifikasi templat, Anda menyediakan nama versi untuk templat tersebut. Saat Anda melakukan iterasi pada kode templat, Anda dapat memperbarui versi yang ada (untuk perbaikan) atau menerbitkan versi baru. Versinya adalah string teks. Anda dapat memilih untuk mengikuti sistem penerapan versi apa pun, termasuk penerapan versi semantik. Pengguna spesifikasi templat dapat memberikan nama versi yang ingin mereka gunakan saat menyebarkannya. Anda dapat memiliki jumlah versi yang tidak dibatasi.

Menggunakan tag

Tag membantu Anda menata sumber daya secara logis. Anda bisa menambahkan tag ke spesifikasi templat dengan menggunakan Azure PowerShell dan Azure CLI:

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"}

Saat membuat atau memodifikasi spesifikasi templat dengan parameter versi yang ditentukan, tetapi tanpa parameter tag/ beberapa tag:

  • Jika spesifikasi templat ada dan memiliki tag, tetapi versi tidak ada, versi baru mewarisi tag yang sama dengan spesifikasi templat yang ada.

Saat membuat atau mengubah spesifikasi templat dengan parameter tag/beberapa tag dan parameter versi yang ditentukan:

  • Jika spesifikasi templat dan versi tidak ada, tag ditambahkan ke spesifikasi templat baru dan versi baru.
  • Jika spesifikasi templat ada, tetapi versi tidak ada, tag hanya ditambahkan ke versi baru.
  • Jika spesifikasi templat dan versi ada, tag hanya berlaku untuk versi.

Saat mengubah templat dengan parameter tag/ beberapa tag yang ditentukan tetapi tanpa parameter versi yang ditentukan, tag hanya ditambahkan ke spesifikasi templat.

Membuat spesifikasi templat dengan templat yang ditautkan

Jika templat utama untuk spesifikasi templat Anda mereferensikan templat yang ditautkan, perintah PowerShell dan CLI dapat secara otomatis mencari dan mengemas templat terkait dari drive lokal Anda. Anda tidak perlu mengonfigurasi akun penyimpanan atau repositori secara manual untuk menghosting spesifikasi templat - semuanya mandiri dalam sumber daya spesifikasi templat.

Contoh berikut terdiri dari templat utama dengan dua templat yang ditautkan. Contoh tersebut hanyalah cuplikan dari templat. Perhatikan bahwa templat menggunakan properti bernama relativePath untuk menautkan ke templat lain. Anda harus menggunakan apiVersion dari 2020-06-01 atau yang lebih baru untuk sumber daya penyebaran.

{
  "$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": {}
}

Saat perintah PowerShell atau CLI untuk membuat spesifikasi templat dijalankan untuk contoh sebelumnya, perintah tersebut menemukan tiga file - templat utama, templat aplikasi web (webapp.json), dan templat database (database.json) - dan mengemas file tersebut ke dalam spesifikasi templat.

Untuk informasi selengkapnya, lihat Tutorial: Membuat spesifikasi templat dengan templat yang ditautkan.

Menyebarkan spesifikasi templat sebagai templat yang ditautkan

Setelah Anda membuat spesifikasi templat, mudah untuk menggunakannya kembali dari templat ARM atau spesifikasi templat lain. Anda menautkan ke spesifikasi templat dengan menambahkan ID sumber dayanya ke templat Anda. Spesifikasi templat yang ditautkan secara otomatis disebarkan saat Anda menggunakan templat utama. Perilaku ini memungkinkan Anda mengembangkan spesifikasi templat modular, dan menggunakannya kembali sesuai kebutuhan.

Misalnya, Anda dapat membuat spesifikasi templat yang menggunakan sumber daya jaringan, dan spesifikasi templat lain yang menggunakan sumber daya penyimpanan. Dalam templat ARM, Anda menautkan ke dua spesifikasi templat ini kapan saja Anda perlu mengonfigurasi sumber daya jaringan atau penyimpanan.

Contoh berikut ini mirip dengan contoh sebelumnya, tetapi Anda menggunakan properti id untuk menautkan ke spesifikasi templat daripada properti relativePath untuk ditautkan ke templat lokal. Gunakan 2020-06-01 untuk versi API untuk sumber daya penyebaran. Dalam contoh, spesifikasi templat berada dalam grup sumber daya bernama 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": {}
}

Untuk informasi selengkapnya tentang menautkan spesifikasi templat, lihat Tutorial: Menyebarkan spesifikasi templat sebagai templat yang ditautkan.

Langkah berikutnya