Bicep-modulok
A Bicep lehetővé teszi az üzembe helyezés modulokba rendezését. A modul egy bicep-fájl (vagy egy Azure Resource Manager JSON-sablon), amely egy másik Bicep-fájlból van üzembe helyezve. 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 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
aloadTextContent
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, olvassa el 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.
Modulok definiálása
A modul meghatározásának alapszintaxisa a következő:
@<decorator>(<argument>)
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.
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
Feljegyzés
A nem AVM (Azure Verified Modules) modulok ki lesznek vonni a nyilvános modulregisztrációs adatbázisból.
Az Azure Ellenőrzött modulok előre összeállított, előre tesztelt és előre ellenőrzött modulok az erőforrások Azure-ban való üzembe helyezéséhez. A Microsoft alkalmazottai által létrehozott és birtokolt modulok célja a gyakori Azure-erőforrások és konfigurációk üzembe helyezési folyamatának egyszerűsítése és felgyorsítása, valamint az ajánlott eljárásokhoz való igazodás; például a jól kiépítésű keretrendszert.
Az Elérhető modulok listájának megtekintéséhez keresse meg az Azure Verified Modules Bicep-indexet, és válassza ki a kiemelt számokat az alábbi képernyőképen, amelyet közvetlenül erre a szűrt nézetre szeretne készíteni.
A modullista a legújabb verziót jeleníti meg. Válassza ki a verziószámot az elérhető verziók listájának megtekintéséhez:
Nyilvános modulhoz való csatoláshoz adja meg a modul elérési útját a következő szintaxissal:
module <symbolic-name> 'br/public:<file-path>:<tag>' = {}
- a br/public a nyilvános modulok aliasa. Ezt az aliast testre szabhatja a Bicep konfigurációs fájljá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 storage 'br/public:avm/res/storage/storage-account:0.9.0' = {
name: 'myStorage'
params: {
name: 'store${resourceGroup().name}'
}
}
Feljegyzés
a br/public a nyilvános modulok aliasa. A következő módon is írható:
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 storage 'br/public:avm/res/storage/storage-account:0.9.0' = {
name: 'myStorage'
params: {
name: 'store${resourceGroup().name}'
}
}
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'
}
}
Dekorátorok használata
A dekorátorok formátuma @expression
és a moduldeklarációk fölé kerülnek. Az alábbi táblázat a modulokhoz elérhető dekorátorokat mutatja be.
Lakberendező | Argumentum | Leírás |
---|---|---|
batchSize | Nincs | A példányok beállítása egymás után történő üzembe helyezéshez. |
leírás | húr | Adja meg a modul leírását. |
A dekorátorok a sys névtérben találhatók. Ha meg kell különböztetnie egy dekoratőrt egy másik, azonos nevű elemtől, akkor a dekoratőrt a következővel kell előtagolnia sys
: . Ha például a Bicep-fájl tartalmaz egy elnevezett description
paramétert, akkor a leírás-dekorátor használatakor hozzá kell adnia a sys névteret.
BatchSize
Csak kifejezéseket használó for
erőforrás- vagy moduldefiníciókra alkalmazható.@batchSize()
Alapértelmezés szerint a modulok párhuzamosan vannak üzembe helyezve. A dekoratőr hozzáadásakor @batchSize(int)
a példányokat sorosan helyezi üzembe.
@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}'
}
}]
További információ: Üzembe helyezés kötegekben.
Leírás
Magyarázat hozzáadásához adjon hozzá leírást a moduldeklarációkhoz. Példa:
@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}'
}
}
Markdown formátumú szöveg használható a leírás szövegéhez.
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@2023-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@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
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@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
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@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'
}
}
Á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:
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@2023-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@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
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 .