Ajánlott eljárások a Bicep-hez

  • Cikk

Ez a cikk a Bicep-fájlok fejlesztésekor követendő eljárásokat javasolja. Ezek a gyakorlatok megkönnyítik a Bicep-fájl megértését és használatát.

Képzési források

Ha lépésről lépésre szeretne többet megtudni a Bicep ajánlott eljárásairól, olvassa el A Bicep-kód strukturálása együttműködésre című témakört.

Paraméterek

  • A paraméterdeklarációkhoz használjon jó elnevezést. A jó nevek megkönnyítik a sablonok olvasását és megértését. Ügyeljen arra, hogy világos, leíró neveket használjon, és konzisztens legyen az elnevezésben.

  • Alaposan gondolja át a sablon által használt paramétereket. Próbálja meg paramétereket használni az üzemelő példányok között változó beállításokhoz. A változók és a rögzített értékek olyan beállításokhoz használhatók, amelyek nem változnak az üzemelő példányok között.

  • Ügyeljen a használt alapértelmezett értékekre. Győződjön meg arról, hogy az alapértelmezett értékek mindenki számára biztonságosak. Fontolja meg például az alacsony költségű tarifacsomagok és termékváltozatok használatát, hogy a sablon tesztelési környezetben történő üzembe helyezése ne járjon feleslegesen nagy költséggel.

  • Ritkán használja a @allowed dekoratőrt. Ha túl széles körben használja ezt a dekorátort, letilthatja az érvényes üzemelő példányokat. Mivel az Azure-szolgáltatások termékváltozatokat és méreteket adnak hozzá, előfordulhat, hogy az engedélyezett lista nem naprakész. Ha például csak a Premium v3 termékváltozatokat engedélyezi éles környezetben, az megakadályozza, hogy ugyanazt a sablont nem éles környezetben használja.

  • Célszerű leírásokat adni a paraméterekhez. Próbálja meg hasznossá tenni a leírásokat, és adjon meg minden fontos információt arról, hogy a sablonnak milyen paraméterértékekre van szüksége.

    Megjegyzésekkel jegyzeteket is // felvehet a Bicep-fájlokba.

  • A paraméterdeklarációkat bárhol elhelyezheti a sablonfájlban, bár általában érdemes a fájl tetejére helyezni őket, hogy a Bicep-kód könnyen olvasható legyen.

  • Célszerű megadni az elnevezést vezérlő paraméterek minimális és maximális karakterhosszát. Ezek a korlátozások segítenek elkerülni a későbbi üzembe helyezés során jelentkező hibákat.

A Bicep-paraméterekkel kapcsolatos további információkért lásd: Paraméterek a Bicepben.

Változók

  • Változó definiálásakor nincs szükség adattípusra . A változók a feloldás értékéből következtetik a típusra.

  • A Bicep-függvényekkel változókat hozhat létre.

  • Miután definiált egy változót a Bicep-fájlban, a változó nevével hivatkozhat az értékre.

A Bicep-változókkal kapcsolatos további információkért lásd: Változók a Bicepben.

Nevek

  • Használjon kisebb tevebetűs kisbetűket a nevekhez, például myVariableName vagy myResource.

  • Az uniqueString() függvény hasznos az egyedi erőforrásnevek létrehozásához. Ha ugyanazokat a paramétereket adja meg, az minden alkalommal ugyanazt a sztringet adja vissza. Az erőforráscsoport-azonosító megadása azt jelenti, hogy a sztring minden üzemelő példányon ugyanazzal az erőforráscsoporthoz tartozik, de eltérő, ha különböző erőforráscsoportokban vagy előfizetésekben helyezi üzembe azokat.

  • Az alábbi példához hasonlóan ajánlott sablonkifejezéseket használni az erőforrásnevek létrehozásához:

    param shortAppName string = 'toy'
param shortEnvironmentName string = 'prod'
param appServiceAppName string = '${shortAppName}-${shortEnvironmentName}-${uniqueString(resourceGroup().id)}'

    Az erőforrásnevek létrehozása sablonkifejezésekkel számos előnnyel jár:

    • Az által uniqueString() létrehozott sztringek nem értelmezhetők. Hasznos, ha sablonkifejezéssel olyan nevet hoz létre, amely értelmes információkat tartalmaz, például a projekt vagy a környezet nevének rövid leíróját, valamint egy véletlenszerű összetevőt, hogy a név nagyobb valószínűséggel legyen egyedi.

    • A uniqueString() függvény nem garantálja a globálisan egyedi neveket. Ha további szöveget ad hozzá az erőforrásnevekhez, csökkentheti a meglévő erőforrásnevek újbóli használatba adásának valószínűségét.

    • Néha a uniqueString() függvény sztringeket hoz létre, amelyek egy számmal kezdődnek. Egyes Azure-erőforrások, például a tárfiókok nem engedélyezik, hogy a nevük számokkal kezdődjön. Ez a követelmény azt jelenti, hogy érdemes sztring interpolációval erőforrásneveket létrehozni. Előtagot adhat hozzá az egyedi sztringhez.

    • Számos Azure-erőforrástípus rendelkezik szabályokkal az engedélyezett karakterekre és a nevük hosszára vonatkozóan. Ha beágyazza az erőforrásnevek létrehozását a sablonba, az azt jelenti, hogy a sablont használóknak nem kell saját maguknak követniük ezeket a szabályokat.

  • Ne használjon name szimbolikus nevet. A szimbolikus név nem az erőforrás nevét, hanem az erőforrás nevét jelöli. Például a következő szintaxis helyett:

    resource cosmosDBAccountName 'Microsoft.DocumentDB/databaseAccounts@2023-04-15' = {

    Használja:

    resource cosmosDBAccount 'Microsoft.DocumentDB/databaseAccounts@2023-04-15' = {

  • Kerülje a változók és paraméterek megkülönböztetését utótagok használatával.

Erőforrás-definíciók

  • Ahelyett, hogy összetett kifejezéseket ágyaz be közvetlenül az erőforrás-tulajdonságokba, változókkal kell tartalmaznia a kifejezéseket. Ez a módszer megkönnyíti a Bicep-fájl olvasását és megértését. Ezzel elkerülheti az erőforrás-definíciók logikával való zsúfoltságát.

  • Próbálja meg az erőforrás-tulajdonságokat kimenetként használni, ahelyett, hogy feltételezi, hogy az erőforrások hogyan fognak viselkedni. Ha például ki kell adnia az URL-címet egy App Service alkalmazásnak, használja az alkalmazás defaultHostname tulajdonságát ahelyett, hogy saját maga hoz létre sztringet az URL-címhez. Előfordulhat, hogy ezek a feltételezések nem helyesek a különböző környezetekben, vagy az erőforrások megváltoztatják a működést. Biztonságosabb, ha az erőforrás saját tulajdonságait mondja el.

  • Érdemes egy újabb API-verziót használni az egyes erőforrásokhoz. Az Azure-szolgáltatások új funkciói néha csak az újabb API-verziókban érhetők el.

  • Ha lehetséges, ne használja a referencia - és resourceId függvényeket a Bicep-fájlban. A Bicep bármely erőforrását a szimbolikus névvel érheti el. Ha például egy toyDesignDocumentsStorageAccount szimbolikus nevű tárfiókot definiál, az erőforrás-azonosítóját a kifejezéssel toyDesignDocumentsStorageAccount.idérheti el. A szimbolikus név használatával implicit függőséget hoz létre az erőforrások között.

  • Inkább implicit függőségeket használ az explicit függőségekkel szemben. Bár az dependsOn erőforrástulajdonság lehetővé teszi, hogy explicit függőséget deklaráljon az erőforrások között, általában a másik erőforrás tulajdonságait használhatja a szimbolikus nevével. Ez a megközelítés implicit függőséget hoz létre a két erőforrás között, és lehetővé teszi, hogy a Bicep kezelje magát a kapcsolatot.

  • Ha az erőforrás nincs üzembe helyezve a Bicep-fájlban, a kulcsszó használatával továbbra is kaphat szimbolikus hivatkozást az existing erőforrásra.

Gyermekerőforrások

  • Kerülje a túl sok réteg mély beágyazását. A túl sok beágyazás megnehezíti a Bicep-kód olvasását és használatát.

  • Kerülje a gyermekerőforrások erőforrásneveinek összeállítását. Elveszíti azokat az előnyöket, amelyeket a Bicep biztosít, ha megérti az erőforrások közötti kapcsolatokat. Használja inkább a parent tulajdonságot vagy a beágyazást.

Kimenetek

  • Győződjön meg arról, hogy nem hoz létre kimeneteket bizalmas adatokhoz. A kimeneti értékeket bárki elérheti, aki hozzáfér az üzembehelyezési előzményekhez. Nem alkalmasak titkos kódok kezelésére.

  • Ahelyett, hogy tulajdonságértékeket ad át a kimeneteken keresztül, használja a meglévő kulcsszót a már létező erőforrások tulajdonságainak kereséséhez. Ajánlott így keresni a kulcsokat más erőforrásokból ahelyett, hogy a kimeneteken keresztül továbbítanák őket. Mindig a legfrissebb adatokat fogja megkapni.

További információ a Bicep-kimenetekről: Kimenetek a Bicepben.

Bérlői hatókörök

A bérlő hatókörében nem hozhat létre szabályzatokat vagy szerepkör-hozzárendeléseket. Ha azonban hozzáférést kell biztosítania vagy szabályzatokat kell alkalmaznia a teljes szervezeten belül, ezeket az erőforrásokat üzembe helyezheti a gyökérszintű felügyeleti csoportban.

Következő lépések