Osvědčené postupy pro Bicep

  • Článek

Tento článek doporučuje postupy, které je třeba dodržovat při vývoji souborů Bicep. Tyto postupy usnadňují pochopení a používání souboru Bicep.

Školicí materiály

Pokud byste se raději dozvěděli o osvědčených postupech bicepu v podrobných doprovodných materiálech, přečtěte si téma Strukturování kódu Bicep pro spolupráci.

Parametry

  • Pro deklarace parametrů používejte vhodné pojmenování. Díky dobrým jménům jsou vaše šablony snadno čitelné a srozumitelné. Ujistěte se, že používáte jasné a popisné názvy a buďte při vytváření názvů konzistentní.

  • Pečlivě zvažte parametry, které šablona používá. Zkuste použít parametry pro nastavení, která se mění mezi nasazeními. Proměnné a pevně zakódované hodnoty se dají použít pro nastavení, která se mezi nasazeními nemění.

  • Mějte na paměti výchozí hodnoty, které používáte. Ujistěte se, že výchozí hodnoty jsou bezpečné pro každého, kdo ho může nasadit. Zvažte například použití cenových úrovní a cenových úrovní s nízkými náklady, aby se někomu, kdo šablonu nasadí do testovacího prostředí, zbytečně neúčtovaly velké náklady.

  • @allowed Používejte dekorátor střídmě. Pokud tento dekorátor používáte příliš široce, můžete blokovat platná nasazení. Vzhledem k tomu, že služby Azure přidávají skladové položky a velikosti, nemusí být seznam povolených položek aktuální. Například povolení pouze skladových položek premium v3 může mít smysl v produkčním prostředí, ale zabrání vám v použití stejné šablony v neprodukčním prostředí.

  • Je vhodné zadat popisy parametrů. Snažte se, aby popisy byly užitečné, a uveďte důležité informace o tom, co šablona potřebuje, aby byly hodnoty parametrů.

    Komentáře můžete také použít // k přidání poznámek do souborů Bicep.

  • Deklarace parametrů můžete umístit kamkoli do souboru šablony, i když je obvykle vhodné umístit je na začátek souboru, aby byl kód Bicep snadno čitelný.

  • Pro parametry, které řídí pojmenování, je vhodné zadat minimální a maximální délku znaků. Tato omezení pomáhají předcházet chybám později během nasazování.

Další informace o parametrech bicepu najdete v tématu Parametry v bicepu.

Proměnné

  • Když definujete proměnnou, datový typ není potřeba. Proměnné odvozují typ z hodnoty překladu.

  • K vytvoření proměnné můžete použít funkce Bicep.

  • Jakmile je proměnná definovaná v souboru Bicep, odkazujete na hodnotu pomocí názvu proměnné.

Další informace o proměnných Bicep najdete v tématu Proměnné v bicepu.

Názvy

  • Pro jména, jako myVariableName je nebo myResource, použijte malá velká písmena.

  • Funkce uniqueString() je užitečná při vytváření jedinečných názvů prostředků. Když zadáte stejné parametry, vrátí pokaždé stejný řetězec. Předání ID skupiny prostředků znamená, že řetězec je stejný při každém nasazení do stejné skupiny prostředků, ale při nasazování do různých skupin prostředků nebo předplatných se liší.

  • K vytváření názvů prostředků je vhodné použít výrazy šablon, jako v tomto příkladu:

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

    Použití výrazů šablony k vytvoření názvů prostředků přináší několik výhod:

    • Řetězce vygenerované nástrojem uniqueString() nemají smysl. Je užitečné použít výraz šablony k vytvoření názvu, který obsahuje smysluplné informace, jako je krátký popisovač projektu nebo názvu prostředí, a také náhodnou komponentu, aby byl název pravděpodobnější jedinečný.

    • Funkce uniqueString() nezaručuje globálně jedinečné názvy. Přidáním dalšího textu k názvům prostředků snížíte pravděpodobnost opakovaného použití existujícího názvu prostředku.

    • uniqueString() Někdy funkce vytvoří řetězce, které začínají číslem. Některé prostředky Azure, jako jsou účty úložiště, neumožňují, aby jejich názvy začínaly čísly. Tento požadavek znamená, že k vytváření názvů prostředků je vhodné použít interpolaci řetězců. K jedinečnému řetězci můžete přidat předponu.

    • Mnoho typů prostředků Azure má pravidla týkající se povolených znaků a délky jejich názvů. Vložení vytváření názvů prostředků do šablony znamená, že každý, kdo šablonu používá, nemusí pamatovat na dodržování těchto pravidel sám.

  • name Nepoužívejte symbolický název. Symbolický název představuje prostředek, nikoli jeho název. Například místo následující syntaxe:

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

    Použít:

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

  • Vyhněte se rozlišení proměnných a parametrů pomocí přípon.

Definice prostředků

  • Místo vkládání složitých výrazů přímo do vlastností prostředků použijte proměnné k jejich zahrnutí. Tento přístup usnadňuje čtení a pochopení souboru Bicep. Vyhnete se tak zahlceným definicím prostředků pomocí logiky.

  • Zkuste použít vlastnosti prostředku jako výstupy, místo abyste předpokládali, jak se budou prostředky chovat. Pokud například potřebujete výstup adresy URL do aplikace App Service, použijte vlastnost defaultHostname aplikace místo vytvoření řetězce pro adresu URL sami. Někdy tyto předpoklady nejsou v různých prostředích správné nebo se prostředky změní, jak fungují. Je bezpečnější nechat prostředek informovat o svých vlastních vlastnostech.

  • Pro každý prostředek je vhodné použít nejnovější verzi rozhraní API. Nové funkce ve službách Azure jsou někdy dostupné jenom v novějších verzích rozhraní API.

  • Pokud je to možné, nepoužívejte v souboru Bicep funkce reference a resourceId . Ke všem prostředkům v bicepu můžete přistupovat pomocí symbolického názvu. Pokud například definujete účet úložiště se symbolickým názvem toyDesignDocumentsStorageAccount, můžete získat přístup k JEHO ID prostředku pomocí výrazu toyDesignDocumentsStorageAccount.id. Pomocí symbolického názvu vytvoříte implicitní závislost mezi prostředky.

  • Upřednostněte použití implicitních závislostí před explicitními závislostmi. dependsOn I když vlastnost prostředku umožňuje deklarovat explicitní závislost mezi prostředky, je obvykle možné použít vlastnosti jiného prostředku pomocí jeho symbolického názvu. Tento přístup vytvoří implicitní závislost mezi těmito dvěma prostředky a umožní nástroji Bicep spravovat samotný vztah.

  • Pokud prostředek není nasazený v souboru Bicep, můžete stále získat symbolický odkaz na prostředek pomocí klíčového existing slova.

Podřízené prostředky

  • Vyhněte se vnořování příliš mnoha vrstev hluboko. Příliš mnoho vnořování znesnadňuje čtení a práci s kódem Bicep.

  • Vyhněte se vytváření názvů prostředků pro podřízené prostředky. Ztratíte výhody, které bicep poskytuje, když rozumí vztahům mezi vašimi prostředky. Místo toho parent použijte vlastnost nebo vnoření.

Výstupy

  • Ujistěte se, že nevytáčíte výstupy pro citlivá data. K výstupním hodnotám může přistupovat každý, kdo má přístup k historii nasazení. Nejsou vhodné pro zpracování tajných kódů.

  • Místo předávání hodnot vlastností mezi výstupy použijte existující klíčové slovo k vyhledání vlastností prostředků, které již existují. Osvědčeným postupem je vyhledávat klíče z jiných prostředků tímto způsobem, místo abyste je předávali mezi výstupy. Vždy získáte nejaktuálnější data.

Další informace o výstupech bicepu najdete v tématu Výstupy v bicepu.

Rozsahy tenantů

V oboru tenanta nemůžete vytvářet zásady ani přiřazení rolí. Pokud ale potřebujete udělit přístup nebo použít zásady v celé organizaci, můžete tyto prostředky nasadit do kořenové skupiny pro správu.

Další kroky