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

  • Artikel

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

Perintah penyebaran berubah di 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 guna membuat koneksi dengan Azure.

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

Jika Anda tidak memiliki Azure CLI yang terinstal, Anda dapat menggunakan Azure Cloud Shell. Untuk informasi selengkapnya, lihat Menyebarkan templat ARM dari Azure Cloud Shell.

Tip

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

Memerlukan izin

Untuk menyebarkan file Bicep atau templat ARM, Anda memerlukan akses tulis pada sumber daya yang Anda sebarkan dan mengakses ke semua operasi di Microsoft.Resources/deployments resource type. Misalnya, untuk menyebarkan mesin virtual, Anda memerlukan izin Microsoft.Compute/virtualMachines/write dan Microsoft.Resources/deployments/*. Operasi bagaimana-jika memiliki persyaratan izin yang sama.

Untuk daftar peran dan izin, lihat Peran bawaan Azure.

Cakupan penyebaran

Anda dapat menargetkan penyebaran Anda 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 menyebarkan templat lokal atau file Bicep, 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 --template-file parameter 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.

Diperlukan beberapa menit untuk menyelesaikan templat penyebaran Azure. 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 di repositori GitHub privat, lihat solusi kustom yang didokumentasikan dalam Membuat Penawaran Portal Microsoft Azure Kustom yang 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 selengkapnya, lihat Menggunakan jalur relatif untuk templat tertaut.

Nama templat penyebaran Azure

Saat menyebarkan templat ARM, Anda dapat memberi nama untuk templat penyebaran Azure. Nama ini dapat membantu Anda mengambil 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, entri ditambahkan ke riwayat penyebaran grup sumber daya dengan nama penyebaran. Jika Anda menjalankan penyebaran lain dan memberinya nama yang sama, entri sebelumnya diganti dengan penyebaran 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 untuk memastikan entri unik dalam riwayat penyebaran, berikan nama unik pada setiap penyebaran nama.

Menyebarkan spesifikasi templat

Sebagai ganti menyebarkan templat lokal atau jarak jauh, Anda dapat membuat spesifikasi templat. Spesifikasi templat adalah sumber daya di langganan Azure Anda yang berisi templat ARM. Sumber daya ini memudahkan Anda berbagi templat dengan pengguna di organisasi Anda secara aman. Anda dapat 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 spesifikasi templat dan sebarkan.

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 templat untuk kesalahan.

Parameter

Untuk meneruskan nilai parameter, Anda dapat menggunakan parameter sebaris 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, berikan 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.jspada 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 kuotasi ganda di sekitar JSON yang ingin Anda teruskan ke 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, Anda mungkin merasa lebih mudah untuk menggunakan file parameter, baik .bicepparam file 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 Membuat file parameter Resource Manager.

File parameter Bicep

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. using Dengan pernyataan dalam file parameter Bicep, tidak perlu memberikan --template-file sakelar saat menentukan file parameter Bicep untuk --parameters sakelar. Menyertakan switch --template-file menghasilkan kesalahan "Hanya templat .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 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 lebih lama, Anda dapat menyebarkan templat dengan string atau komentar multibaris menggunakan tombol --handle-extended-json-format. Contohnya:

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2018-10-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