Bicep-modulok

A Bicep lehetővé teszi az üzembe helyezés modulokba rendezését. A modul egy másik Bicep-fájlból üzembe helyezett Bicep-fájl (vagy ARM JSON-sablon). A modulokkal az üzembe helyezés összetett részleteinek beágyazásával javíthatja a Bicep-fájlok olvashatóságát. A modulok könnyen újra felhasználhatók a különböző üzemelő példányokhoz.

Ha modulokat szeretne megosztani a szervezet más tagjaival, hozzon létre egy sablon-specifikációt, egy nyilvános beállításjegyzéket vagy egy privát beállításjegyzéket. A beállításjegyzék sablonelemei és moduljai csak a megfelelő engedélyekkel rendelkező felhasználók számára érhetők el.

Tipp.

A modulregisztrációs adatbázis és a sablon specifikációi közötti választás többnyire preferencia kérdése. Ha a kettő közül választ, érdemes megfontolni néhány dolgot:

• A modulregisztrációs adatbázist csak a Bicep támogatja. Ha még nem használja a Bicep-et, használja a sablon specifikációit.
• A Bicep-modul beállításjegyzékében lévő tartalom csak egy másik Bicep-fájlból telepíthető. A sablon specifikációi közvetlenül az API-ból, az Azure PowerShellből, az Azure CLI-ből és az Azure Portalról telepíthetők. A portál üzembehelyezési felületének testreszabására is használható UiFormDefinition .
• A Bicep bizonyos korlátozott képességekkel rendelkezik más projektösszetevők beágyazásához (beleértve a nem Bicep- és nem ARM-sablonfájlokat is). Például PowerShell-szkriptek, PARANCSSOR-szkriptek és egyéb bináris fájlok) a függvények és loadFileAsBase64 a loadTextContent függvények használatával. A sablon specifikációi nem tudják csomagolni ezeket az összetevőket.

A Bicep-modulok egyetlen, beágyazott sablonokkal rendelkező Azure Resource Manager-sablonlá alakulnak. További információ arról, hogy a Bicep hogyan oldja fel a konfigurációs fájlokat, és hogy a Bicep hogyan egyesítheti a felhasználó által definiált konfigurációs fájlt az alapértelmezett konfigurációs fájllal, tekintse meg a konfigurációs fájlfeloldási folyamatot és a konfigurációs fájlegyesítési folyamatot.

Képzési erőforrások

Ha lépésről lépésre szeretne többet megtudni a modulokról, olvassa el a Összeállítható Bicep-fájlok modulok használatával történő létrehozását ismertető témakört.

Definíció szintaxisa

A modul meghatározásának alapszintaxisa a következő:

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

Tehát egy egyszerű, valós példa a következőképpen nézne ki:

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

ARM JSON-sablont is használhat modulként:

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

A szimbolikus névvel hivatkozhat a modulra a Bicep-fájl egy másik részében. A szimbolikus névvel például lekérheti a kimenetet egy modulból. A szimbolikus név tartalmazhat a-z, A-Z, 0-9 és aláhúzásjelet (_). A név nem kezdődhet számmal. Egy modul neve nem lehet ugyanaz, mint egy paraméter, változó vagy erőforrás.

Az elérési út lehet helyi fájl vagy egy beállításjegyzékbeli fájl. A helyi fájl lehet Bicep-fájl vagy ARM JSON-sablon. További információ: Elérési út modul.

A névtulajdonság megadása kötelező. Ez lesz a beágyazott üzembehelyezési erőforrás neve a létrehozott sablonban.

Ha egy statikus nevű modul egyidejűleg ugyanarra a hatókörre van üzembe helyezve, lehetséges, hogy az egyik üzembe helyezés zavarja a másik üzembe helyezés kimenetét. Ha például két Bicep-fájl ugyanazt a modult használja ugyanazzal a statikus névvel (examplemodule) és ugyanarra az erőforráscsoportra van megcélzva, előfordulhat, hogy az egyik üzembe helyezés nem a megfelelő kimenetet jeleníti meg. Ha az azonos hatókörbe tartozó egyidejű üzembe helyezések miatt aggódik, adjon egyedi nevet a modulnak.

Az alábbi példa összefűzi az üzembe helyezés nevét a modul nevével. Ha egyedi nevet ad meg az üzembe helyezéshez, a modul neve is egyedi.

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

Ha olyan hatókört kell megadnia, amely eltér a fő fájl hatókörétől, adja hozzá a hatókör tulajdonságot. További információ: Modul hatókörének beállítása.

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

Egy modul feltételes üzembe helyezéséhez adjon hozzá egy if kifejezést. A használat hasonlít egy erőforrás feltételes üzembe helyezéséhez.

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

A modul több példányának üzembe helyezéséhez adja hozzá a for kifejezést. A dekoratőr használatával batchSize megadhatja, hogy a példányok sorosan vagy párhuzamosan vannak-e üzembe helyezve. További információ: Iteratív hurkok a Bicepben.

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

Az erőforrásokhoz hasonlóan a modulok párhuzamosan vannak üzembe helyezve, kivéve, ha más moduloktól vagy erőforrásoktól függenek. Általában nem kell függőségeket beállítania, mivel implicit módon vannak meghatározva. Ha explicit függőséget kell beállítania, hozzáadhatja dependsOn a moduldefinícióhoz. A függőségekkel kapcsolatos további információkért tekintse meg az erőforrás-függőségeket.

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

A modul elérési útja

A modul fájlja lehet helyi vagy külső fájl. A külső fájl lehet sablon specifikációban vagy Bicep-modulregisztrációs adatbázisban. Ezek a lehetőségek az alábbiakban láthatók.

Helyi fájl

Ha a modul helyi fájl, adja meg a fájl relatív elérési útját. A Bicep összes elérési útját a perjel (/) könyvtárelválasztóval kell megadni a platformok közötti egységes fordítás biztosításához. A Windows fordított perjel (\) karaktere nem támogatott. Az elérési utak szóközöket tartalmazhatnak.

Ha például egy olyan fájlt szeretne üzembe helyezni, amely egy szinttel feljebb van a címtárban a fő fájlból, használja a következőt:

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

Fájl a beállításjegyzékben

Nyilvános modulregisztrációs adatbázis

A nyilvános modulregisztrációs adatbázis egy Microsoft-tárolóregisztrációs adatbázisban (MCR) található. A forráskódot és a modulokat a GitHub tárolja. Az elérhető modulok és azok verzióinak megtekintéséhez tekintse meg a Bicep beállításjegyzék modulindexét.

Válassza ki a verziókat az elérhető verziók megtekintéséhez. A forráskód kiválasztásával megtekintheti a modul forráskódját, és megnyithatja a Readme-fájlokat.

Jelenleg csak néhány közzétett modul van közzétéve. További modulok jönnek. Ha szeretne hozzájárulni a beállításjegyzékhez, tekintse meg a hozzájárulási útmutatót.

Nyilvános beállításjegyzék-modulra mutató hivatkozáshoz adja meg a modul elérési útját az alábbi szintaxissal:

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

• a br/public a nyilvános modulregisztrációs adatbázis aliasa. Ez az alias előre definiálva van a konfigurációban.
• a fájl elérési útja olyan szegmenseket tartalmazhat, amelyeket a karakter elválaszthat egymástól / .
• A modul egy verziójának megadásához címke szolgál.

Például:

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

Feljegyzés

a br/public a nyilvános beállításjegyzék aliasa. Megírható úgy is, mint

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

Privát modulregisztrációs adatbázis

Ha közzétett egy modult egy beállításjegyzékben, hivatkozhat erre a modulra. Adja meg az Azure Container Registry nevét és a modul elérési útját. Adja meg a modul elérési útját a következő szintaxissal:

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

• a br egy Bicep-beállításjegyzék sémaneve.
• a fájl elérési útját az Azure Container Registry hívja meg repository . A fájl elérési útja tartalmazhat olyan szegmenseket, amelyeket a karakter elválaszt./
• A modul egy verziójának megadásához címke szolgál.

Példa:

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

Amikor egy beállításjegyzék egy moduljára hivatkozik, a Visual Studio Code Bicep-bővítménye automatikusan meghívja a Bicep-visszaállítást , hogy a külső modult a helyi gyorsítótárba másolja. A külső modul visszaállítása néhány percet vesz igénybe. Ha a modul intellisense nem működik azonnal, várja meg a visszaállítás befejezését.

Egy beállításjegyzék moduljának teljes elérési útja hosszú lehet. Ahelyett, hogy minden alkalommal megadja a teljes elérési utat, amikor használni szeretné a modult, konfigurálhatja az aliasokat a bicepconfig.json fájlban. Az aliasok megkönnyítik a modulra való hivatkozást. Egy aliassal például lerövidítheti a következő elérési utat:

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

A nyilvános modulregisztrációs adatbázis aliasa előre definiálva van:

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

A nyilvános alias felülbírálható a bicepconfig.json fájlban.

Fájl sablon specifikációban

A sablon specifikációinak létrehozása után egy modulban hivatkozhat erre a sablon-specifikációra. Adja meg a sablon specifikációt a következő formátumban:

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

Egyszerűsítheti azonban a Bicep-fájlt úgy, hogy létrehoz egy aliast a sablon specifikációit tartalmazó erőforráscsoporthoz. Alias használata esetén a szintaxis a következő lesz:

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

Az alábbi modul üzembe helyez egy sablon-specifikációt egy tárfiók létrehozásához. A sablon specifikációjának előfizetése és erőforráscsoportja a ContosoSpecs aliasban van definiálva.

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

Paraméterek

A moduldefinícióban megadott paraméterek megegyeznek a Bicep-fájl paramétereivel.

Az alábbi Bicep-példában három paraméter található: storagePrefix, storageSKU és location. A StorageSKU paraméter alapértelmezett értékkel rendelkezik, így az üzembe helyezés során nem kell megadnia az adott paraméter értékét.

@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

Az előző példa modulként való használatához adjon meg értékeket ezekhez a paraméterekhez.

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

Modul hatókörének beállítása

Modul deklarálásakor a modul hatóköre eltérhet a bicep-fájl hatókörétől. scope A tulajdonság használatával állítsa be a modul hatókörét. Ha a hatókör tulajdonság nincs megadva, a modul a szülő célhatókörében lesz üzembe helyezve.

Az alábbi Bicep-fájl létrehoz egy erőforráscsoportot és egy tárfiókot az adott erőforráscsoportban. A fájl egy előfizetésben van üzembe helyezve, de a modul hatóköre az új erőforráscsoportra terjed ki.

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

A következő példa két különböző erőforráscsoportban helyezi üzembe a tárfiókokat. Mindkét erőforráscsoportnak már léteznie kell.

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

Állítsa a hatókör tulajdonságát érvényes hatókör-objektumra. Ha a Bicep-fájl egy erőforráscsoportot, előfizetést vagy felügyeleti csoportot helyez üzembe, beállíthatja a modul hatókörét az adott erőforrás szimbolikus nevére. Vagy használhatja a hatókörfüggvényeket egy érvényes hatókör lekéréséhez.

Ezek a függvények a következők:

• resourceGroup
• előfizetést
• managementGroup
• Bérlő

Az alábbi példa a függvényt használja a managementGroup hatókör beállításához.

param managementGroupName string

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

Hozam

A modulból lekérheti az értékeket, és használhatja őket a fő Bicep-fájlban. Egy modul kimeneti értékének lekéréséhez használja a outputs modulobjektum tulajdonságát.

Az első példa létrehoz egy tárfiókot, és visszaadja az elsődleges végpontokat.

@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

Modulként használva ezt a kimeneti értéket is lekérheti.

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

Következő lépések

• Az oktatóanyagért lásd : Azure-erőforrások üzembe helyezése Bicep-sablonok használatával.
• Ha bizalmas értéket szeretne átadni egy modulnak, használja a getSecret függvényt .