Bicep modülleri

Bicep, dağıtımları modüller halinde düzenlemenizi sağlar. Modül, başka bir Bicep dosyasından dağıtılan bir Bicep dosyasıdır (veya ARM JSON şablonudur). Modüllerle, 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 bir şablon belirtimi, genel kayıt defteri veya özel kayıt defteri oluşturun. Kayıt defterindeki şablon belirtimleri ve modülleri yalnızca doğru izinlere sahip kullanıcılar tarafından kullanılabilir.

İpucu

Modül kayıt defteri ve şablon özellikleri arasındaki seçim çoğunlukla tercih konusudur. İkisi arasında seçim yaparken göz önünde bulundurmanız gereken birkaç şey vardır:

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

Bicep modülleri, iç içe şablonlar içeren tek bir Azure Resource Manager şablonuna dönüştürülür. Bicep'in yapılandırma dosyalarını nasıl çözümlediğini ve Bicep'in kullanıcı tanımlı 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.

Eğitim kaynakları

Adım adım yönergeler aracılığıyla modüller hakkında bilgi edinmek isterseniz bkz . Modülleri kullanarak oluşturulabilir Bicep dosyaları oluşturma.

Tanım söz dizimi

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

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

Bu nedenle, basit, gerçek dünya örneği şöyle görünür:

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

Arm JSON şablonunu modül olarak 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 ARM JSON şablonu olabilir. Daha fazla bilgi için bkz . Modülün yolu.

Name özelliği gereklidir. Oluşturulan şablonda iç içe dağıtım kaynağının adı olur.

Statik ada sahip bir modül aynı kapsama eş zamanlı olarak dağıtılırsa, bir dağıtımın diğer dağıtımın çıktısını engelleme olasılığı vardır. Örneğin, iki Bicep dosyası aynı statik adla (examplemodule) aynı modülü kullanıyorsa ve aynı kaynak grubunu hedeflediyse, 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.

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

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. Kullanım, 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 ekleyinfor. Örneklerin batchSize seri olarak mı yoksa paralel olarak mı dağıtılacağını belirtmek için dekoratör kullanabilirsiniz. Daha fazla bilgi için bkz . Bicep'te yinelemeli döngüler.

// 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 ekleyebilirsiniz dependsOn . Bağımlılıklar hakkında daha fazla bilgi edinmek için bkz . Kaynak 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ülün yolu

Modülün dosyası yerel bir dosya veya dış dosya olabilir. Dış dosya şablon belirtiminde veya Bicep modülü kayıt defterinde olabilir. Bu seçeneklerin tümü aşağıda gösterilmiştir.

Yerel dosya

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

Örneğin, ana dosyanızdan dizinde bir düzeyde olan bir dosyayı dağıtmak için şunu kullanın:

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

Kayıt defterindeki dosya

Genel modül kayıt defteri

Ortak modül kayıt defteri bir Microsoft kapsayıcı kayıt defterinde (MCR) barındırılır. Kaynak kodu ve modüller GitHub'da depolanır. Kullanılabilir modülleri ve bunların sürümlerini görüntülemek için bkz . Bicep kayıt defteri Modül Dizini.

Kullanılabilir sürümleri görmek için sürümleri seçin. Ayrıca Kaynak kodu'nu seçerek modül kaynak kodunu görebilir ve Benioku dosyalarını açabilirsiniz.

Şu anda yalnızca birkaç yayımlanmış modül vardır. Daha fazla modül geliyor. Kayıt defterine katkıda bulunmak istiyorsanız katkıda bulunma kılavuzuna bakın.

Genel kayıt defteri modülüne bağlanmak için modül yolunu aşağıdaki söz dizimiyle belirtin:

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

• br/public , ortak modül kayıt defterinin diğer adıdır. Bu diğer ad, yapılandırmanızda önceden tanımlanmıştır.
• dosya yolu , karakterle / ayrılabilen kesimler içerebilir.
• etiketi , modül için bir sürüm belirtmek için kullanılır.

Örneğin:

module hw 'br/public:samples/hello-world:1.0.2' = {
  name: 'helloWorld'
  params: {
    name: 'John Dole'
  }
}

Not

br/public , genel kayıt defterinin diğer adıdır. Ayrıca şu şekilde yazılabilir:

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

Özel modül kayıt defteri

Bir modülü bir kayıt defterinde yayı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 , bicep kayıt defterinin şema adıdır.
• dosya yolu Azure Container Registry'de çağrılır repository . Dosya yolu, karakterle / ayrılmış segmentler içerebilir.
• etiketi , modül için bir sürüm belirtmek için kullanılır.

Ö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 geri yüklemesini ç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ü her kullanmak istediğinizde tam yolu sağlamak yerine, bicepconfig.json dosyasında diğer adları yapılandırabilirsiniz. Diğer 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'
  }
}

Genel modül kayıt defteri için bir diğer ad önceden tanımlanmış:

module hw 'br/public:samples/hello-world:1.0.2' = {
  name: 'helloWorld'
  params: {
    name: 'John Dole'
  }
}

bicepconfig.json dosyasındaki ortak diğer adı geçersiz kılabilirsiniz.

Şablondaki dosya belirtimi

Şablon belirtimi oluşturduktan sonra modülde 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>' = {

Ancak, şablon belirtimlerinizi içeren kaynak grubu için bir diğer ad oluşturarak Bicep dosyanızı basitleştirebilirsiniz. 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 belirtimi için abonelik ve kaynak grubu ContosoSpecs adlı diğer adda tanımlanır.

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

Parametreler

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, storageSKU ve 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@2021-04-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@2021-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ü bildirirken, modül için, içeren Bicep dosyasının kapsamından farklı bir kapsam ayarlayabilirsiniz. modülünün scope kapsamını ayarlamak için özelliğini kullanın. Kapsam özelliği sağlanmayan modül üst öğesinin hedef kapsamında 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@2021-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@2021-04-01' existing = {
  name: 'demogroup1'
}

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

Kapsam özelliğini geçerli bir kapsam nesnesi olarak 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ına ayarlayabilirsiniz. Veya geçerli bir kapsam elde etmek için kapsam işlevlerini kullanabilirsiniz.

Bu işlevler şunlardır:

• resourceGroup
• aboneliği
• managementGroup
• tenant

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)
}

Çıktı

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

output storageEndpoint object = stg.properties.primaryEndpoints

Modül olarak kullanıldığında bu çıkış değerini alabilirsiniz.

targetScope = 'subscription'

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

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

Sonraki adımlar

• Öğretici için bkz . Bicep şablonlarını kullanarak Azure kaynaklarını dağıtma.
• Bir modüle hassas bir değer geçirmek için getSecret işlevini kullanın.