Praktik terbaik templat ARM

Artikel
09/22/2023

Artikel ini memperlihatkan kepada Anda cara menggunakan praktik yang direkomendasikan saat membuat templat Azure Resource Manager (templat ARM). Rekomendasi ini membantu Anda menghindari masalah umum saat menggunakan templat ARM untuk menyebarkan solusi.

Batas templat

Batasi ukuran templat Anda hingga 4 MB, dan setiap definisi sumber daya hingga 1 MB. Batas berlaku untuk status akhir templat setelah diperluas dengan definisi sumber daya berulang, dan nilai untuk variabel dan parameter. File parameter juga dibatasi hingga 4 MB. Anda mungkin mendapatkan kesalahan dengan templat atau file parameter yang kurang dari 4 MB jika ukuran total permintaan terlalu besar. Untuk informasi selengkapnya tentang cara menyederhanakan templat Anda untuk menghindari permintaan besar, lihat Mengatasi kesalahan untuk ukuran pekerjaan yang terlampaui.

Anda juga terbatas pada:

256 parameter
256 variabel
800 sumber daya (termasuk jumlah salinan)
64 nilai output
10 lokasi unik untuk setiap cakupan grup langganan/penyewa/manajemen
24.576 karakter dalam ekspresi templat

Anda dapat melampaui beberapa batas templat dengan menggunakan templat berlapis. Untuk informasi selengkapnya, lihat Menggunakan templat yang ditautkan dan berlapis saat menyebarkan sumber daya Azure. Untuk mengurangi jumlah parameter, variabel, atau output, Anda dapat menggabungkan beberapa nilai ke dalam objek. Untuk informasi selengkapnya, lihat Objek sebagai parameter.

Grup sumber daya

Saat Anda menyebarkan sumber daya ke grup sumber daya, grup sumber daya menyimpan metadata tentang sumber daya tersebut. Metadata tersebut disimpan di lokasi grup sumber daya.

Jika wilayah grup sumber daya untuk sementara waktu tidak tersedia, Anda tidak dapat memperbarui sumber daya dalam grup sumber daya karena metadata tidak tersedia. Sumber daya di wilayah lain masih akan berfungsi seperti yang diharapkan, tetapi Anda tidak dapat memperbaruinya. Untuk meminimalkan risiko, tempatkan grup sumber daya dan sumber daya Anda di wilayah yang sama.

Parameter

Informasi di bagian ini dapat membantu ketika Anda bekerja dengan parameter.

Rekomendasi umum untuk parameter

Minimalkan penggunaan parameter Anda. Sebagai gantinya, gunakan variabel atau nilai harfiah untuk properti yang tidak perlu ditentukan selama penyebaran.
Gunakan camel case untuk nama parameter.
Gunakan parameter untuk pengaturan yang bervariasi sesuai dengan lingkungan, seperti SKU, ukuran, atau kapasitas.
Gunakan parameter untuk nama sumber daya yang ingin Anda tentukan agar mudah diidentifikasi.

Berikan deskripsi setiap parameter dalam metadata.

"parameters": {
  "storageAccountType": {
    "type": "string",
    "metadata": {
      "description": "The type of the new storage account created to store the VM disks."
    }
  }
}

Tentukan nilai default untuk parameter yang tidak sensitif. Dengan menentukan nilai default, jadi lebih mudah untuk menyebarkan templat, dan pengguna templat Anda melihat contoh nilai yang sesuai. Nilai default apa pun untuk parameter harus valid untuk semua pengguna dalam konfigurasi penyebaran default.
```
"parameters": {
  "storageAccountType": {
    "type": "string",
    "defaultValue": "Standard_GRS",
    "metadata": {
      "description": "The type of the new storage account created to store the VM disks."
    }
  }
}
```

Untuk menentukan parameter opsional, jangan gunakan untai (karakter) kosong sebagai nilai default. Sebagai gantinya, gunakan nilai harfiah atau ekspresi bahasa untuk membangun nilai.

"storageAccountName": {
   "type": "string",
   "defaultValue": "[concat('storage', uniqueString(resourceGroup().id))]",
   "metadata": {
     "description": "Name of the storage account"
   }
}

Gunakan allowedValues dengan hemat. Gunakan hanya saat Anda harus memastikan beberapa nilai tidak disertakan dalam opsi yang diizinkan. Jika Anda menggunakan allowedValues terlalu luas, Anda bisa jadi memblokir penyebaran yang valid dengan tidak memperbarui daftar Anda.
Ketika nama parameter di templat Anda cocok dengan parameter di perintah penyebaran PowerShell, Resource Manager menyelesaikan konflik penamaan ini dengan menambahkan postfix FromTemplate ke parameter templat. Misalnya, jika Anda menyertakan parameter bernama ResourceGroupName dalam templat Anda, parameter tersebut berkonflik dengan parameter ResourceGroupName di cmdlet New-AzResourceGroupDeployment. Selama penyebaran, Anda diminta untuk memberikan nilai untuk ResourceGroupNameFromTemplate.

Rekomendasi keamanan untuk parameter

Selalu gunakan parameter untuk nama pengguna dan kata sandi (atau rahasia).
Gunakan securestring untuk semua kata sandi dan rahasia. Jika Anda meneruskan data sensitif dalam objek JSON, gunakan jenis secureObject tersebut. Parameter templat dengan untai (karakter) aman atau jenis objek aman tidak dapat dibaca setelah penyebaran sumber daya.
```
"parameters": {
  "secretValue": {
    "type": "securestring",
    "metadata": {
      "description": "The value of the secret to store in the vault."
    }
  }
}
```
Jangan berikan nilai default untuk nama pengguna, kata sandi, atau nilai apa pun yang memerlukan jenis secureString.
Jangan berikan nilai default untuk properti yang meningkatkan permukaan area serangan aplikasi.

Rekomendasi lokasi untuk parameter

Gunakan parameter untuk menentukan lokasi sumber daya, dan atur nilai default ke resourceGroup().location. Menyediakan parameter lokasi memungkinkan pengguna templat untuk menentukan lokasi di mana mereka memiliki izin untuk menyebarkan sumber daya.
```
"parameters": {
   "location": {
     "type": "string",
     "defaultValue": "[resourceGroup().location]",
     "metadata": {
       "description": "The location in which the resources should be deployed."
     }
   }
}
```
Jangan tentukan allowedValues sebagai parameter lokasi. Lokasi yang Anda tentukan mungkin tidak tersedia di semua cloud.
Gunakan nilai parameter lokasi untuk sumber daya yang sangat mungkin berada di lokasi yang sama. Pendekatan ini mengecilkan jumlah berapa kali pengguna diminta untuk memberikan informasi lokasi.
Untuk sumber daya yang tidak tersedia di semua lokasi, gunakan parameter terpisah atau tentukan nilai lokasi harfiah.

Variabel

Informasi berikut ini dapat membantu ketika Anda bekerja dengan variabel:

Gunakan camel case untuk nama variabel.
Gunakan variabel untuk nilai yang perlu Anda gunakan lebih dari sekali dalam templat. Jika nilai hanya digunakan sekali, nilai yang dikodekan secara permanen membuat templat Anda lebih mudah dibaca.
Gunakan variabel untuk nilai yang Anda buat dari susunan fungsi templat yang kompleks. Templat Anda lebih mudah dibaca saat ekspresi kompleks hanya muncul dalam variabel.
Anda tidak dapat menggunakan fungsi referensi di bagian templat variables. Fungsi reference ini memperoleh nilainya dari status runtime sumber daya. Namun, variabel diselesaikan selama penguraian awal templat. Buatlah nilai yang memerlukan fungsi reference langsung di resources atau outputs bagian templat.
Sertakan variabel untuk nama sumber daya yang harus unik.
Gunakan perulangan salinan dalam variabel untuk membuat pola berulang objek JSON.
Hapus variabel yang tidak digunakan.

versi API

Atur properti apiVersion ke versi API dikodekan secara permanen untuk jenis sumber daya tersebut. Saat membuat templat baru, kami sarankan Anda menggunakan versi API terbaru untuk satu jenis sumber daya. Untuk menentukan nilai yang tersedia, lihat referensi templat.

Ketika templat Anda berfungsi seperti yang diharapkan, kami sarankan Anda terus menggunakan versi API yang sama. Dengan menggunakan versi API yang sama, Anda tidak perlu khawatir memutuskan perubahan yang mungkin diperkenalkan di versi yang lebih baru.

Jangan gunakan parameter untuk versi API tersebut. Properti dan nilai sumber daya dapat bervariasi menurut versi API. IntelliSense dalam editor kode tidak dapat menentukan skema yang benar saat versi API diatur ke satu parameter. Jika Anda meneruskan versi API yang tidak cocok dengan properti di templat Anda, penyebaran akan gagal.

Jangan gunakan variabel untuk versi API.

Dependensi sumber daya

Saat memutuskan dependensi apa yang akan ditetapkan, gunakan panduan berikut:

Gunakan fungsi reference dan berikan nama sumber daya untuk mengatur dependensi implisit antara sumber daya yang perlu berbagi properti. Jangan tambahkan elemen dependsOn eksplisit saat Anda sudah menentukan dependensi implisit. Pendekatan ini mengurangi risiko memiliki dependensi yang tidak perlu. Untuk contoh pengaturan dependensi implisit, lihat fungsi referensi dan daftar.
Tetapkan sumber daya anak sebagai dependen pada sumber daya induknya.
Sumber daya dengan elemen kondisi yang diatur ke false secara otomatis dihapus dari urutan dependensi. Atur dependensi seolah-olah sumber daya selalu disebarkan.
Biarkan dependensi bertingkat tanpa mengaturnya secara eksplisit. Misalnya, komputer virtual Anda bergantung pada antarmuka jaringan virtual, dan antarmuka jaringan virtual bergantung pada jaringan virtual dan alamat IP publik. Oleh karena itu, komputer virtual disebarkan setelah ketiga sumber daya, tetapi jangan mengatur komputer virtual sebagai dependen pada ketiga sumber daya secara eksplisit. Pendekatan ini mengklarifikasi urutan dependensi dan membuatnya lebih mudah untuk mengubah templat nanti.
Jika nilai dapat ditentukan sebelum penyebaran, coba sebarkan sumber daya tanpa dependensi. Misalnya, jika nilai konfigurasi memerlukan nama sumber daya lain, Anda mungkin tidak memerlukan dependensi. Panduan ini tidak selalu berfungsi karena beberapa sumber daya memastikan keberadaan sumber daya lainnya. Jika Anda menerima kesalahan, tambahkan dependensi.

Sumber

Informasi berikut ini dapat membantu ketika Anda bekerja dengan sumber daya:

Untuk membantu kontributor lain memahami tujuan sumber daya tersebut, tentukan comments untuk setiap sumber daya dalam templat.

"resources": [
  {
    "name": "[variables('storageAccountName')]",
    "type": "Microsoft.Storage/storageAccounts",
    "apiVersion": "2019-06-01",
    "location": "[resourceGroup().location]",
    "comments": "This storage account is used to store the VM disks.",
      ...
  }
]

Jika templat ARM Anda disimpan dalam file .jsonc, komentar yang menggunakan sintaksis // akan didukung, seperti yang ditunjukkan di sini.

"resources": [
  {
    // This storage account is used to store the VM disks.
    "name": "[variables('storageAccountName')]",
    "type": "Microsoft.Storage/storageAccounts",
    "apiVersion": "2019-06-01",
    "location": "[resourceGroup().location]",
      ...
  }
]

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

Jika Anda menggunakan titik akhir publik di templat Anda (seperti titik akhir publik penyimpanan Azure Blob), jangan dikodekan secara permanen namespace layanan tersebut. Gunakan fungsi reference untuk mengambil namespace layanan secara dinamis. Anda dapat menggunakan pendekatan ini untuk menyebarkan templat ke lingkungan namespace layanan publik yang berbeda tanpa mengubah titik akhir dalam templat secara manual. Atur versi API ke versi yang sama dengan yang Anda gunakan untuk akun penyimpanan di templat Anda.
```
"diagnosticsProfile": {
  "bootDiagnostics": {
    "enabled": "true",
    "storageUri": "[reference(resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName')), '2019-06-01').primaryEndpoints.blob]"
  }
}
```
Jika akun penyimpanan disebarkan dalam templat yang sama dengan yang Anda buat dan nama akun penyimpanan tidak dibagikan dengan sumber daya lain dalam templat, Anda tidak perlu menentukan namespace layanan penyedia atau apiVersion saat Anda mereferensikan sumber daya. Contoh berikut memperlihatkan sintaks yang disederhanakan.
```
"diagnosticsProfile": {
  "bootDiagnostics": {
    "enabled": "true",
    "storageUri": "[reference(variables('storageAccountName')).primaryEndpoints.blob]"
  }
}
```
Anda juga dapat mereferensikan akun penyimpanan yang sudah ada yang berada di grup sumber daya yang berbeda.
```
"diagnosticsProfile": {
  "bootDiagnostics": {
    "enabled": "true",
    "storageUri": "[reference(resourceId(parameters('existingResourceGroup'), 'Microsoft.Storage/storageAccounts', parameters('existingStorageAccountName')), '2019-06-01').primaryEndpoints.blob]"
  }
}
```
Tetapkan alamat IP publik ke komputer virtual hanya ketika aplikasi memerlukannya. Untuk menyambungkan ke mesin virtual untuk tujuan administratif, gunakan aturan NAT masuk, gateway jaringan virtual, atau jumpbox.

Untuk informasi selengkapnya tentang menyambungkan ke komputer virtual, lihat:

Properti domainNameLabel untuk alamat IP publik harus unik. Nilai domainNameLabel harus berkisar antara 3 hingga 63 karakter, dan mengikuti aturan yang ditentukan oleh regex ini: ^[a-z][a-z0-9-]{1,61}[a-z0-9]$. Karena fungsi uniqueString ini menghasilkan untai (karakter) yang panjangnya 13 karakter, parameter dnsPrefixString terbatas pada 50 karakter.

"parameters": {
  "dnsPrefixString": {
    "type": "string",
    "maxLength": 50,
    "metadata": {
      "description": "The DNS label for the public IP address. It must be lowercase. It should match the following regular expression, or it will raise an error: ^[a-z][a-z0-9-]{1,61}[a-z0-9]$"
    }
  }
},
"variables": {
  "dnsPrefix": "[concat(parameters('dnsPrefixString'),uniquestring(resourceGroup().id))]"
}

Saat Anda menambahkan kata sandi ke ekstensi skrip kustom, gunakan properti commandToExecute di properti protectedSettings.

"properties": {
  "publisher": "Microsoft.Azure.Extensions",
  "type": "CustomScript",
  "typeHandlerVersion": "2.0",
  "autoUpgradeMinorVersion": true,
  "settings": {
    "fileUris": [
      "[concat(variables('template').assets, '/lamp-app/install_lamp.sh')]"
    ]
  },
  "protectedSettings": {
    "commandToExecute": "[concat('sh install_lamp.sh ', parameters('mySqlPassword'))]"
  }
}

Catatan

Untuk memastikan bahwa rahasia dienkripsi ketika diteruskan sebagai parameter ke komputer virtual dan ekstensi, gunakan properti protectedSettings pada ekstensi yang relevan.

Tentukan nilai eksplisit untuk properti yang memiliki nilai default yang bisa berubah dari waktu ke waktu. Misalnya, jika Anda menyebarkan kluster AKS, Anda dapat menentukan atau menghilangkan properti kubernetesVersion. Jika Anda tidak menentukannya, maka kluster diatur default ke versi minor N-1 dan patch terbaru. Saat Anda menyebarkan kluster menggunakan templat ARM, perilaku default ini mungkin bukan yang Anda harapkan. Menyebarkan kembali templat Anda dapat mengakibatkan kluster ditingkatkan ke versi Kubernetes baru secara tak terduga. Sebagai gantinya, pertimbangkan untuk menentukan nomor versi eksplisit lalu ubah secara manual saat Anda siap untuk meningkatkan kluster Anda.

Komentar

Selain properti comments, komentar yang menggunakan sintaksis // didukung. Untuk detail selengkapnya tentang komentar dan metadata, lihat Memahami struktur dan sintaksis templat ARM. Anda dapat memilih untuk menyimpan file JSON yang berisi // komentar menggunakan ekstensi file .jsonc, untuk menunjukkan bahwa file JSON berisi komentar. Layanan ARM juga akan menerima komentar dalam file JSON apa pun termasuk file parameter.

Alat ARM Visual Studio Code

Bekerja dengan templat ARM jauh lebih mudah dengan Alat Azure Resource Manager (ARM) untuk Visual Studio Code. Ekstensi ini menyediakan dukungan bahasa, cuplikan sumber daya, dan penyelesaian otomatis sumber daya untuk membantu Anda membuat dan memvalidasi templat Azure Resource Manager. Untuk mempelajari lebih lanjut dan menginstal ekstensi, lihat Alat Azure Resource Manager (ARM).

Gunakan toolkit pengujian

Toolkit pengujian templat ARM adalah skrip yang memeriksa apakah templat Anda menggunakan praktik yang direkomendasikan. Saat templat Anda tidak sesuai dengan praktik yang direkomendasikan, templat ini akan mengembalikan daftar peringatan dengan perubahan yang disarankan. Toolkit pengujian dapat membantu Anda mempelajari cara menerapkan praktik terbaik di templat Anda.

Setelah Anda menyelesaikan templat Anda, jalankan toolkit pengujian untuk melihat apakah ada cara untuk meningkatkan implementasinya. Untuk informasi selengkapnya, lihat Menggunakan toolkit pengujian templat ARM.

Langkah berikutnya

Untuk informasi tentang struktur dalam file templat, lihat Memahami struktur dan sintaks templat ARM.
Untuk rekomendasi tentang cara membangun templat yang berfungsi di semua lingkungan cloud Azure, lihat Mengembangkan templat ARM untuk konsistensi cloud.