Cara menggunakan templat penyebaran Azure Resource Manager (ARM) dengan Azure CLI

Artikel ini menjelaskan cara menggunakan Azure CLI dengan templat Azure Resource Manager (templat ARM) untuk menyebarkan sumber daya Anda ke Azure. Jika Anda tidak terbiasa dengan konsep penyebaran dan pengelolaan solusi Azure Anda, lihat gambaran umum penyebaran template.

Perintah penyebaran berubah dalam Azure CLI versi 2.2.0. Contoh dalam artikel ini memerlukan Azure CLI versi 2.20.0 atau yang lebih baru.

Untuk menjalankan sampel ini, instal versi terbaru Azure CLI. Untuk memulai, jalankan az login untuk membuat koneksi dengan Azure.

Sampel untuk Azure CLI ditulis untuk shell bash. Untuk menjalankan sampel ini di Windows PowerShell atau Prompt Perintah, Anda mungkin perlu mengubah elemen skrip.

Jika Anda belum menginstal Azure CLI, Anda dapat menggunakan Azure Cloud Shell. Untuk informasi selengkapnya, lihat Deploy ARM templates dari Azure Cloud Shell.

Tips

Sebaiknya Bicep karena menawarkan kemampuan yang sama dengan templat ARM dan sintaks lebih mudah digunakan. Untuk mempelajari selengkapnya, lihat Cara menyebarkan sumber daya dengan Bicep dan Azure CLI.

Prasyarat

Izin yang diperlukan

Untuk menyebarkan file Bicep atau templat Azure Resource Manager (ARM), Anda memerlukan akses tulis pada sumber daya yang Anda sebarkan dan akses ke semua operasi pada jenis sumber daya Microsoft.Resources/deployments. Misalnya, untuk menyebarkan komputer virtual, Anda memerlukan izin Microsoft.Compute/virtualMachines/write dan Microsoft.Resources/deployments/*. Operasi hipotetis memiliki persyaratan izin yang sama.

Azure CLI versi 2.76.0 atau yang lebih baru dan versi Azure PowerShell 13.4.0 atau yang lebih baru memperkenalkan switch ValidationLevel untuk menentukan seberapa lengkap ARM memvalidasi templat Bicep selama proses ini. Untuk informasi selengkapnya, lihat Perintah bagaimana-jika

Untuk daftar peran dan izin, lihat peran bawaan Azure.

Cakupan penyebaran

Anda dapat menargetkan templat penyebaran Azure ke grup sumber daya, langganan, grup manajemen, atau penyewa. Tergantung pada lingkup penyebaran, Anda menggunakan perintah yang berbeda.

Untuk setiap cakupan, pengguna yang menyebarkan templat harus memiliki izin yang diperlukan untuk membuat sumber daya.

Menyebarkan templat lokal

Anda dapat menyebarkan templat ARM dari mesin lokal Anda atau templat yang disimpan secara eksternal. Bagian ini mendeskripsikan cara menyebarkan templat lokal.

Jika Anda menyebarkan ke grup sumber daya yang tidak ada, buatlah grup sumber daya. Nama grup sumber daya hanya dapat mencakup karakter alfanumerik, titik, garis bawah, tanda hubung, dan tanda kurung. Panjangnya bisa sampai 90 karakter. Nama tidak boleh diakhiri dengan titik.

az group create --name ExampleGroup --location "Central US"

Untuk menggunakan templat lokal, gunakan parameter --template-file dalam perintah penyebaran. Contoh berikut juga memperlihatkan cara mengatur nilai parameter.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file <path-to-template> \
  --parameters storageAccountType=Standard_GRS

Nilai parameter --template-file harus berupa file Bicep atau file .json atau .jsonc. Ekstensi file .jsonc menunjukkan bahwa file dapat berisi // komentar gaya. Sistem ARM menerima // komentar dalam file .json. Itu tidak peduli dengan ekstensi file. Untuk detail selengkapnya tentang komentar dan metadata, lihat Memahami struktur dan sintaksis templat ARM.

Templat penyebaran Azure dapat memakan waktu beberapa menit untuk diselesaikan. Setelah selesai, Anda akan melihat pesan yang menyertakan hasilnya:

"provisioningState": "Succeeded",

Menyebarkan templat jarak jauh

Alih-alih menyimpan templat ARM di komputer lokal, Anda mungkin lebih suka menyimpannya di lokasi eksternal. Anda dapat menyimpan templat di repositori kontrol sumber (seperti GitHub). Atau, Anda dapat menyimpannya di akun penyimpanan Azure untuk akses bersama di organisasi Anda.

Catatan

Untuk menyebarkan templat atau mereferensikan templat tertaut yang disimpan dalam repositori GitHub privat, lihat solusi kustom yang didokumentasikan di Buat Penawaran portal Azure Kustom dan Aman. Anda dapat membuat fungsi Azure yang menarik token GitHub keluar dari Azure Key Vault.

Jika Anda menyebarkan ke grup sumber daya yang tidak ada, buatlah grup sumber daya. Nama grup sumber daya hanya dapat mencakup karakter alfanumerik, titik, garis bawah, tanda hubung, dan tanda kurung. Panjangnya bisa sampai 90 karakter. Nama tidak boleh diakhiri dengan titik.

az group create --name ExampleGroup --location "Central US"

Untuk menyebarkan templat eksternal, gunakan template-uri parameter.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-uri "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.storage/storage-account-create/azuredeploy.json" \
  --parameters storageAccountType=Standard_GRS

Contoh sebelumnya memerlukan URI yang dapat diakses publik untuk templat, yang berfungsi untuk sebagian besar skenario karena templat Anda tidak boleh menyertakan data sensitif. Jika Anda perlu menentukan data sensitif (seperti kata sandi admin), berikan nilai tersebut sebagai parameter aman. Namun, jika Anda ingin mengelola akses ke templat, pertimbangkan untuk menggunakan spesifikasi templat.

Untuk menyebarkan templat tertaut jarak jauh dengan jalur relatif yang disimpan di akun penyimpanan, gunakan query-string untuk menentukan token SAS:

az deployment group create \
  --name linkedTemplateWithRelativePath \
  --resource-group myResourceGroup \
  --template-uri "https://stage20210126.blob.core.windows.net/template-staging/mainTemplate.json" \
  --query-string $sasToken

Untuk informasi lebih lanjut, lihat Menggunakan jalur relatif untuk templat tertaut.

Nama templat penyebaran Azure

Saat menyebarkan templat ARM, Anda dapat memberikan nama pada templat penyebaran Azure. Nama ini dapat membantu Anda mendapatkan kembali penyebaran dari riwayat penyebaran. Jika Anda tidak memberikan nama untuk penyebaran, nama file templat akan digunakan. Misalnya, jika Anda menyebarkan templat bernama azuredeploy.json dan tidak menentukan nama penyebaran, penyebaran tersebut akan diberi nama azuredeploy.

Setiap kali Anda menjalankan penyebaran, sebuah entri ditambahkan ke riwayat penyebaran grup sumber daya dengan menggunakan nama penyebaran. Jika Anda menjalankan penggelaran lainnya dan memberinya nama yang sama, entri sebelumnya akan digantikan oleh penggelaran saat ini. Jika Anda ingin mempertahankan entri unik dalam riwayat penyebaran, berikan nama yang unik pada setiap penyebaran.

Untuk membuat nama yang unik, Anda dapat menetapkan angka acak.

deploymentName='ExampleDeployment'$RANDOM

Atau, tambahkan nilai tanggal.

deploymentName='ExampleDeployment'$(date +"%d-%b-%Y")

Jika Anda menjalankan penyebaran bersamaan ke grup sumber daya yang sama dengan nama penyebaran yang sama, hanya penyebaran terakhir yang diselesaikan. Setiap penyebaran dengan nama yang sama yang belum selesai akan digantikan oleh penyebaran terakhir. Misalnya, jika Anda menjalankan penyebaran bernama newStorage yang menyebarkan akun penyimpanan bernama storage1, dan pada saat yang sama menjalankan penyebaran lain bernama newStorage yang menyebarkan akun penyimpanan bernama storage2, Anda hanya menyebarkan satu akun penyimpanan. Akun penyimpanan yang dihasilkan diberi nama storage2.

Namun, jika Anda menjalankan penyebaran bernama newStorage yang menyebarkan akun penyimpanan bernama storage1, dan segera setelah selesai Anda menjalankan penyebaran lain bernama newStorage yang menyebarkan akun penyimpanan bernama storage2, Anda memiliki dua akun penyimpanan. Satu bernama storage1, dan yang lain bernama storage2. Tetapi, Anda hanya memiliki satu entri dalam riwayat penyebaran.

Saat menentukan nama unik untuk setiap penyebaran, Anda dapat menjalankannya secara bersamaan tanpa konflik. Jika Anda menjalankan penyebaran bernama newStorage1 yang menyebarkan akun penyimpanan bernama storage1, dan pada saat yang sama menjalankan penyebaran lain bernama newStorage2 yang menyebarkan akun penyimpanan bernama storage2, Anda memiliki dua akun penyimpanan dan dua entri di riwayat penyebaran.

Untuk menghindari konflik dengan penyebaran bersamaan dan memastikan entri unik dalam riwayat penyebaran, berikan nama yang unik pada setiap penyebaran.

Menyebarkan spesifikasi templat

Alih-alih menyebarkan templat lokal atau jarak jauh, Anda dapat membuat spesifikasi template. Spesifikasi templat adalah sumber daya dalam langganan Azure Anda yang berisi templat ARM. Sumber daya ini memudahkan Anda berbagi templat dengan pengguna di organisasi Anda secara aman. Anda menggunakan kontrol akses berbasis peran Azure (Azure RBAC) untuk memberikan akses ke spesifikasi templat. Fitur ini saat ini dalam pratinjau.

Contoh berikut menunjukkan cara membuat dan menyebarkan spesifikasi templat.

Pertama, buat spesifikasi templat dengan menyediakan templat ARM.

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

Kemudian, dapatkan ID untuk template spesifikasi dan terapkan.

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

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

Untuk informasi selengkapnya, lihat spesifikasi templat Azure Resource Manager.

Pratinjau perubahan

Sebelum menyebarkan templat ARM, Anda dapat mempratinjau perubahan yang dilakukan templat ke lingkungan Anda. Gunakan operasi what-if untuk memverifikasi bahwa templat membuat perubahan yang Anda harapkan. What-if juga memvalidasi template untuk kesalahan.

Parameter

Untuk meneruskan nilai parameter, Anda dapat menggunakan parameter inline atau file parameter. File parameter dapat berupa file parameter Bicep atau file parameter JSON.

Parameter sebaris

Untuk meneruskan parameter sebaris, berikan nilai dalam parameters. Misalnya, untuk meneruskan string dan array ke templat di shell Bash, gunakan:

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-template> \
  --parameters exampleString='inline string' exampleArray='("value1", "value2")'

Jika Anda menggunakan Azure CLI dengan Windows Command Prompt (CMD) atau PowerShell, teruskan array dalam format: exampleArray="['value1','value2']".

Anda juga bisa mendapatkan konten file dan menyediakan konten tersebut sebagai parameter sebaris.

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-template> \
  --parameters exampleString=@stringContent.txt exampleArray=@arrayContent.json

Mendapatkan nilai parameter dari file sangat berguna ketika Anda perlu memberikan nilai konfigurasi. Misalnya, Anda dapat memberikan nilai cloud-init untuk mesin virtual Linux.

Format arrayContent.json adalah:

[
  "value1",
  "value2"
]

Untuk meneruskan objek, misalnya untuk mengatur tag, gunakan JSON. Misalnya, templat Anda mungkin menyertakan parameter seperti ini:

"resourceTags": {
  "type": "object",
  "defaultValue": {
    "Cost Center": "IT Department"
  }
}

Dalam hal ini, Anda dapat meneruskan untai JSON untuk mengatur parameter seperti yang ditunjukkan dalam skrip Bash berikut:

tags='{"Owner":"Contoso","Cost Center":"2345-324"}'
az deployment group create --name addstorage  --resource-group myResourceGroup \
--template-file $templateFile \
--parameters resourceName=abcdef4556 resourceTags="$tags"

Gunakan tanda kutip ganda di sekitar JSON yang ingin Anda masukkan ke dalam objek.

Anda dapat menggunakan variabel untuk berisi nilai parameter. Di Bash, atur variabel ke semua nilai parameter dan tambahkan ke perintah penyebaran.

params="prefix=start suffix=end"

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-template> \
  --parameters $params

Namun, jika Anda menggunakan Azure CLI dengan Windows Command Prompt (CMD) atau PowerShell, atur variabel ke string JSON. Hindari tanda kutip: $params = '{ \"prefix\": {\"value\":\"start\"}, \"suffix\": {\"value\":\"end\"} }'.

File parameter JSON

Daripada meneruskan parameter sebagai nilai sebaris dalam skrip Anda, akan lebih mudah untuk menggunakan file parameter, baik file .bicepparam atau file parameter JSON, yang berisi nilai parameter. File parameter harus berupa file lokal. File parameter eksternal tidak didukung dengan Azure CLI.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file storage.json \
  --parameters 'storage.parameters.json'

Untuk informasi selengkapnya tentang file parameter, lihat Buat file parameter Resource Manager.

Bicep file parameter

Dengan Azure CLI versi 2.53.0 atau yang lebih baru, dan Bicep CLI versi 0.22.6 atau yang lebih baru, Anda dapat menyebarkan file Bicep dengan menggunakan file parameter Bicep. Dengan pernyataan using dalam file parameter Bicep, tidak perlu menyediakan sakelar --template-file saat menentukan file parameter Bicep untuk sakelar --parameters. Menyertakan pengalih --template-file menghasilkan kesalahan, "Hanya file .bicep yang diizinkan dengan file .bicepparam."

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --parameters storage.bicepparam

File parameter harus berupa file lokal. File parameter eksternal tidak didukung dengan Azure CLI. Untuk informasi selengkapnya tentang file parameter, lihat panduan Membuat File Parameter Resource Manager.

Komentar dan format JSON yang diperluas

Anda dapat menyertakan // komentar gaya dalam file parameter, tetapi Anda harus memberi nama file dengan ekstensi .jsonc.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file storage.json \
  --parameters '@storage.parameters.jsonc'

Untuk detail selengkapnya tentang komentar dan metadata, lihat Memahami struktur dan sintaks templat ARM.

Jika Anda menggunakan Azure CLI dengan versi 2.3.0 atau yang lebih lama, Anda dapat menyebarkan templat dengan string multibaris atau komentar menggunakan sakelar --handle-extended-json-format. Contohnya:

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2025-04-01",
  "name": "[variables('vmName')]", // to customize name, change it in variables
  "location": "[
    parameters('location')
    ]", //defaults to resource group location
  /*
    storage account and network interface
    must be deployed first
  */
  "dependsOn": [
    "[resourceId('Microsoft.Storage/storageAccounts/', variables('storageAccountName'))]",
    "[resourceId('Microsoft.Network/networkInterfaces/', variables('nicName'))]"
  ],

Langkah berikutnya

  • Last updated on