A Bicep-fájl újrabontása

  • 5 perc

A sablon Bicep-be való konvertálásának és migrálásának fázisai után javítania kell a fájlt. Ezt a folyamatot újrabontásnak nevezzük. A JSON ARM-sablon és az Azure-erőforrások Bicep-be való migrálásához ajánlott munkafolyamat harmadik fázisa az újrabontási fázis:

Diagram that shows the refactor phase of the recommended workflow for migrating Azure resources to Bicep.

Az újrabontási fázis fő célja a Bicep-kód minőségének javítása. A fejlesztések olyan módosításokat is tartalmazhatnak, mint például a sablon sablonszabványaihoz igazodó kódbejegyzések hozzáadása.

Az újrabontási fázis nyolc lépésből áll, amelyeket bármilyen sorrendben elvégezhet:

  • Tekintse át az erőforrás API-verzióit.
  • Tekintse át az új Bicep-fájl linter javaslatait.
  • Paraméterek, változók és szimbolikus nevek felülvizsgálata.
  • A kifejezések egyszerűsítése.
  • Tekintse át a gyermek- és bővítményerőforrásokat.
  • Modularize.
  • Megjegyzések hozzáadása.
  • Kövesse a Bicep ajánlott eljárásait.

Az alábbi példa egy App Service-csomagot létrehozó JSON-sablon Bicep decompile parancsának kimenetét mutatja be:

@description('Location for resources.')
param location string = resourceGroup().location

@allowed([
  'prod'
  'dev'
  'test'
])
@description('The list of allowed environment names.')
param environment string = 'prod'

@allowed([
  'P1v3'
  'P2v3'
  'P3v3'
])
@description('The list of allowed App Service Plan SKUs.')
param appServicePlanSku string = 'P1v3'

@minValue(1)
@maxValue(10)
@description('The number of allowed App Service Plan instances.')
param appServicePlanInstanceCount int = 1

var appServicePlanName_var = 'plan-${environment}-001'

resource appServicePlanName 'Microsoft.Web/serverfarms@2020-12-01' = {
  name: appServicePlanName_var
  location: location
  sku: {
    name: appServicePlanSku
    capacity: appServicePlanInstanceCount
  }
  kind: 'app'
  properties: {}
}

output appServicePlanId string = appServicePlanName.id

Ha a Bicep-sablont jelenleg is üzembe helyezi, az üzembe helyezés sikeres lesz, de továbbfejlesztheti a sablont, hogy megfeleljen a sablonszabványoknak.

Erőforrás API-verzióinak áttekintése

Amikor a Bicep használatával használja az Azure-erőforrásokat, meg kell adnia egy használni kívánt API-verziót. Ahogy az Azure-termékek változnak és fejlődnek, újabb API-verziók jelennek meg, amelyek hozzáférést biztosítanak az új funkciókhoz. Az Azure-erőforrások exportálásakor előfordulhat, hogy az exportált sablon nem rendelkezik az erőforrástípus legújabb API-verziójával. Ha a jövőbeli üzemelő példányokhoz konkrét tulajdonságokra van szüksége, frissítse az API-t a megfelelő verzióra. Ajánlott áttekinteni az egyes exportált erőforrások API-verzióit.

Az Azure ARM-sablonreferenciával ellenőrizheti a sablon megfelelő API-verzióit és erőforrás-tulajdonságait.

Tekintse át a linter javaslatokat az új Bicep-fájlban

Amikor Bicep-fájlokat hoz létre a Visual Studio Code Bicep-bővítményével, a linter automatikusan fut, és kiemeli a kód hibáit, és javaslatokat nyújt. Számos javaslat és hiba tartalmaz egy lehetőséget a probléma gyors megoldására. Tekintse át ezeket a javaslatokat, és módosítsa a Bicep-fájlt.

Paraméterek, változók és szimbolikus nevek módosítása

Ha az infrastruktúra több környezetet támogat, például az éles üzemet és a fejlesztést, hozzon létre olyan paramétereket, amelyek támogatják ezeket a környezeteket. A jó paraméterelnevezési konvenció megkönnyíti az üzemelő példányok környezetenkénti testreszabását.

Előfordulhat, hogy a dekompiler által létrehozott paraméterek, változók és szimbolikus nevek nevei nem egyeznek a szabványos elnevezési konvencióval. Tekintse át a létrehozott neveket, és szükség szerint végezze el a módosításokat.

Az alábbi példában a névvel ellátott appServicePlanName_var _var változó hozzá lett fűzve az eredeti változónév végéhez:

@minValue(1)
@maxValue(10)
@description('The number of allowed App Service Plan instances.')
param appServicePlanInstanceCount int = 1

var appServicePlanName_var = 'plan-${environment}-001'

resource appServicePlanName 'Microsoft.Web/serverfarms@2020-12-01' = {

Az egyértelműség kedvéért érdemes eltávolítani _var a változó nevét. A változó átnevezésekor azonban az új neve ütközik az App Service-csomag erőforrásának szimbolikus nevével. Ezért érdemes először átnevezni az erőforrásokat, majd átnevezni a definícióikban használt változókat.

Tipp.

Az azonosítók átnevezésekor mindenképpen konzisztensen nevezze át őket a sablon minden részében. Ez különösen fontos a sablonban hivatkozott paraméterek, változók és erőforrások esetében.

A Visual Studio Code kényelmes módot kínál a szimbólumok átnevezésére: válassza ki az átnevezni kívánt azonosítót, válassza az F2 lehetőséget, adjon meg egy új nevet, majd válassza az Enter billentyűt:

Screenshot from Visual Studio Code that shows how to rename a symbol.

Ezek a lépések átnevezik az azonosítót, és automatikusan frissítik az összes rá mutató hivatkozást.

Kifejezések egyszerűsítése

Előfordulhat, hogy a lebomlási folyamat nem mindig használja ki a Bicep egyes funkcióit. Tekintse át az átalakítás során létrehozott kifejezéseket, és egyszerűsítse őket. A lefordított sablon tartalmazhat például egy vagy format() több concat() olyan függvényt, amelyet sztring interpolációval egyszerűsíthet. Tekintse át a linter javaslatait, és szükség szerint végezze el a módosításokat.

Gyermek- és bővítményerőforrások áttekintése

A Bicep többféleképpen is deklarálhatja a gyermek- és bővítményerőforrásokat, beleértve az erőforrások nevének összefűzését, a tulajdonság használatát és a parent beágyazott erőforrások használatát.

Érdemes lehet áttekinteni ezeket az erőforrásokat a felbontás után, hogy meggyőződjön arról, hogy a struktúra megfelel a szabványoknak. Győződjön meg például arról, hogy nem használ sztringösszefűzést gyermekerőforrás-nevek létrehozásához. Ehelyett használja a parent tulajdonságot vagy egy beágyazott erőforrást. Hasonlóképpen hivatkozhat az alhálózatokra virtuális hálózat tulajdonságaiként vagy különálló erőforrásokként.

Modularizálás

Ha olyan sablont alakít át, amely sok erőforrással rendelkezik, fontolja meg az egyes erőforrástípusok modulokká alakítását az egyszerűség kedvéért. A Bicep moduljainak használata segít csökkenteni a sablontelepítések összetettségét.

Feljegyzés

A JSON-sablonokat modulként is használhatja egy Bicep-üzembe helyezés során. A Bicep képes felismerni a JSON-modulokat, és ugyanúgy hivatkozni rájuk, mint a Bicep-modulok használatára.

Megjegyzések és leírások hozzáadása

A Jó Bicep-kód önaláírás. A Bicepben megjegyzéseket és leírásokat adhat hozzá a kódhoz az infrastruktúra dokumentálásához. A megjegyzések és leírások segíthetnek a csapattagoknak megérteni a kódot, és növelik a bizalmat a módosítások során. A megjegyzések és leírások akkor jelennek meg, ha Bicep-fájllal dolgozik a Visual Studio Code-ban, például amikor paraméterértéket kell megadnia egy modulhoz. Ha azonban bicep-fájlt helyez üzembe az Azure-ban, a megjegyzések figyelmen kívül lesznek hagyva.

Egysoros megjegyzéseket a karaktersorozat használatával // adhat hozzá. Többsoros megjegyzések esetén kezdje a következővel*/: egy /* . A kód adott soraira vagy a kódszakaszokra vonatkozó megjegyzéseket is hozzáadhat.

A fájl elején többsoros megjegyzést is hozzáadhat:

/*
  This Bicep file was developed by the web team.
  It deploys the resources we need for our toy company's website.
*/

A kód leírásához egysoros megjegyzéseket adhat hozzá fejlécként a kódszakaszokhoz vagy az egyes sorokhoz:

// Resource - App Service plan
@description('The App Service plan resource name.')
resource appServicePlan 'Microsoft.Web/serverfarms@2022-03-01' = {
  name: appServicePlanName
  location: location
  sku: {
    name: appServicePlanSku // Specifies the SKU of the App Service plan.
    capacity: appServicePlanInstanceCount
  }
  kind: 'app' // Specifies a Windows App Service plan.
}

// Outputs
@description('The resource ID of the App Service plan.')
output appServicePlanId string = appServicePlan.id // Resource ID of the App Service plan.

A Bicep egy dekoratőrt @description biztosít, amellyel dokumentálhatja a paraméterek, változók, erőforrások, modulok és kimenetek célját. A leírást a leírt elem fölötti sorra is felveheti:

@description('The name of the App Service plan.')
var appServicePlanName = 'plan-${environment}-001'

A Bicep ajánlott eljárásainak követése

Győződjön meg arról, hogy a Bicep-fájl a szokásos javaslatokat követi. Tekintse át a Bicep ajánlott eljárásait minden olyan dologhoz, amelyet esetleg kihagyott.

A konvertált sablon

Miután elvégezte a megfelelő fejlesztéseket, tekintse át a végleges sablont, mielőtt üzembe helyezené. A frissített sablon módosított neveket, API-verziókat, leírásokat és hozzáadott megjegyzéseket tartalmaz:

/*
  This Bicep file was developed by the web team.
  It deploys the resources we need for our toy company's website.
*/

// Parameters
@description('Location for all resources.')
param location string = resourceGroup().location

@allowed([
  'prod' // Production environment
  'dev' // Development environment
  'test' // Test environment
])
@description('The list of allowed environment names.')
param environment string = 'prod'

@allowed([
  'P1v3'
  'P2v3'
  'P3v3'
])
@description('The list of allowed App Service plan SKUs.')
param appServicePlanSku string = 'P1v3'

@minValue(1)
@maxValue(10)
@description('The number of allowed App Service plan instances.')
param appServicePlanInstanceCount int = 1

// Variables
@description('The name of the App Service plan.')
var appServicePlanName = 'plan-${environment}-001'

// Resource - App Service plan
@description('The App Service plan resource name.')
resource appServicePlan 'Microsoft.Web/serverfarms@2022-03-01' = {
  name: appServicePlanName
  location: location
  sku: {
    name: appServicePlanSku // Specifies the SKU of the App Service plan.
    capacity: appServicePlanInstanceCount
  }
  kind: 'app' // Specifies a Windows App Service plan.
}

// Outputs
@description('The resource ID of the App Service plan.')
output appServicePlanId string = appServicePlan.id // Resource ID of the App Service plan.