Menyebarkan sumber daya dengan templat ARM dan Azure PowerShell

Artikel
03/20/2024

Artikel ini menjelaskan cara menggunakan Azure PowerShell 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 templat.

Tip

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

Prasyarat

Anda memerlukan templat untuk disebarkan. Jika Anda belum memilikinya, unduh dan simpan templat contoh dari repositori templat Mulai Cepat Azure. Nama berkas lokal yang digunakan dalam artikel ini C:\MyTemplates\azuredeploy.json.

Anda perlu menginstal Azure PowerShell dan menyambungkan ke Azure:

Instal cmdlet Azure PowerShell di komputer lokal Anda. Untuk informasi selengkapnya, lihat Mulai menggunakan Azure PowerShell.
Sambungkan ke Azure dengan menggunakan Connect-AZAccount. Jika Anda memiliki beberapa langganan Azure, Anda mungkin juga perlu menjalankan Set-AzContext. Untuk informasi selengkapnya, lihat Menggunakan beberapa langganan Azure.

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

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 menyebarkan ke grup sumber daya, gunakan New-AzResourceGroupDeployment:

New-AzResourceGroupDeployment -ResourceGroupName <resource-group-name> -TemplateFile <path-to-template>

Untuk menyebarkan ke langganan, gunakan New-AzSubscriptionDeployment yang merupakan alias dari New-AzDeployment cmdlet:
```
New-AzSubscriptionDeployment -Location <location> -TemplateFile <path-to-template>
```
Untuk informasi selengkapnya tentang penyebaran tingkat langganan, lihat Membuat grup sumber daya dan sumber daya di tingkat langganan.
Untuk menyebarkan ke grup manajemen, gunakan New-AzManagementGroupDeployment.
```
New-AzManagementGroupDeployment -Location <location> -TemplateFile <path-to-template>
```
Untuk informasi selengkapnya tentang penyebaran tingkat grup manajemen, lihat Membuat sumber daya di tingkat grup manajemen.
Untuk menyebarkan ke penyewa, gunakan New-AzTenantDeployment.
```
New-AzTenantDeployment -Location <location> -TemplateFile <path-to-template>
```
Untuk informasi selengkapnya tentang penyebaran tingkat penyewa, lihat Membuat sumber daya di tingkat penyewa.

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

Nama penyebaran

Saat menyebarkan templat ARM, Anda dapat memberi nama penyebaran. 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 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.

$suffix = Get-Random -Maximum 1000
$deploymentName = "ExampleDeployment" + $suffix

Atau, tambahkan nilai tanggal.

$today=Get-Date -Format "MM-dd-yyyy"
$deploymentName="ExampleDeployment"+"$today"

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 templat lokal

Anda dapat menyebarkan templat 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.

New-AzResourceGroup -Name ExampleGroup -Location "Central US"

Untuk menyebarkan templat lokal atau file Bicep, gunakan parameter -TemplateFile dalam perintah penyebaran. Contoh berikut ini juga menunjukkan cara mengatur nilai parameter yang berasal dari template.

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleGroup `
  -TemplateFile <path-to-template>

Diperlukan beberapa menit untuk menyelesaikan penyebaran.

Menyebarkan templat jarak jauh

Sebagai ganti menyimpan templat ARM di mesin lokal Anda, 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.

New-AzResourceGroup -Name ExampleGroup -Location "Central US"

Untuk menyebarkan templat eksternal, gunakan -TemplateUri parameter.

New-AzResourceGroupDeployment `
  -Name remoteTemplateDeployment `
  -ResourceGroupName ExampleGroup `
  -TemplateUri https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.storage/storage-account-create/azuredeploy.json

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 QueryString untuk menentukan token SAS:

New-AzResourceGroupDeployment `
  -Name linkedTemplateWithRelativePath `
  -ResourceGroupName "myResourceGroup" `
  -TemplateUri "https://stage20210126.blob.core.windows.net/template-staging/mainTemplate.json" `
  -QueryString "$sasToken"

Untuk informasi selengkapnya, lihat Menggunakan jalur relatif untuk templat tertaut.

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.

New-AzTemplateSpec `
  -Name storageSpec `
  -Version 1.0 `
  -ResourceGroupName templateSpecsRg `
  -Location westus2 `
  -TemplateJsonFile ./mainTemplate.json

Kemudian, dapatkan ID untuk spesifikasi templat dan sebarkan.

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

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

Untuk informasi selengkapnya, lihat Spesifikasi templat Azure Resource Manager.

Pratinjau perubahan

Sebelum menyebarkan templat Anda, Anda dapat melakukan pratinjau pada perubahan yang akan 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.

Meneruskan nilai 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 nama parameter dengan perintah New-AzResourceGroupDeployment. Misalnya, untuk meneruskan string dan array ke templat, gunakan:

$arrayParam = "value1", "value2"
New-AzResourceGroupDeployment -ResourceGroupName testgroup `
  -TemplateFile <path-to-template> `
  -exampleString "inline string" `
  -exampleArray $arrayParam

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

$arrayParam = "value1", "value2"
New-AzResourceGroupDeployment -ResourceGroupName testgroup `
  -TemplateFile <path-to-template> `
  -exampleString $(Get-Content -Path c:\MyTemplates\stringcontent.txt -Raw) `
  -exampleArray $arrayParam

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

Jika Anda perlu meneruskan array objek, buat tabel hash di PowerShell dan tambahkan ke array. Teruskan array tersebut sebagai parameter selama penyebaran.

$hash1 = @{ Name = "firstSubnet"; AddressPrefix = "10.0.0.0/24"}
$hash2 = @{ Name = "secondSubnet"; AddressPrefix = "10.0.1.0/24"}
$subnetArray = $hash1, $hash2
New-AzResourceGroupDeployment -ResourceGroupName testgroup `
  -TemplateFile <path-to-template> `
  -exampleArray $subnetArray

File parameter JSON

Daripada meneruskan parameter sebagai nilai sebaris dalam skrip Anda, Anda mungkin merasa lebih mudah untuk menggunakan file JSON yang berisi nilai parameter. File parameter dapat menjadi file lokal atau file eksternal dengan URI yang dapat diakses.

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

Untuk meneruskan file parameter lokal, gunakan parameter TemplateParameterFile:

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateFile <path-to-template> `
  -TemplateParameterFile c:\MyTemplates\storage.parameters.json

Untuk meneruskan file parameter eksternal, gunakan parameter TemplateParameterUri:

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateUri https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.storage/storage-account-create/azuredeploy.json `
  -TemplateParameterUri https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.storage/storage-account-create/azuredeploy.parameters.json

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

File parameter Bicep

Dengan Azure PowerShell versi 10.4.0 atau yang lebih baru, dan Bicep CLI versi 0.22.6 atau yang lebih baru, Anda dapat menyebarkan file templat ARM dengan menggunakan file parameter Bicep. using Dengan pernyataan dalam file parameter Bicep, tidak perlu memberikan -TemplateFile sakelar saat menentukan file parameter Bicep untuk -TemplateParameterFile sakelar.

Contoh berikut menunjukkan file parameter bernama storage.bicepparam. File berada di direktori yang sama dengan tempat perintah dijalankan.

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateParameterFile storage.bicepparam

Untuk informasi selengkapnya tentang file parameter Bicep, lihat File parameter Bicep.

Langkah berikutnya

Untuk putar kembali ke penyebaran yang berhasil saat Anda mendapatkan kesalahan, lihat Putar kembali pada kesalahan ke penyebaran yang berhasil.
Untuk menentukan cara menangani sumber daya yang ada di grup sumber daya tetapi tidak ditentukan dalam templat, lihat Mode penyebaran Azure Resource Manager.
Untuk memahami cara menentukan parameter dalam templat Anda, lihat Memahami struktur dan sintaksis templat ARM.
Untuk informasi tentang penyebaran templat yang memerlukan token SAS, lihat Menyebarkan templat ARM privat dengan token SAS.

Menyebarkan sumber daya dengan templat ARM dan Azure PowerShell

Prasyarat

Memerlukan izin

Cakupan penyebaran

Nama penyebaran

Menyebarkan templat lokal

Menyebarkan templat jarak jauh

Menyebarkan spesifikasi templat

Pratinjau perubahan

Meneruskan nilai parameter

Parameter sebaris

File parameter JSON

File parameter Bicep

Langkah berikutnya

Sumber Daya Tambahan: