Spesifikasi templat Azure Resource Manager di Bicep

Artikel
10/18/2023

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 bisa menggunakan kontrol akses berbasis peran Azure (Azure RBAC) untuk berbagi spesifikasi templat. Anda dapat menggunakan Azure CLI atau Azure PowerShell untuk membuat spesifikasi templat dengan menyediakan file Bicep. File Bicep tersebut akan diterjemahkan ke dalam template ARM JSON sebelum disimpan. Saat ini, Anda tidak dapat mengimpor file Bicep dari portal Azure untuk membuat sumber daya 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. Templat utama dan templat tertaut harus dalam JSON. 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 lakukan untuk templat atau file Bicep.

Catatan

Untuk menggunakan spesifikasi templat di Bicep dengan Azure PowerShell, Anda harus menginstal versi 6.3.0 atau yang lebih baru. Untuk menggunakannya dengan Azure CLI, gunakan versi 2.27.0 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 mencakup beberapa instans Azure Cosmos DB dengan setiap instans yang berisi database dan kontainernya sendiri. Karena database dan kontainer tidak banyak berubah, Anda ingin membuat satu spesifikasi templat untuk menyertakan instans Cosmo DB serta database dan kontainer yang mendasarinya. Anda kemudian dapat menggunakan pernyataan bersyarat di Bicep bersama dengan loop salinan untuk membuat beberapa contoh sumber daya ini.

Tip

Pemilihan antara spesifikasi registri modul dan spesifikasi templat umumnya masalah preferensi. Ada beberapa hal yang perlu dipertimbangkan saat Anda memilih di antara keduanya:

Registri modul hanya didukung oleh Bicep. Jika Anda belum menggunakan Bicep, gunakan spesifikasi templat.
Konten di registri modul Bicep hanya dapat disebarkan dari file Bicep lain. Spesifikasi templat dapat disebarkan secara langsung dari API, Azure PowerShell, Azure CLI, dan portal Azure. Anda bahkan bisa menggunakan UiFormDefinition untuk menyesuaikan pengalaman penyebaran portal.
Bicep memiliki beberapa kemampuan terbatas untuk menyematkan artefak proyek lainnya (termasuk file template non-Bicep dan non-ARM. Misalnya, skrip PowerShell, skrip CLI, dan biner lainnya) dengan menggunakan fungsi loadTextContent dan loadFileAsBase64. Spesifikasi templat tidak dapat mengemas artefak 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.

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.

Mengapa menggunakan spesifikasi templat?

Spesifikasi templat memberi manfaat berikut:

Gunakan templat ARM standar atau file Bicep untuk spesifikasi templat Anda.
Anda mengelola akses melalui Azure RBAC, bukan token SAS.
Pengguna dapat menerapkan spesifikasi templat tanpa memiliki akses tulis ke file Bicep.
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.

Membuat spesifikasi templat

Contoh berikut menunjukkan file Bicep sederhana untuk membuat akun penyimpanan di Azure.

@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'
}

Buat spesifikasi templat dengan menggunakan:

PowerShell
CLI

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"

Anda juga dapat membuat spesifikasi templat menggunakan file Bicep. Namun konten mainTemplate harus ada dalam JSON. Templat berikut membuat spesifikasi templat untuk menyebarkan akun penyimpanan:

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

Templat JSON yang disematkan dalam file Bicep perlu membuat perubahan berikut:

Hapus koma di akhir baris.
Ganti tanda kutip ganda menjadi tanda kutip tunggal.
Menghindari tanda kutip tunggal dalam ekspresi. Misalnya, 'name': '[parameters(\'storageAccountType\')]'.
Untuk mengakses parameter dan variabel yang didefinisikan dalam file Bicep, Anda dapat langsung menggunakan nama parameter dan nama variabel. Untuk mengakses parameter dan variabel yang ditentukan dalam mainTemplate, Anda masih perlu menggunakan sintaks templat JSON ARM. Misalnya, 'name': '[parameters(\'storageAccountType\')]'.
Gunakan sintaks Bicep untuk memanggil fungsi Bicep. Misalnya, 'location': resourceGroup().location.

Ukuran spesifikasi templat dibatasi kurang lebih hingga 2 MB. Jika ukuran spesifikasi templat melebihi batas, Anda akan memperoleh 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:

PowerShell
CLI

Get-AzTemplateSpec

az ts list

Anda bisa menampilkan detail spesifikasi templat, termasuk versinya dengan:

PowerShell
CLI

Get-AzTemplateSpec -ResourceGroupName templateSpecsRG -Name storageSpec

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

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 disebarkan melalui portal, PowerShell, Azure CLI, atau sebagai modul Bicep 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).

Daripada meneruskan jalur atau URI untuk file Bicep, sebaiknya sebarkan spesifikasi templat dengan memberikan 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.

PowerShell
CLI

$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

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

PowerShell
CLI

$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

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 mirip dengan meneruskan parameter ke file Bicep. Tambahkan nilai parameter sebaris atau dalam file parameter.

Parameter sebaris

Untuk meneruskan parameter sebaris, gunakan:

PowerShell
CLI

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

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

File parameter

Menggunakan file parameter Bicep

Untuk membuat file parameter Bicep, Anda harus menentukan using pernyataan. Berikut adalah contoh:
```
using 'using 'ts:<subscription-id>/<resource-group-name>/<template-spec-name>:<tag>'

param StorageAccountType = 'Standard_GRS'
```
Untuk informasi selengkapnya, lihat File parameter Bicep.

Untuk meneruskan file parameter dengan:
- PowerShell
- CLI
Saat ini, Anda tidak dapat menyebarkan spesifikasi templat dengan file .bicepparam dengan menggunakan Azure PowerShell.
```
az deployment group create \
  --resource-group demoRG \
  --parameters "./mainTemplate.bicepparam"
```
using Karena pernyataan dalam file bicepparam. Anda tidak perlu menentukan --template-spec parameter .

Menggunakan file parameter JSON

JSON berikut adalah contoh file parameter JSON:

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

PowerShell
CLI

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

az deployment group create \
  --resource-group demoRG \
  --template-spec $id \
  --parameters "./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 dapat menambahkan tag ke spesifikasi template dengan menggunakan Azure PowerShell dan Azure CLI. Contoh berikut ini menunjukkan cara menentukan tag saat membuat spesifikasi template:

PowerShell
CLI

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

Contoh berikutnya menunjukkan cara menerapkan tag ketika memperbarui spesifikasi templat yang telah ada:

PowerShell
CLI

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

Template dan versinya dapat memiliki tag. Tag akan diterapkan atau diwariskan tergantung pada parameter yang Anda tentukan.

Spesifikasi template	Versi	Parameter versi	Parameter tag	Nilai tag
Ada	T/A	Tidak ditentukan	Ditentukan	diterapkan pada spesifikasi template
Ada	Baru	Ditentukan	Tidak ditentukan	diwarisi dari spesifikasi template ke versi
Baru	Baru	Ditentukan	Ditentukan	diterapkan ke spesifikasi template dan versi
Ada	Baru	Ditentukan	Ditentukan	diterapkan pada versi
Ada	Ada	Ditentukan	Ditentukan	diterapkan pada versi

Tautan ke spesifikasi templat

Setelah membuat spesifikasi templat, Anda dapat menautkan ke spesifikasi templat tersebut dalam modul Bicep. Spesifikasi templat disebarkan saat Anda menyebarkan file Bicep yang berisi modul tersebut. Untuk informasi selengkapnya, lihat File dalam spesifikasi templat.

Untuk membuat alias untuk spesifikasi templat yang ditujukan untuk penautan modul, lihat Alias untuk modul.