Modul Bicep

2025-05-10

Dengan Bicep, Anda dapat mengatur penyebaran ke dalam modul. Modul adalah file Bicep yang dideploy oleh Bicep lainnya. Modul juga dapat menjadi templat Azure Resource Manager (templat ARM) untuk JSON. Dengan modul, Anda meningkatkan keterbacaan file Bicep Anda dengan menggambarkan 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. Spesifikasi dan modul templat dalam registri hanya tersedia untuk pengguna dengan izin yang benar.

Tips

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 tidak menggunakan Bicep, gunakan spesifikasi template.
Anda dapat menyebarkan konten di registri modul Bicep hanya dari file Bicep lain. Anda dapat menyebarkan spesifikasi templat langsung dari API, Azure PowerShell, Azure CLI, dan portal Microsoft Azure. Anda bahkan bisa menggunakan UiFormDefinition untuk menyesuaikan pengalaman penyebaran portal.
Bicep memiliki beberapa kemampuan terbatas untuk menyematkan artefak proyek lain (termasuk file non-Bicep dan non-ARM-template seperti 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 ARM 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 ingin mempelajari tentang modul melalui panduan langkah demi langkah, lihat Membuat file Bicep yang dapat dikomposisikan dengan 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>
  }
}

Contoh dunia nyata yang sederhana terlihat seperti:

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

Anda juga dapat menggunakan templat ARM untuk 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 untuk JSON. Untuk informasi selengkapnya, lihat Jalur ke modul.

Properti name bersifat opsional. Ini menjadi nama sumber daya penyebaran tertanam di templat yang dihasilkan. Jika tidak ada nama yang disediakan, GUID akan dibuat sebagai nama untuk sumber daya penyebaran berlapis.

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. Cara lain untuk memastikan nama modul unik adalah dengan meninggalkan name properti, nama modul unik akan dibuat secara otomatis.

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

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

Tidak memberikan nama modul apa pun juga valid. GUID akan dihasilkan sebagai nama modul.

module stgModule 'storageAccount.bicep' = {
  scope: resourceGroup('demoRG')
}

Jika Anda perlu menentukan cakupan yang berbeda dari 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 if ekspresi. Ini mirip dengan penyebaran 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 menerapkan lebih dari satu instans modul, tambahkan for pernyataan. Gunakan dekorator batchSize untuk menentukan apakah instans disebarkan secara serial atau paralel. Untuk informasi selengkapnya, lihat Perulangan berulang di Bicep.

// 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 ditentukan secara implisit. Jika Anda perlu mengatur dependensi eksplisit, tambahkan dependsOn ke definisi modul. Untuk mempelajari selengkapnya tentang dependensi, lihat Dependensi sumber daya di Bicep.

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 berada dalam spesifikasi template atau sebuah registri modul Bicep.

File lokal

Jika modul adalah file lokal, berikan jalur relatif ke file tersebut. Semua jalur di Bicep harus ditentukan oleh pemisah direktori garis miring (/) untuk memastikan kompilasi yang konsisten di seluruh platform. 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'
  }
}

Berkas pada registri

Ada registri modul publik dan privat.

Registri modul publik

Catatan

Modul Terverifikasi Non-Azure dihentikan dari registri modul publik.

Modul Terverifikasi Azure adalah modul bawaan, yang telah dibuktikan, dan diverifikasi sebelumnya yang dapat Anda gunakan untuk menyebarkan sumber daya di Azure. Karyawan Microsoft membuat dan memiliki modul ini. Mereka dirancang untuk menyederhanakan dan mempercepat proses penyebaran untuk sumber daya dan konfigurasi Azure umum. Modul juga selaras dengan praktik terbaik seperti Azure Well-Architected Framework.

Telusuri Modul Bicep untuk melihat daftar modul yang tersedia. Pilih angka yang disorot dalam cuplikan layar berikut untuk langsung masuk ke tampilan yang difilter:

Cuplikan layar yang memperlihatkan Modul Terverifikasi Azure.

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

Cuplikan layar yang memperlihatkan versi Modul Terverifikasi Azure.

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

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

br/publik: Ini adalah alias untuk modul publik. Anda dapat menyesuaikan alias ini dalam file konfigurasi Bicep.
jalur file: Ini dapat berisi segmen yang dapat Anda pisahkan dengan / karakter.
tag: Ini digunakan untuk menentukan versi untuk modul.

Contoh:

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

Catatan

Alias untuk modul publik br/public. Anda juga dapat menulisnya sebagai:

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

Registri Modulo Pribadi

Jika Anda 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: Ini adalah nama skema untuk registri Bicep.
jalur file: Ini dipanggil repository di Azure Container Registry. Jalur file dapat berisi segmen yang dipisahkan oleh karakter /.
tag: Digunakan untuk menentukan versi untuk modul.

Contoh:

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 bicep restore untuk menyalin modul eksternal ke cache lokal. Dibutuhkan beberapa saat untuk memulihkan modul eksternal. Jika IntelliSense untuk modul tidak segera berfungsi, tunggu hingga pemulihan selesai.

Path lengkap untuk modul dalam registri bisa panjang. Alih-alih menyediakan jalur lengkap setiap kali Anda ingin menggunakan modul, konfigurasikan alias dalam file bicepconfig.json. Penggunaan alias memudahkan kita untuk merujuk modul. Misalnya, dengan alias, Anda dapat mempersingkat jalur ke:

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

Registri modul publik memiliki alias yang telah ditentukan sebelumnya:

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

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

Berkas pada spesifikasi template

Setelah Anda membuat spesifikasi templat , tautkan spesifikasi templat tersebut pada modul. Tentukan spesifikasi templat dalam format berikut:

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

Untuk menyederhanakan file Bicep Anda, buat 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. Grup langganan dan 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 ini memperlihatkan dekorator yang tersedia untuk modul:

Dekorator	Argumen	Deskripsi
batchSize	tidak ada	Mengatur instans untuk disebarkan secara berurutan.
deskripsi	benang	Berikan deskripsi untuk modul.

Dekorator berada di namespace sys. Jika Anda perlu membedakan suatu dekorator dari item lainnya dengan nama yang sama, awali dekorator dengan sys. Misalnya, jika file Bicep Anda menyertakan parameter bernama description, Anda harus menambahkan namespace sys saat menggunakan dekorator description.

Ukuran Batch

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 mendistribusikan 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. Contoh:

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

Anda dapat menggunakan teks berformat Markdown 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, jadi Anda tidak perlu memberikan 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

Menetapkan cakupan modul

Saat Anda mendeklarasikan modul, atur cakupan untuk modul yang berbeda dari cakupan untuk file Bicep yang berisinya. Gunakan properti scope untuk mengatur ruang lingkup modul. Saat properti scope tidak disediakan, modul disebarkan pada 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 memiliki ruang lingkup dalam 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 scope 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)
}

Keluaran

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 mengembalikan 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

Saat properti digunakan sebagai modul, Anda bisa mendapatkan nilai output 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

Dengan Bicep versi 0.35.1 dan yang lebih baru, penanda @secure() dapat diterapkan ke output modul untuk menandainya sebagai sensitif, mengamankan bahwa nilainya tidak terekspos dalam log atau riwayat penyebaran. Ini berguna ketika modul perlu mengembalikan data sensitif, seperti kunci yang dihasilkan atau string koneksi, ke file Bicep induk tanpa risiko paparan. Untuk informasi selengkapnya, lihat Output aman.

Untuk tutorial, lihat Membangun file Bicep pertama Anda.
Untuk meneruskan nilai sensitif ke modul, gunakan fungsi getSecret.