Modul Bicep

Artikel
10/17/2024

Bicep memungkinkan Anda mengatur penyebaran ke dalam modul. Modul adalah file Bicep (atau templat JSON Azure Resource Manager) yang disebarkan dari file Bicep lain. Dengan modul, Anda meningkatkan keterbacaan file Bicep Anda dengan merangkum detail penyebaran yang kompleks. Anda juga dapat dengan mudah menggunakan kembali modul untuk penyebaran yang berbeda.

Untuk berbagi modul dengan orang lain di organisasi Anda, buat spesifikasi templat, atau registri privat. Modul dan spesifikasi templat dalam registri hanya tersedia bagi pengguna dengan izin yang tepat.

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.

Modul bicep dikonversi menjadi satu templat Azure Resource Manager dengan templat berlapis. Untuk informasi selengkapnya tentang cara Bicep menyelesaikan file konfigurasi dan bagaimana Bicep menggabungkan file konfigurasi yang ditentukan pengguna dengan file konfigurasi default, lihat Proses resolusi file konfigurasi dan Proses penggabungan file konfigurasi.

Sumber daya pelatihan

Jika Anda lebih suka mempelajari modul melalui panduan langkah demi langkah, lihat Membuat file Bicep yang dapat disusun menggunakan modul.

Menentukan modul

Sintaks dasar untuk mendefinisikan modul adalah:

@<decorator>(<argument>)
module <symbolic-name> '<path-to-file>' = {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
}

Jadi, contoh sederhana dan nyata akan terlihat seperti:

module stgModule '../storageAccount.bicep' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

Anda juga dapat menggunakan tempatl ARM JSON sebagai modul:

module stgModule '../storageAccount.json' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

Gunakan nama simbolis untuk mereferensikan modul di bagian lain dari file Bicep. Misalnya, Anda dapat menggunakan nama simbolis untuk mendapatkan output dari modul. Nama simbolis mungkin berisi a-z, A-Z, 0-9, dan garis bawah (_). Nama tidak boleh dimulai dengan angka. Modul tidak dapat memiliki nama yang sama dengan parameter, variabel, atau sumber daya.

Jalur dapat berupa file lokal atau file dalam registri. File lokal dapat berupa file Bicep atau templat ARM JSON. Untuk informasi selengkapnya, lihat Jalur ke modul.

Properti name wajib diisi. Ini menjadi nama sumber daya penyebaran berlapis di templat yang dihasilkan.

Jika modul dengan nama statis disebarkan secara bersamaan ke cakupan yang sama, ada potensi bagi satu penyebaran untuk mengganggu output dari penyebaran lain. Misalnya, jika dua file Bicep menggunakan modul yang sama dengan nama statis yang sama (examplemodule) dan ditargetkan ke grup sumber daya yang sama, satu penyebaran mungkin menunjukkan output yang salah. Jika Anda khawatir tentang penyebaran bersamaan ke cakupan yang sama, beri modul Anda nama yang unik.

Contoh berikut menggabungkan nama penyebaran ke nama modul. Jika Anda memberikan nama unik untuk penyebaran, nama modul juga unik.

module stgModule 'storageAccount.bicep' = {
  name: '${deployment().name}-storageDeploy'
  scope: resourceGroup('demoRG')
}

Jika Anda perlu menentukan cakupan yang berbeda dengan cakupan untuk file utama, tambahkan properti cakupan. Untuk informasi selengkapnya, lihat Mengatur cakupan modul.

// deploy to different scope
module <symbolic-name> '<path-to-file>' = {
  name: '<linked-deployment-name>'
  scope: <scope-object>
  params: {
    <parameter-names-and-values>
  }
}

Untuk menyebarkan modul secara kondisional, tambahkan ekspresi if. Penggunaannya mirip dengan menyebarkan sumber daya secara kondisional.

// conditional deployment
module <symbolic-name> '<path-to-file>' = if (<condition-to-deploy>) {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
}

Untuk menyebarkan lebih dari satu instans modul, tambahkan ekspresi for. Anda dapat menggunakan dekorator batchSize untuk menentukan apakah instans digunakan secara serial atau paralel. Untuk informasi selengkapnya, lihat loop Iterasi di Bisep.

// iterative deployment
@batchSize(int) // optional decorator for serial deployment
module <symbolic-name> '<path-to-file>' = [for <item> in <collection>: {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
}]

Seperti sumber daya, modul disebarkan secara paralel kecuali modul tersebut bergantung pada modul atau sumber daya lain. Biasanya, Anda tidak perlu mengatur dependensi karena dependensi ditentukan secara implisit. Jika perlu mengatur dependensi eksplisit, Anda dapat menambahkan dependsOn ke definisi modul. Untuk mempelajari lebih lanjut tentang dependensi, lihat Sumber daya dependensi.

module <symbolic-name> '<path-to-file>' = {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
  dependsOn: [
    <symbolic-names-to-deploy-before-this-item>
  ]
}

Jalur ke modul

File untuk modul dapat berupa file lokal atau file eksternal. File eksternal dapat berupa spesifikasi templat atau registri modul Bisep.

File lokal

Jika modul berupa file lokal, berikan jalur relatif ke file tersebut. Semua jalur di Bicep harus ditentukan menggunakan pemisah direktori garis miring (/) untuk memastikan kompilasi lintas platform yang konsisten. Karakter garis miring terbalik (\) Windows tidak didukung. Jalur dapat berisi spasi.

Misalnya, untuk menyebarkan file yang naik satu tingkat di direktori dari file utama Anda, gunakan:

module stgModule '../storageAccount.bicep' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

File dalam registri

Registri modul publik

Catatan

Modul Non-AVM (Modul Terverifikasi Azure) dihentikan dari registri modul publik.

Modul Terverifikasi Azure adalah modul bawaan, yang telah dibuktikan, dan diverifikasi sebelumnya untuk menyebarkan sumber daya di Azure. Dibuat dan dimiliki oleh karyawan Microsoft, modul ini dirancang untuk menyederhanakan dan mempercepat proses penyebaran untuk sumber daya dan konfigurasi Azure umum sambil juga selaras dengan praktik terbaik; seperti Kerangka Kerja Well-Architected.

Telusuri ke IndeksBicep Modul Terverifikasi Azure untuk melihat daftar modul yang tersedia, pilih angka yang disorot dalam cuplikan layar berikut untuk dibawa langsung ke tampilan yang difilter tersebut.

Cuplikan layar Azure Verified Modules (AVM).

Daftar modul menunjukkan versi terbaru. Pilih nomor versi untuk melihat daftar versi yang tersedia:

Cuplikan layar versi Azure Verified Modules (AVM).

Untuk menautkan ke modul publik, tentukan jalur modul dengan sintaks berikut:

module <symbolic-name> 'br/public:<file-path>:<tag>' = {}

br/public adalah alias untuk modul publik. Anda dapat menyesuaikan alias ini dalam file konfigurasi Bicep.
jalur file dapat berisi segmen yang dipisahkan oleh karakter /.
tag digunakan untuk menentukan versi modul.

Contoh:

module storage 'br/public:avm/res/storage/storage-account:0.9.0' = {
  name: 'myStorage'
  params: {
    name: 'store${resourceGroup().name}'
  }
}

Catatan

br/public adalah alias untuk modul publik. Ini juga dapat ditulis sebagai:

module <symbolic-name> 'br:mcr.microsoft.com/bicep/<file-path>:<tag>' = {}

Registri modul privat

Jika telah menerbitkan modul ke registri, Anda dapat menautkan ke modul tersebut. Berikan nama untuk registri kontainer Azure dan jalur ke modul. Tentukan jalur modul dengan sintaks berikut:

module <symbolic-name> 'br:<registry-name>.azurecr.io/<file-path>:<tag>' = {

br adalah nama skema untuk registri Bicep.
jalur file disebut repository di Azure Container Registry. jalur file dapat berisi segmen yang dipisahkan oleh karakter /.
tag digunakan untuk menentukan versi modul.

Contohnya:

module stgModule 'br:exampleregistry.azurecr.io/bicep/modules/storage:v1' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

Saat Anda mereferensikan modul dalam registri, ekstensi Bicep di Visual Studio Code secara otomatis memanggil pemulihan bicep untuk menyalin modul eksternal ke cache lokal. Dibutuhkan beberapa saat untuk memulihkan modul eksternal. Jika intellisense untuk modul tidak berfungsi secara langsung, tunggu hingga pemulihan selesai.

Jalur penuh untuk modul dalam registri bisa panjang. Alih-alih menyediakan jalur penuh setiap kali Anda ingin menggunakan modul, Anda dapat mengonfigurasi alias dalam file bicepconfig.json. Alias memudahkan referensi ke modul. Misalnya, dengan alias, Anda dapat mempersingkat jalur ke:

module stgModule 'br/ContosoModules:storage:v1' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

Alias untuk registri modul publik telah ditentukan sebelumnya:

module storage 'br/public:avm/res/storage/storage-account:0.9.0' = {
  name: 'myStorage'
  params: {
    name: 'store${resourceGroup().name}'
  }
}

Anda dapat mengambil alih alias publik dalam file bicepconfig.json.

File di spesifikasi templat

Setelah membuat spesifikasi templat, Anda dapat menautkan spesifikasi templat tersebut ke dalam sebuah modul. Tentukan spesifikasi templat dalam format berikut:

module <symbolic-name> 'ts:<sub-id>/<rg-name>/<template-spec-name>:<version>' = {

Namun, Anda dapat menyederhanakan file Bisep dengan membuat alias untuk grup sumber daya yang berisi spesifikasi templat Anda. Saat menggunakan alias, sintaksis akan menjadi:

module <symbolic-name> 'ts/<alias>:<template-spec-name>:<version>' = {

Modul berikut menyebarkan spesifikasi templat untuk membuat akun penyimpanan. Langganan dan grup sumber daya untuk spesifikasi templat ditentukan dalam alias bernama ContosoSpecs.

module stgModule 'ts/ContosoSpecs:storageSpec:2.0' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

Menggunakan dekorator

Dekorator ditulis dalam format @expression dan ditempatkan di atas deklarasi modul. Tabel berikut menunjukkan dekorator yang tersedia untuk modul.

Dekorator	Argumen	Deskripsi
batchSize	tidak ada	Siapkan instans untuk disebarkan secara berurutan.
description	string	Berikan deskripsi untuk modul.

Dekotaror berada dalam namespace layanan sys. Jika Anda perlu membedakan suatu dekorator dari item lainnya dengan nama yang sama, awali dekorator dengan sys. Contohnya, jika file Bicep Anda mencakup parameter bernama description, Anda harus menambahkan namespace layanan sys saat menggunakan dekorator deskripsi.

BatchSize

Anda hanya dapat menerapkan @batchSize() ke definisi sumber daya atau modul yang menggunakan for ekspresi.

Secara default, modul disebarkan secara paralel. Saat Anda menambahkan dekorator @batchSize(int), Anda menerapkan instans secara serial.

@batchSize(3)
module storage 'br/public:avm/res/storage/storage-account:0.11.1' = [for storageName in storageAccounts: {
  name: 'myStorage'
  params: {
    name: 'store${resourceGroup().name}'
  }
}]

Untuk informasi selengkapnya, lihat Menyebarkan dalam batch.

Deskripsi

Untuk menambahkan penjelasan, tambahkan deskripsi ke deklarasi modul. Contohnya:

@description('Create storage accounts referencing an AVM.')
module storage 'br/public:avm/res/storage/storage-account:0.9.0' = {
  name: 'myStorage'
  params: {
    name: 'store${resourceGroup().name}'
  }
}

Teks berformat markdown dapat digunakan untuk teks deskripsi.

Parameter

Parameter yang Anda berikan dalam definisi modul cocok dengan parameter dalam file Bicep.

Contoh Bicep berikut memiliki tiga parameter - storagePrefix, storageSKU, dan location. Parameter storageSKU memiliki nilai default sehingga Anda tidak perlu memasukkan nilai untuk parameter tersebut selama penyebaran.

@minLength(3)
@maxLength(11)
param storagePrefix string

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_RAGRS'
  'Standard_ZRS'
  'Premium_LRS'
  'Premium_ZRS'
  'Standard_GZRS'
  'Standard_RAGZRS'
])
param storageSKU string = 'Standard_LRS'

param location string

var uniqueStorageName = '${storagePrefix}${uniqueString(resourceGroup().id)}'

resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

output storageEndpoint object = stg.properties.primaryEndpoints

Untuk menggunakan contoh sebelumnya sebagai modul, masukkan nilai untuk parameter tersebut.

targetScope = 'subscription'

@minLength(3)
@maxLength(11)
param namePrefix string

resource demoRG 'Microsoft.Resources/resourceGroups@2024-03-01' existing = {
  name: 'demogroup1'
}

module stgModule '../create-storage-account/main.bicep' = {
  name: 'storageDeploy'
  scope: demoRG
  params: {
    storagePrefix: namePrefix
    location: demoRG.location
  }
}

output storageEndpoint object = stgModule.outputs.storageEndpoint

Mengatur cakupan modul

Saat mendeklarasikan modul, Anda dapat mengatur ruang lingkup untuk modul yang berbeda dari ruang lingkup untuk file Bisep yang berisi. Gunakan properti scope untuk mengatur ruang lingkup modul. Ketika properti cakupan tidak disediakan, modul disebarkan di cakupan target induk.

Contoh file Bicep berikut membuat grup sumber daya dan akun penyimpanan dalam grup sumber daya tersebut. File ini disebarkan ke langganan, tetapi modul dicakup ke grup sumber daya baru.

// set the target scope for this file
targetScope = 'subscription'

@minLength(3)
@maxLength(11)
param namePrefix string

param location string = deployment().location

var resourceGroupName = '${namePrefix}rg'

resource newRG 'Microsoft.Resources/resourceGroups@2024-03-01' = {
  name: resourceGroupName
  location: location
}

module stgModule '../create-storage-account/main.bicep' = {
  name: 'storageDeploy'
  scope: newRG
  params: {
    storagePrefix: namePrefix
    location: location
  }
}

output storageEndpoint object = stgModule.outputs.storageEndpoint

Contoh berikutnya menyebarkan akun penyimpanan ke dua grup sumber daya yang berbeda. Kedua grup sumber daya ini pasti sudah ada.

targetScope = 'subscription'

resource firstRG 'Microsoft.Resources/resourceGroups@2024-03-01' existing = {
  name: 'demogroup1'
}

resource secondRG 'Microsoft.Resources/resourceGroups@2024-03-01' existing = {
  name: 'demogroup2'
}

module storage1 '../create-storage-account/main.bicep' = {
  name: 'westusdeploy'
  scope: firstRG
  params: {
    storagePrefix: 'stg1'
    location: 'westus'
  }
}

module storage2 '../create-storage-account/main.bicep' = {
  name: 'eastusdeploy'
  scope: secondRG
  params: {
    storagePrefix: 'stg2'
    location: 'eastus'
  }
}

Atur properti cakupan ke objek cakupan yang valid. Jika file Bicep Anda menyebarkan grup sumber daya, langganan, atau grup manajemen, Anda dapat mengatur cakupan modul ke nama simbolis untuk sumber daya tersebut. Atau, Anda dapat menggunakan fungsi cakupan untuk mendapatkan cakupan yang valid.

Fungsi-fungsi itu adalah:

Contoh berikut menggunakan fungsi managementGroup untuk mengatur ruang lingkup.

param managementGroupName string

module mgDeploy 'main.bicep' = {
  name: 'deployToMG'
  scope: managementGroup(managementGroupName)
}

Output

Anda bisa mendapatkan nilai dari modul dan menggunakannya dalam file Bicep utama. Untuk mendapatkan nilai output dari modul, gunakan properti outputs pada objek modul.

Contoh pertama membuat akun penyimpanan dan menampilkan titik akhir utama.

@minLength(3)
@maxLength(11)
param storagePrefix string

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_RAGRS'
  'Standard_ZRS'
  'Premium_LRS'
  'Premium_ZRS'
  'Standard_GZRS'
  'Standard_RAGZRS'
])
param storageSKU string = 'Standard_LRS'

param location string

var uniqueStorageName = '${storagePrefix}${uniqueString(resourceGroup().id)}'

resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

output storageEndpoint object = stg.properties.primaryEndpoints

Jika digunakan sebagai modul, Anda bisa mendapatkan nilai output itu.

targetScope = 'subscription'

@minLength(3)
@maxLength(11)
param namePrefix string

resource demoRG 'Microsoft.Resources/resourceGroups@2024-03-01' existing = {
  name: 'demogroup1'
}

module stgModule '../create-storage-account/main.bicep' = {
  name: 'storageDeploy'
  scope: demoRG
  params: {
    storagePrefix: namePrefix
    location: demoRG.location
  }
}

output storageEndpoint object = stgModule.outputs.storageEndpoint

Langkah berikutnya

Untuk tutorial, lihat Menyebarkan sumber daya Azure dengan menggunakan templat Bicep.
Untuk meneruskan nilai sensitif ke modul, gunakan fungsi getSecret.

Bagikan melalui