Bicep modülleri

Bicep ile dağıtımları modüller halinde düzenleyebilirsiniz. Bir modül, başka bir Bicep dosyasının dağıttığı bir Bicep dosyasıdır. Modül, JSON için bir Azure Resource Manager şablonu (ARM şablonu) da olabilir. Modülleri kullanarak, dağıtımınızın karmaşık ayrıntılarını kapsülleyerek Bicep dosyalarınızın okunabilirliğini geliştirirsiniz. Ayrıca farklı dağıtımlar için modülleri kolayca yeniden kullanabilirsiniz.

Modülleri kuruluşunuzdaki diğer kişilerle paylaşmak için şablon tanımı oluşturun veya özel kayıt defteri. Kayıt defterindeki şablon belirtimleri ve modülleri yalnızca doğru izinlere sahip kullanıcılar tarafından kullanılabilir.

Tip

Modül kayıt defteri ve şablon özellikleri arasındaki seçim çoğunlukla tercih konusudur. İki seçenek arasında seçim yaparken aşağıdaki noktaları göz önünde bulundurun:

  • Modül kayıt defterini yalnızca Bicep destekler. Bicep kullanmıyorsanız şablon belirtimlerini kullanın.
  • Bicep modülü kayıt defterindeki içeriği yalnızca başka bir Bicep dosyasından dağıtabilirsiniz. Şablon belirtimlerini doğrudan API, Azure PowerShell, Azure CLI ve Azure portalından dağıtabilirsiniz. Portal dağıtım deneyimini özelleştirmek için bile kullanabilirsiniz UiFormDefinition .
  • Bicep, loadTextContent ve loadFileAsBase64 işlevlerini kullanarak diğer proje yapıtlarını (Bicep olmayan ve PowerShell betikleri, CLI betikleri ve diğer ikili dosyalar gibi ARM şablonu olmayan dosyalar dahil) eklemek için bazı sınırlı özelliklere sahiptir. Şablon özellikleri bu yapıtları paketleyemez.

Bicep modülleri, iç içe şablonlarıyla birlikte tek bir ARM şablonunadönüştürülür. Bicep'in yapılandırma dosyalarını nasıl çözümlediğini ve Bicep'in kullanıcı tanımlı bir yapılandırma dosyasını varsayılan yapılandırma dosyasıyla birleştirmesi hakkında daha fazla bilgi için bkz. Yapılandırma dosyası çözümleme işlemi ve Yapılandırma dosyası birleştirme işlemi.

Modülleri tanımlama

Modül tanımlamaya yönelik temel söz dizimi:

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

Basit bir gerçek dünya örneği şöyle görünür:

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

Modül olarak JSON için ARM şablonu da kullanabilirsiniz:

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

Bicep dosyasının başka bir bölümündeki modüle başvurmak için sembolik adı kullanın. Örneğin, bir modülden çıktı almak için sembolik adı kullanabilirsiniz. Sembolik ad a-z, A-Z, 0-9 ve alt çizgi (_) içerebilir. Ad bir sayı ile başlayamaz. Bir modülün adı parametre, değişken veya kaynakla aynı olamaz.

Yol yerel bir dosya veya kayıt defterindeki bir dosya olabilir. Yerel dosya bir Bicep dosyası veya JSON için ARM şablonu olabilir. Daha fazla bilgi için Bir modül yoluna bkz.

name özelliği isteğe bağlıdır. Oluşturulan şablonda iç içe geçmiş dağıtım kaynağının adı haline gelir. Ad sağlanmamışsa, iç içe dağıtım kaynağının adı olarak bir GUID oluşturulur.

Statik ada sahip bir modülü aynı kapsama eş zamanlı olarak dağıtırsanız, bir dağıtım diğer dağıtımdan gelen çıkışı etkileyebilir. Örneğin, iki Bicep dosyası aynı statik ada (examplemodule) sahip aynı modülü kullanıyorsa ve aynı kaynak grubuna hedefleniyorsa, bir dağıtım yanlış çıkış gösterebilir. Aynı kapsama eş zamanlı dağıtımlar hakkında endişeleriniz varsa modülünüze benzersiz bir ad verin. Benzersiz modül adları sağlamanın bir başka yolu, name özelliğini boş bırakmaktır; bu durumda benzersiz bir modül adı otomatik olarak oluşturulur. no-module-name linter kuralı, hâlâ açık bir name özelliği içeren modülleri işaretleyerek bu daha temiz kodlama uygulamasını benimsetmek için tasarlanmıştır.

Aşağıdaki örnek, dağıtım adını modül adıyla birleştirir. Dağıtım için benzersiz bir ad sağlarsanız modül adı da benzersizdir.

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

Modül adı verilmemesi de geçerlidir. Modül adı olarak bir GUID oluşturulur.

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

Ana dosyanın kapsamından farklı bir kapsam belirtmeniz gerekiyorsa kapsam özelliğini ekleyin. Daha fazla bilgi için bkz . Modül kapsamını ayarlama.

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

Bir modülü koşullu olarak dağıtmak için bir if ifade ekleyin. Bu, bir kaynağı koşullu olarak dağıtmaya benzer.

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

Bir modülün birden fazla örneğini dağıtmak için ifadesini ekleyin. Örneklerin seri olarak mı yoksa paralel olarak mı dağıtılacağını belirtmek için batchSize dekoratörü kullanın. Daha fazla bilgi için Bicep'te Yinelemeli Döngüler bölümüne bakın.

// 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>
  }
}]

Kaynaklar gibi modüller de diğer modüllere veya kaynaklara bağımlı olmadığı sürece paralel olarak dağıtılır. Genellikle, bağımlılıkları örtük olarak belirlendikleri için ayarlamanız gerekmez. Açık bir bağımlılık ayarlamanız gerekiyorsa modül tanımına dependsOn ekleyin. Bağımlılıklar hakkında daha fazla bilgi edinmek için bkz. Bicepkaynak bağımlılıkları.

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

Modüle giden yol

Modül için yerel dosya veya dış dosya kullanabilirsiniz. Dış dosyayı bir şablon belirtiminde veya Bicep modül kayıt defterinde bulabilirsiniz.

Yerel dosya

Modül yerel bir dosyaysa, bu dosyanın göreli yolunu belirtin. Bicep'da, platformlar arasında tutarlı bir derleme sağlamak için tüm yollar için eğik çizgi (/) dizin ayırıcısını kullanmanız gerekir. Windows ters eğik çizgi (\) karakteri desteklenmiyor. Yollar boşluk içerebilir.

Dizinde bir düzey yukarı olan bir dosyayı ana dosyanızdan dağıtmak için aşağıdaki örneği kullanın:

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

Kayıt defterindeki dosya

Genel ve özel modül kayıt defterleri vardır.

Genel modül kayıt defteri

Note

Azure Dışı Doğrulanmış Modüller, genel modül kayıt defterinden kullanımdan kaldırılır.

Azure Doğrulanmış Modülleri, Azure'da kaynakları dağıtmak için kullanabileceğiniz önceden oluşturulmuş, önceden test edilmiş ve önceden doğrulanmış modüllerdir. Microsoft çalışanları bu modülleri oluşturup bu modüllerin sahibidir. Yaygın Azure kaynakları ve yapılandırmaları için dağıtım sürecini basitleştirir ve hızlandırır. Modüller, Azure Well-Architected Framework gibi en iyi yöntemlerle de uyumludur.

Kullanılabilir modüllerin listesini görmek için Bicep Modules seçeneğine göz atın. Aşağıdaki ekran görüntüsünde vurgulanan sayıları seçerek doğrudan filtrelenmiş görünüme gidin:

Azure Doğrulanmış Modülleri gösteren ekran görüntüsü.

Modül listesinde en son sürüm gösterilir. Kullanılabilir sürümlerin listesini görmek için sürüm numarasını seçin.

Azure Doğrulanmış Modül sürümlerini gösteren ekran görüntüsü.

Genel bir modüle bağlanmak için modül yolunu aşağıdaki söz dizimiyle belirtin:

module <symbolic-name> 'br/public:<file-path>:<tag>' = {}
  • br/public: Bu, genel modüllerin diğer adıdır. Bu diğer adı Bicep yapılandırma dosyasında özelleştirebilirsiniz.
  • dosya yolu: Bu, karakterle / ayırdığınız kesimleri içerebilir.
  • etiketi: Modül için bir sürüm belirtir.

Örneğin:

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

Note

Ortak modüller için takma ad br/public'dır. Bunu şu şekilde de yazabilirsiniz:

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

Özel modül kayıt defteri

Bir modülü kayıt merkezi 'eyayımladıysanız, bu modüle bağlanabilirsiniz. Azure kapsayıcı kayıt defterinin adını ve modülün yolunu belirtin. Modül yolunu aşağıdaki söz dizimiyle belirtin:

module <symbolic-name> 'br:<registry-name>.azurecr.io/<file-path>:<tag>' = {
  • br: Bu, Bicep kayıt defteri için bir şema adıdır.
  • dosya yolu: Bu, Azure Container Registry'de repository olarak adlandırılır. Dosya yolu, / karakteriyle ayrılmış kesimler içerebilir.
  • etiketi: Modül için bir sürüm belirtir.

Örneğin:

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

Kayıt defterindeki bir modüle başvurdığınızda, Visual Studio Code'daki Bicep uzantısı dış modülü yerel önbelleğe kopyalamak için otomatik olarak bicep restore çağırır. Dış modülü geri yüklemek birkaç dakika sürer. Modül için IntelliSense hemen çalışmazsa geri yükleme işleminin tamamlanmasını bekleyin.

Kayıt defterindeki bir modülün tam yolu uzun olabilir. Modülü kullanmak istediğinizde her seferinde tam yolu sağlamak yerine, bicepconfig.json dosyasında takma adlar yapılandırın. Takma adlar modüle başvurmayı kolaylaştırır. Örneğin, diğer adla yolu şu şekilde kısaltabilirsiniz:

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

Ortak modül kayıt defterinin önceden tanımlanmış bir diğer adı vardır:

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

bicepconfig.json dosyasındaki genel takma adı geçersiz kılabilirsiniz.

Bicep CLI v0.43.1'den başlayarak, Bicep bir Azure Container Registry (ACR) modülüne başvururken veya geri yüklerken özel etki alanlarının kullanımını açıkça engeller. Bu koruma, aksi takdirde uyumluluk sorunlarına neden olacak desteklenmeyen yapılandırmaların kullanılmasını önler.

gibi moduleStore.myCompany.comözel bir etki alanına başvurmaya çalışırsanız, Bicep CLI bcP446 tanılama hatası döndürür. Örneğin:

module foo 'br:moduleStore.myCompany.com/networking/hub:1.0.0' = { ... }

Bicep, tüm kayıt defteri ana bilgisayar adlarını yerleşik izin verilenler listesine göre doğrular. Şu anda yalnızca aşağıdaki etki alanlarına izin verilir:

  • *.azurecr.io
  • *.azurecr.cn
  • *.azurecr.us
  • mcr.microsoft.com
  • mcr.azure.cn
  • ghcr.io

Kuruluşunuz özel etki alanları kullanıyorsa, Bicep dosyalarınızı şu kısıtlamalara uyacak şekilde güncelleştirin:

  • Yerel ana bilgisayar adlarına geri dön: Yerel .azurecr.io (veya ilgili buluta özgü) etki alanını kullanmak için tüm Bicep modül başvurularını güncelleştirin.
  • Yerel önbelleği temizle: Başvurularınızı güncelleştirdikten sonra yerel modül önbelleğinizi temizlemeniz gerekebilir. Modülleri düzeltilmiş yerel ana bilgisayar adlarını kullanarak çekmek için bicep restore komutunu yeniden çalıştırın.

Şablon belirtimindeki dosya

birşablonu belirtimi oluşturduktan sonra modüldeki bu şablon belirtimine bağlanabilirsiniz. Şablon belirtimini aşağıdaki biçimde belirtin:

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

Bicep dosyanızı basitleştirmek için şablon belirtimlerinizi içeren kaynak grubu için bir diğer ad oluşturun. Diğer ad kullandığınızda söz dizimi şöyle olur:

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

Aşağıdaki modülde depolama hesabı oluşturmak için bir şablon belirtimi dağıtılır. Şablon özelliğinin aboneliği ve kaynak grubu, ContosoSpecs adlı diğer adda tanımlanır.

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

Dekoratörleri kullanma

Dekoratörleri @expression formatında yazın ve modül bildirimlerinin üzerine yerleştirin. Aşağıdaki tabloda modüller için kullanılabilir dekoratörler gösterilmektedir:

Decorator Argument Description
batchSize none Örnekleri sıralı olarak dağıtılacak şekilde ayarlayın.
description string Modül için açıklamalar sağlayın.

Dekoratörler sys ad alanı içindedir. Bir dekoratörü aynı ada sahip başka bir ögeden ayırt etmeniz gerekiyorsa, dekoratörün önüne sys ekleyin. Örneğin, Bicep dosyanız descriptionadlı bir parametre içeriyorsa, sys dekoratörü kullanırken description ad alanını eklemeniz gerekir.

BatchSize

@batchSize() yalnızca for ifadesi kullanan bir kaynak veya modül tanımına uygulayabilirsiniz.

Varsayılan olarak, dağıtım altyapısı modülleri paralel olarak dağıtır. @batchSize(int) dekoratörünü eklediğinizde, örnekleri seri olarak dağıtırsınız.

@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}'
  }
}]

Daha fazla bilgi için Toplu Olarak Dağıtma başlığına bakın.

Description

Açıklama eklemek için modül bildirimlerine bir açıklama ekleyin. Örneğin:

@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}'
  }
}

Açıklama metni için Markdown biçimli metin kullanabilirsiniz.

Parameters

Modül tanımınızda sağladığınız parametreler, Bicep dosyasındaki parametrelerle eşleşmektedir.

Aşağıdaki Bicep örneğinde üç parametre vardır: storagePrefix, storageSKUve location. storageSKU parametresi varsayılan bir değere sahiptir, bu nedenle dağıtım sırasında bu parametre için bir değer sağlamanız gerekmez.

@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@2025-06-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

output storageEndpoint object = stg.properties.primaryEndpoints

Önceki örneği modül olarak kullanmak için bu parametreler için değerler sağlayın.

targetScope = 'subscription'

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

resource demoRG 'Microsoft.Resources/resourceGroups@2025-04-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

Modül kapsamını ayarlama

Bir modülü bildirdiğinizde, modülü içeren Bicep dosyasının kapsamından farklı bir modül kapsamı ayarlayın. modülünün scope kapsamını ayarlamak için özelliğini kullanın. scope özelliğini belirtmediğinizde modül, üst öğenin hedef kapsamına dağıtılır.

Aşağıdaki Bicep dosyası, bu kaynak grubunda bir kaynak grubu ve bir depolama hesabı oluşturur. Dosya bir aboneliğe dağıtılır, ancak modülün kapsamı yeni kaynak grubuna göre belirlenmiştir.

// 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@2025-04-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

Sonraki örnek, depolama hesaplarını iki farklı kaynak grubuna dağıtır. Bu kaynak gruplarının her ikisi de zaten mevcut olmalıdır.

targetScope = 'subscription'

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

resource secondRG 'Microsoft.Resources/resourceGroups@2025-04-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'
  }
}

scope özelliğini geçerli bir kapsam nesnesine ayarlayın. Bicep dosyanız bir kaynak grubu, abonelik veya yönetim grubu dağıtıyorsa, modülün kapsamını bu kaynağın sembolik adı olarak ayarlayın. Veya geçerli bir kapsam elde etmek için kapsam işlevlerini kullanın.

Bu işlevler şunlardır:

Aşağıdaki örnekte kapsamı ayarlamak için işlevi kullanılmaktadır managementGroup .

param managementGroupName string

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

Output

Bir modülden değerler alabilir ve bunları ana Bicep dosyasında kullanabilirsiniz. Bir modülden çıkış değeri almak için modül nesnesinde özelliğini kullanın outputs .

İlk örnek bir depolama hesabı oluşturur ve birincil uç noktaları döndürür:

@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@2025-06-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

output storageEndpoint object = stg.properties.primaryEndpoints

özelliğini modül olarak kullandığınızda bu çıkış değerini alabilirsiniz:

targetScope = 'subscription'

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

resource demoRG 'Microsoft.Resources/resourceGroups@2025-04-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

Bicep'in 0.35.1 veya daha sonraki bir sürümünü kullanarak, modül çıkışlarını hassas olarak işaretlemek için @secure() dekoratörünü uygulayabilir ve böylece değerlerinin günlüklerde veya dağıtım geçmişinde açığa çıkmamasını sağlayabilirsiniz. Bu yaklaşım, bir modülün oluşturulmuş bir anahtar veya bağlantı dizesi gibi hassas verileri, açığa çıkma riski oluşturmadan ana Bicep dosyasına döndürmesi gerektiğinde kullanışlıdır. Daha fazla bilgi için bkz . Güvenli çıkışlar.

Modül kimliği

Bicep sürüm 0.36.1'den başlayarak modüle kullanıcı tarafından atanan bir yönetilen kimlik atayabilirsiniz. Bu kimlik modül içinde mevcuttur; örneğin bir Key Vault’a erişmek için kullanılabilir. Ancak arka uç hizmetleri henüz bu özelliği desteklemez.

param identityId string

module mod './module.bicep' = {
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '${identityId}': {}
    }
  }
  name: 'mod'
  params: {
    keyVaultUri: 'keyVaultUri'
    identityId: identityId
  }
}

İlgili içerik

  • Bir modüle hassas bir değer geçirmek için getSecret işlevini kullanın.
  • Last updated on