Best practices voor Bicep

  • Artikel
  • 5 minuten om te lezen

In dit artikel worden procedures aanbevolen die u moet volgen bij het ontwikkelen van bicep-bestanden. Deze procedures maken uw Bicep-bestand gemakkelijker te begrijpen en te gebruiken.

Microsoft Learn

Zie Structure your Bicep code for collaboration on Microsoft Learn (Uw Bicep-code structureren voor samenwerking op Microsoft Learn) voor meer informatie over bicep-best practices.

Parameters

  • Gebruik een goede naam voor parameterdeclaraties. Met goede namen zijn uw sjablonen gemakkelijk te lezen en te begrijpen. Zorg ervoor dat u duidelijke, beschrijvende namen gebruikt en consistent bent in uw naamgeving.

  • Denk goed na over de parameters die door uw sjabloon worden gebruikt. Probeer parameters te gebruiken voor instellingen die tussen implementaties veranderen. Variabelen en in code gecodeerde waarden kunnen worden gebruikt voor instellingen die niet veranderen tussen implementaties.

  • Let op de standaardwaarden die u gebruikt. Zorg ervoor dat de standaardwaarden veilig zijn voor iedereen om te implementeren. Overweeg bijvoorbeeld het gebruik van prijscategorie en SKU's voor lage kosten, zodat iemand die de sjabloon in een testomgeving implementeert, niet onnodig veel kosten in rekening wordt brengen.

  • Gebruik @allowed deator spaarzaam. Als u deze autorator te breed gebruikt, kunt u geldige implementaties blokkeren. Wanneer Azure-services SKU's en grootten toevoegen, is uw lijst met toegestane SKU's mogelijk niet up-to-date. Het toestaan van alleen Premium v3-SKU's kan bijvoorbeeld zinvol zijn in productie, maar voorkomt dat u dezelfde sjabloon gebruikt in niet-productieomgevingen.

  • Het is een goed idee om beschrijvingen voor uw parameters op te geven. Probeer de beschrijvingen nuttig te maken en geef belangrijke informatie op over wat de sjabloon nodig heeft om de parameterwaarden te zijn.

    U kunt ook opmerkingen // gebruiken voor bepaalde informatie.

  • U kunt parameterdeclaraties overal in het sjabloonbestand zetten, hoewel het meestal een goed idee is om ze bovenaan het bestand te zetten, zodat uw Bicep-code gemakkelijk te lezen is.

  • Het is een goed idee om de minimale en maximale tekenlengte op te geven voor parameters die de naamgeving bepalen. Deze beperkingen helpen fouten later tijdens de implementatie te voorkomen.

Zie Parameters in Bicepvoor meer informatie over Bicep-parameters.

Variabelen

  • Wanneer u een variabele definieert, is het gegevenstype niet nodig. Variabelen afleiden het type van de oploswaarde.

  • U kunt Bicep-functies gebruiken om een variabele te maken.

  • Nadat een variabele is gedefinieerd in uw Bicep-bestand, verwijst u naar de waarde met behulp van de naam van de variabele.

Zie Variabelen in Bicep voor meer informatie over Bicep-variabelen.

Namen

  • Gebruik kleine camelcase voor namen, zoals myVariableName of myResource .

  • De functie uniqueString() is handig voor het maken van wereldwijd unieke resourcenamen. Wanneer u dezelfde parameters op geeft, wordt telkens dezelfde tekenreeks retourneert. Het doorgeven van de resourcegroep-id betekent dat de tekenreeks bij elke implementatie hetzelfde is voor dezelfde resourcegroep, maar anders wanneer u implementeert naar verschillende resourcegroepen of abonnementen.

  • Soms maakt uniqueString() de functie tekenreeksen die beginnen met een getal. Sommige Azure-resources, zoals opslagaccounts, staan niet toe dat hun namen beginnen met getallen. Deze vereiste betekent dat het een goed idee is om tekenreeksinterpolatie te gebruiken om resourcenamen te maken. U kunt een voorvoegsel toevoegen aan de unieke tekenreeks.

  • Het is vaak een goed idee om sjabloonexpressie te gebruiken om resourcenamen te maken. Veel Azure-resourcetypen hebben regels over de toegestane tekens en de lengte van hun namen. Het insluiten van het maken van resourcenamen in de sjabloon betekent dat iedereen die de sjabloon gebruikt, deze regels zelf niet hoeft te volgen.

  • Vermijd het name gebruik van in een symbolische naam. De symbolische naam vertegenwoordigt de resource, niet de naam van de resource. In plaats van dit:

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

    gebruik deze:

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

  • Vermijd het onderscheiden van variabelen en parameters door gebruik te maken van achtervoegsels.

Resourcedefinities

  • In plaats van complexe expressies rechtstreeks in tesluiten in resource-eigenschappen, gebruikt u variabelen om de expressies te bevatten. Deze aanpak maakt uw Bicep-bestand gemakkelijker te lezen en te begrijpen. Zo voorkomt u dat uw resourcedefinities vol komen te zitten met logica.

  • Probeer resource-eigenschappen te gebruiken als uitvoer, in plaats van veronderstellingen te doen over hoe resources zich zullen gedragen. Als u bijvoorbeeld de URL wilt uitvoer naar een App Service-app, gebruikt u de eigenschap defaultHostname van de app in plaats van zelf een tekenreeks voor de URL te maken. Soms zijn deze veronderstellingen niet juist in verschillende omgevingen of veranderen de resources de manier waarop ze werken. Het is veiliger om de resource uw eigen eigenschappen te laten vertellen.

  • Het is een goed idee om voor elke resource een recente API-versie te gebruiken. Nieuwe functies in Azure-services zijn soms alleen beschikbaar in nieuwere API-versies.

  • Vermijd indien mogelijk het gebruik van de functies reference en resourceId in uw Bicep-bestand. U hebt toegang tot elke resource in Bicep met behulp van de symbolische naam. Als u bijvoorbeeld een opslagaccount met de symbolische naam toyDesignDocumentsStorageAccount definieert, hebt u toegang tot de resource-id met behulp van de expressie toyDesignDocumentsStorageAccount.id . Met behulp van de symbolische naam maakt u een impliciete afhankelijkheid tussen resources.

  • Gebruik liever impliciete afhankelijkheden dan expliciete afhankelijkheden. Hoewel u met de eigenschap resource een expliciete afhankelijkheid tussen resources kunt declaren, is het meestal mogelijk om de eigenschappen van de andere resource te gebruiken met behulp van de dependsOn symbolische naam. Hiermee wordt een impliciete afhankelijkheid tussen de twee resources gemaakt en kan Bicep de relatie zelf beheren.

  • Als de resource niet is geïmplementeerd in het Bicep-bestand, kunt u nog steeds een symbolische verwijzing naar de resource krijgen met behulp van het existing trefwoord .

Onderliggende resources

  • Vermijd te veel lagen diep te nesten. Te veel nesten maakt uw Bicep-code moeilijker te lezen en daarmee te werken.

  • Vermijd het maken van resourcenamen voor onderliggende resources. U verliest de voordelen die Bicep biedt wanneer het inzicht krijgt in de relaties tussen uw resources. Gebruik in parent plaats daarvan de eigenschap of nesting.

Uitvoerwaarden

  • Zorg ervoor dat u geen uitvoer voor gevoelige gegevens maakt. Uitvoerwaarden zijn toegankelijk voor iedereen die toegang heeft tot de implementatiegeschiedenis. Ze zijn niet geschikt voor het verwerken van geheimen.

  • In plaats van eigenschapswaarden door te geven via uitvoer, gebruikt u het bestaande trefwoord om eigenschappen op te zoeken van resources die al bestaan. Het is een best practice sleutels van andere resources op deze manier op te zoeken in plaats van ze door te geven via uitvoer. U krijgt altijd de meest actuele gegevens.

Zie Outputs in Bicep (Uitvoer in Bicep) voor meer informatie over Bicep-uitvoer.

Tenantbereiken

U kunt geen beleidsregels of roltoewijzingen maken in het tenantbereik. Als u echter toegang moet verlenen of beleidsregels moet toepassen in uw hele organisatie, kunt u deze resources implementeren in de hoofdbeheergroep.

Volgende stappen