Parameters en namen verbeteren
Parameters zijn de meest voorkomende manier waarop uw collega's met uw sjabloon werken. Wanneer ze uw sjabloon implementeren, moeten ze waarden voor de parameters opgeven. Nadat deze is gemaakt, bevat de naam van een resource belangrijke informatie over het doel ervan voor iedereen die uw Azure-omgeving bekijkt.
In deze les krijgt u informatie over enkele belangrijke overwegingen wanneer u de parameters voor Bicep-bestanden plant en de namen die u uw resources geeft.
Hoe begrijpelijk zijn de parameters?
Met parameters kunt u Bicep-bestanden herbruikbaar en flexibel maken. Het is belangrijk dat het doel van elke parameter duidelijk is voor iedereen die deze parameter gebruikt. Wanneer uw collega's met uw sjabloon werken, gebruiken ze parameters om het gedrag van hun implementatie aan te passen.
Stel dat u een opslagaccount moet implementeren met behulp van een Bicep-bestand. Een van de vereiste eigenschappen van het opslagaccount is de SKU (Stock Keeping Unit), waarmee het gegevensredundantieniveau wordt gedefinieerd. De SKU heeft verschillende eigenschappen, de belangrijkste.name Wanneer u een parameter maakt om de waarde voor de SKU van het opslagaccount in te stellen, gebruikt u een duidelijk gedefinieerde naam, zoals storageAccountSkuName. Als u deze waarde gebruikt in plaats van een algemene naam zoals sku of skuName helpt anderen het doel van de parameter en de effecten van het instellen van de waarde ervan te begrijpen.
Standaardwaarden zijn een belangrijke manier om uw sjabloon bruikbaar te maken voor anderen. Het is belangrijk om standaardwaarden te gebruiken waar ze zinvol zijn. Ze helpen de gebruikers van uw sjabloon op twee manieren:
- Standaardwaarden vereenvoudigen het proces van het implementeren van uw sjabloon. Als uw parameters goede standaardwaarden hebben die voor de meeste gebruikers van uw sjabloon werken, kunnen de gebruikers de parameterwaarden weglaten in plaats van ze elke keer op te geven wanneer ze de sjabloon implementeren.
- Standaardwaarden geven een voorbeeld van hoe u verwacht dat de parameterwaarde eruitziet. Als sjabloongebruikers een andere waarde moeten kiezen, kan de standaardwaarde nuttige hints geven over hoe hun waarde eruit moet zien.
Bicep kan ook helpen bij het valideren van de invoer die gebruikers bieden via parameter decorators. U kunt deze decorators gebruiken om een parameterbeschrijving op te geven of om aan te geven welke soorten waarden zijn toegestaan. Bicep biedt verschillende typen parameter decorators:
Beschrijvingen bieden door mensen leesbare informatie over het doel van de parameter en de effecten van het instellen van de waarde.
Waardebeperkingen dwingen limieten af voor wat gebruikers kunnen invoeren voor de waarde van de parameter. U kunt een lijst met specifieke, toegestane waarden opgeven met behulp van de
@allowed()decorator. U kunt de@minValue()en@maxValue()decorators gebruiken om de minimum- en maximumwaarden voor numerieke parameters af te dwingen en u kunt de@minLength()en@maxLength()decorators gebruiken om de lengte van tekenreeks- en matrixparameters af te dwingen.Tip
Wees voorzichtig wanneer u de
@allowed()parameter decorator gebruikt om SKU's op te geven. Azure-services voegen vaak nieuwe SKU's toe en u wilt niet dat uw sjabloon onnodig het gebruik ervan verbiedt. Overweeg om Azure Policy te gebruiken om het gebruik van specifieke SKU's af te dwingen en gebruik de@allowed()decorator alleen met SKU's als er functionele redenen zijn waarom de gebruikers van uw sjabloon geen specifieke SKU moeten selecteren. De functies die uw sjabloon nodig heeft, zijn bijvoorbeeld mogelijk niet beschikbaar in die SKU. Leg dit uit met behulp van een@description()decorator of opmerking die de redenen voor iedereen in de toekomst duidelijk maakt.Metagegevens, hoewel niet vaak worden gebruikt, kunnen worden toegepast om extra aangepaste metagegevens over de parameter op te geven.
Hoe flexibel moet een Bicep-bestand zijn?
Een van de doelstellingen van het definiëren van uw infrastructuur als code is om uw sjablonen herbruikbaar en flexibel te maken. U wilt geen sjablonen voor één doel maken die een in code vastgelegde configuratie hebben. Aan de andere kant is het niet zinvol om alle resource-eigenschappen als parameters weer te geven. Maak sjablonen die werken voor uw specifieke bedrijfsprobleem of oplossing, niet algemene sjablonen die voor elke situatie moeten werken. U wilt ook niet zoveel parameters hebben dat het lang duurt om de waarden in te voeren voordat u de sjabloon kunt implementeren. Dit is met name belangrijk wanneer u de SKU's en het aantal exemplaren van resources configureert.
Wanneer u een sjabloon plant, kunt u overwegen hoe u flexibiliteit in balans brengt met eenvoud. Er zijn twee algemene manieren om parameters in sjablonen op te geven:
- Beschikbare configuratieopties bieden
- Vooraf gedefinieerde configuratiesets gebruiken
Laten we beide benaderingen overwegen met behulp van een bicep-voorbeeldbestand waarmee een opslagaccount en een Azure-app Service-plan worden geïmplementeerd.
Beschikbare configuratieopties bieden
Voor zowel het App Service-plan als het opslagaccount moet u hun SKU's opgeven. U kunt overwegen om een set parameters te maken om elk van de SKU's en het aantal exemplaren voor de resources te beheren:
Dit ziet er als volgt uit in Bicep:
param appServicePlanSkuName string
param appServicePlanSkuCapacity int
param storageAccountSkuName string
resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
name: appServicePlanName
location: location
sku: {
name: appServicePlanSkuName
capacity: appServicePlanSkuCapacity
}
}
resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = {
name: storageAccountSkuName
location: location
sku: {
name: storageAccountSkuName
}
}
Deze indeling biedt de meeste flexibiliteit, omdat iedereen die de sjabloon gebruikt elke combinatie van parameterwaarden kan opgeven. Als u echter meer resources toevoegt, hebt u meer parameters nodig. Als gevolg hiervan wordt uw sjabloon ingewikkelder. Mogelijk moet u ook bepaalde combinaties van parameters beperken of ervoor zorgen dat wanneer een specifieke resource wordt geïmplementeerd met één SKU, een andere resource moet worden geïmplementeerd met behulp van een andere SKU. Als u te veel afzonderlijke parameters opgeeft, is het lastig om deze regels af te dwingen.
Tip
Denk na over de personen die met uw sjabloon gaan werken. Als u tientallen parameters ziet, kunnen ze overweldigd raken en ze verlaten met behulp van uw sjabloon.
Mogelijk kunt u het aantal parameters verminderen door gerelateerde parameters te groeperen in de vorm van een parameterobject, zoals deze:
param appServicePlanSku object = {
name: 'S1'
capacity: 2
}
Deze aanpak kan echter de mogelijkheid verminderen om de parameterwaarden te valideren en het is niet altijd eenvoudig voor uw sjabloongebruikers om te begrijpen hoe het object moet worden gedefinieerd.
Vooraf gedefinieerde configuratiesets gebruiken
U kunt ook een configuratieset opgeven: één parameter, waarvan de waarde een beperkte lijst met toegestane waarden is, zoals een lijst met omgevingstypen. Wanneer gebruikers uw sjabloon implementeren, moeten ze slechts een waarde voor deze ene parameter selecteren. Wanneer ze een waarde voor de parameter selecteren, neemt de implementatie automatisch een set configuratie over:
De parameterdefinitie ziet er als volgt uit:
@allowed([
'Production'
'Test'
])
param environmentType string = 'Test'
Configuratiesets bieden lagere flexibiliteit, omdat personen die uw sjabloon implementeren geen grootten voor afzonderlijke resources kunnen opgeven, maar u kunt elke set configuraties valideren en ervoor zorgen dat ze aan uw vereisten voldoen. Het gebruik van configuratiesets vermindert de noodzaak voor de gebruikers van uw sjabloon om inzicht te krijgen in alle verschillende opties die beschikbaar zijn voor elke resource. Het wordt eenvoudiger om sjablonen te ondersteunen, te testen en problemen op te lossen.
Wanneer u met configuratiesets werkt, maakt u een kaartvariabele om de specifieke eigenschappen te definiëren die moeten worden ingesteld op verschillende resources, op basis van de parameterwaarde:
var environmentConfigurationMap = {
Production: {
appServicePlan: {
sku: {
name: 'P2V3'
capacity: 3
}
}
storageAccount: {
sku: {
name: 'ZRS'
}
}
}
Test: {
appServicePlan: {
sku: {
name: 'S2'
capacity: 1
}
}
storageAccount: {
sku: {
name: 'LRS'
}
}
}
}
Uw resourcedefinities gebruiken vervolgens de configuratietoewijzing om de resource-eigenschappen te definiëren:
resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
name: appServicePlanName
location: location
sku: environmentConfigurationMap[environmentType].appServicePlan.sku
}
Met configuratiesets kunt u complexe sjablonen gemakkelijker toegankelijk maken. Ze kunnen u ook helpen uw eigen regels af te dwingen en het gebruik van vooraf gevalideerde configuratiewaarden aan te moedigen.
Notitie
Deze benadering wordt ook wel t-shirt formaat genoemd. Wanneer u een t-shirt koopt, krijgt u niet veel opties voor lengte, breedte, mouwen, enzovoort. U kunt kiezen uit kleine, middelgrote en grote maten, en de t-shirt designer heeft vooraf gedefinieerd die metingen op basis van die grootte.
Hoe worden uw resources benoemd?
In Bicep is het belangrijk om uw resources betekenisvolle namen te geven. Resources in Bicep hebben twee namen:
Symbolische namen worden alleen in het Bicep-bestand gebruikt en worden niet weergegeven in uw Azure-resources. Symbolische namen helpen gebruikers die uw sjabloon lezen of wijzigen om inzicht te hebben in het doel van een parameter, variabele of resourcedefinitie, en ze helpen gebruikers weloverwogen beslissingen te nemen over het wijzigen van de sjabloon.
Resourcenamen zijn de namen van de resources die zijn gemaakt in Azure. Veel resources hebben beperkingen voor hun namen en veel resources vereisen dat hun namen uniek zijn.
Symbolische namen
Het is belangrijk om na te denken over de symbolische namen die u op uw resources toepast. Stel dat u collega's hebt die de sjabloon moeten wijzigen. Begrijpen ze waar elke resource voor is?
Stel dat u een opslagaccount wilt definiëren dat producthandleidingen bevat die gebruikers kunnen downloaden van uw website. U kunt de resource een symbolische naam geven (bijvoorbeeld) storageAccountmaar als deze zich in een Bicep-bestand bevindt dat veel andere resources bevat, en misschien zelfs andere opslagaccounts, is die naam niet voldoende beschrijvend. In plaats daarvan kunt u deze een symbolische naam geven die bepaalde informatie over het doel ervan bevat, zoals productManualStorageAccount.
In Bicep gebruikt u normaal gesproken camelCase-hoofdletterstijl voor de namen van parameters, variabelen en symbolische namen van resources. Dit betekent dat u een eerste letter in kleine letters voor het eerste woord gebruikt en vervolgens de eerste letter van de andere woorden in hoofdletters zet (zoals in het voorgaande voorbeeld). productManualStorageAccount U hoeft camelCase niet te gebruiken. Als u ervoor kiest om een andere stijl te gebruiken, is het belangrijk dat u akkoord gaat met één standaard binnen uw team en deze consistent gebruikt.
Resourcenamen
Elke Azure-resource heeft een naam. Namen vormen een deel van de id van de resource. In veel gevallen worden ze ook weergegeven als de hostnamen die u gebruikt voor toegang tot de resource. Wanneer u bijvoorbeeld een App Service-app met de naam myappmaakt, is myapp.azurewebsites.netde hostnaam die u gebruikt voor toegang tot de app. U kunt de naam van resources niet wijzigen nadat ze zijn geïmplementeerd.
Het is belangrijk om na te denken over de naam van uw Azure-resources. Veel organisaties definiëren hun eigen naamgevingsconventie voor resources. Cloud Adoption Framework voor Azure heeft specifieke richtlijnen waarmee u uw gegevens kunt definiëren. Het doel van een naamgevingsconventie voor resources is om iedereen in uw organisatie te helpen begrijpen waar elke resource voor is.
Daarnaast heeft elke Azure-resource bepaalde naamgevingsregels en -beperkingen. Er zijn bijvoorbeeld beperkingen voor de lengte van namen, de tekens die ze kunnen opnemen en of namen globaal uniek of alleen uniek moeten zijn binnen een resourcegroep.
Het kan complex zijn om alle naamconventies voor uw organisatie en de naamgevingsvereisten voor Azure te volgen. Een goed geschreven Bicep-sjabloon moet deze complexiteit verbergen voor de gebruikers en de namen voor resources automatisch bepalen. Hier volgt een voorbeeld van een aanpak:
Voeg een parameter toe die wordt gebruikt om een uniek achtervoegsel te maken. Dit helpt ervoor te zorgen dat uw resources unieke namen hebben. Het is een goed idee om de
uniqueString()functie te gebruiken om een standaardwaarde te genereren. Personen die uw sjabloon implementeren, kunnen dit overschrijven met een specifieke waarde als ze een betekenisvolle naam willen hebben. Zorg ervoor dat u de@maxLength()decorator gebruikt om de lengte van dit achtervoegsel te beperken, zodat uw resourcenamen de maximumlengte niet overschrijden.Tip
Het is beter om unieke achtervoegsels te gebruiken in plaats van voorvoegsels. Deze aanpak maakt het gemakkelijker om uw resourcenamen te sorteren en snel te scannen. Sommige Azure-resources hebben ook beperkingen voor het eerste teken van de naam en willekeurig gegenereerde namen kunnen deze beperkingen soms schenden.
Gebruik variabelen om resourcenamen dynamisch samen te stellen. Uw Bicep-code kan ervoor zorgen dat de namen die worden gegenereerd, voldoen aan de naamconventie van uw organisatie en aan De Vereisten van Azure. Neem het achtervoegsel voor uniekheid op als onderdeel van de resourcenaam.
Notitie
Niet elke resource vereist een wereldwijd unieke naam. Overweeg of u het achtervoegsel voor uniekheid opneemt in de namen van elke resource of alleen de namen die deze nodig hebben.