Förbättra parametrar och namn

• 8 minuter

Parametrar är det vanligaste sättet för dina kollegor att interagera med mallen. När de distribuerar mallen måste de ange värden för parametrarna. När den har skapats innehåller namnet på en resurs viktig information om dess syfte för alla som tittar på din Azure-miljö.

I den här lektionen får du lära dig om några viktiga överväganden när du planerar parametrarna för Bicep-filer och de namn som du ger dina resurser.

Hur begripliga är parametrarna?

Parametrar hjälper till att göra Bicep-filer återanvändbara och flexibla. Det är viktigt att syftet med varje parameter är tydligt för alla som använder den. När dina kollegor arbetar med mallen använder de parametrar för att anpassa beteendet för distributionen.

Anta till exempel att du behöver distribuera ett lagringskonto med hjälp av en Bicep-fil. En av de nödvändiga egenskaperna för lagringskontot är lagerhållningsenheten (SKU), som definierar nivån för dataredundans. SKU:n har flera egenskaper, det viktigaste är name. När du skapar en parameter för att ange värdet för lagringskontots SKU använder du ett tydligt definierat namn, till exempel storageAccountSkuName. Om du använder det här värdet i stället för ett allmänt namn som sku eller skuName hjälper det andra att förstå syftet med parametern och effekterna av att ange dess värde.

Standardvärden är ett viktigt sätt att göra mallen användbar av andra. Det är viktigt att använda standardvärden där de är meningsfulla. De hjälper mallens användare på två sätt:

• Standardvärden förenklar distributionen av mallen. Om parametrarna har bra standardvärden som fungerar för de flesta av mallens användare kan användarna utelämna parametervärdena i stället för att ange dem varje gång de distribuerar mallen.
• Standardvärden ger ett exempel på hur du förväntar dig att parametervärdet ska se ut. Om mallanvändare behöver välja ett annat värde kan standardvärdet ge användbara tips om hur deras värde ska se ut.

Bicep kan också hjälpa till att verifiera de indata som användarna tillhandahåller via parameterdekoratörer. Du kan använda dessa dekoratörer för att ange en parameterbeskrivning eller för att ange vilka typer av värden som tillåts. Bicep innehåller flera typer av parameterdekoratörer:

• Beskrivningar ger läsbar information om syftet med parametern och effekterna av att ange dess värde.

• Värdebegränsningar tillämpar gränser för vad användare kan ange för parameterns värde. Du kan ange en lista med specifika, tillåtna värden med hjälp av dekoratören @allowed() . Du kan använda dekoratörerna @minValue() och @maxValue() för att framtvinga lägsta och högsta värden för numeriska parametrar, och du kan använda dekoratörerna @minLength() och @maxLength() för att framtvinga längden på sträng- och matrisparametrar.

  Dricks

  Var försiktig när du använder parameterdekoratören @allowed() för att ange SKU:er. Azure-tjänster lägger ofta till nya SKU:er och du vill inte att mallen i onödan ska förbjuda användningen. Överväg att använda Azure Policy för att framtvinga användningen av specifika SKU:er och använda dekoratören @allowed() med SKU:er endast när det finns funktionella skäl till varför mallens användare inte bör välja en specifik SKU. De funktioner som mallen behöver kanske inte är tillgängliga i den SKU:n. Förklara detta med hjälp av en @description() dekoratör eller kommentar som gör orsakerna tydliga för alla i framtiden.

• Metadata, även om de inte används ofta, kan användas för att tillhandahålla extra anpassade metadata om parametern.

Hur flexibel ska en Bicep-fil vara?

Ett av målen med att definiera infrastrukturen som kod är att göra mallarna återanvändbara och flexibla. Du vill inte skapa mallar för en enda användning som har en hårdkodad konfiguration. Å andra sidan är det inte meningsfullt att exponera alla resursegenskaper som parametrar. Skapa mallar som fungerar för ditt specifika affärsproblem eller din lösning, inte allmänna mallar som måste fungera för varje situation. Du vill inte heller ha så många parametrar att det tar lång tid att ange värdena innan du kan distribuera mallen. Detta är särskilt viktigt när du konfigurerar SKU:er och antalet instanser av resurser.

När du planerar en mall bör du fundera på hur du ska balansera flexibilitet med enkelhet. Det finns två vanliga sätt att ange parametrar i mallar:

• Ange konfigurationsalternativ för fritt formulär
• Använda fördefinierade konfigurationsuppsättningar

Låt oss överväga båda metoderna med hjälp av en Bicep-exempelfil som distribuerar ett lagringskonto och en Azure App Service-plan.

Ange konfigurationsalternativ för fritt formulär

Både App Service-planen och lagringskontot kräver att du anger deras SKU:er. Du kan överväga att skapa en uppsättning parametrar för att styra var och en av SKU:erna och antalet instanser för resurserna:

Så här ser det ut i 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
  }
}

Det här formatet ger störst flexibilitet eftersom alla som använder mallen kan ange valfri kombination av parametervärden. Men när du lägger till fler resurser behöver du fler parametrar. Därför blir mallen mer komplicerad. Du kan också behöva begränsa vissa kombinationer av parametrar eller se till att en annan resurs måste distribueras med hjälp av en annan SKU när en specifik resurs distribueras med hjälp av en annan SKU. Om du anger för många separata parametrar är det svårt att tillämpa dessa regler.

param appServicePlanSku object = {
  name: 'S1'
  capacity: 2
}

Använda fördefinierade konfigurationsuppsättningar

Du kan också ange en konfigurationsuppsättning: en enskild parameter, vars värde är en begränsad lista över tillåtna värden, till exempel en lista över miljötyper. När användarna distribuerar mallen måste de välja ett värde för endast den här parametern. När de väljer ett värde för parametern ärver distributionen automatiskt en uppsättning konfiguration:

Parameterdefinitionen ser ut så här:

@allowed([
  'Production'
  'Test'
])
param environmentType string = 'Test'

Konfigurationsuppsättningar ger lägre flexibilitet eftersom personer som distribuerar mallen inte kan ange storlekar för enskilda resurser, men du kan verifiera varje uppsättning konfigurationer och se till att de passar dina krav. Med hjälp av konfigurationsuppsättningar minskar behovet för mallens användare att förstå alla olika alternativ som är tillgängliga för varje resurs, och det blir lättare att stödja, testa och felsöka dina mallar.

När du arbetar med konfigurationsuppsättningar skapar du en mappningsvariabel för att definiera de specifika egenskaper som ska anges för olika resurser, baserat på parametervärdet:

var environmentConfigurationMap = {
  Production: {
    appServicePlan: {
      sku: {
        name: 'P2V3'
        capacity: 3
      }
    }
    storageAccount: {
      sku: {
        name: 'ZRS'
      }
    }
  }
  Test: {
    appServicePlan: {
      sku: {
        name: 'S2'
        capacity: 1
      }
    }
    storageAccount: {
      sku: {
        name: 'LRS'
      }
    }
  }
}

Resursdefinitionerna använder sedan konfigurationskartan för att definiera resursegenskaperna:

resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
  name: appServicePlanName
  location: location
  sku: environmentConfigurationMap[environmentType].appServicePlan.sku
}

Konfigurationsuppsättningar kan hjälpa dig att göra komplexa mallar mer lättillgängliga. De kan också hjälpa dig att tillämpa dina egna regler och uppmuntra till användning av fördefinierade konfigurationsvärden.

Hur namnges dina resurser?

I Bicep är det viktigt att ge dina resurser meningsfulla namn. Resurser i Bicep har två namn:

• Symboliska namn används endast i Bicep-filen och visas inte på dina Azure-resurser. Symboliska namn hjälper användare som läser eller ändrar mallen att förstå syftet med en parameter, variabel eller resursdefinition, och de hjälper användarna att fatta välgrundade beslut om huruvida mallen ska ändras.

• Resursnamn är namnen på de resurser som skapas i Azure. Många resurser har begränsningar för sina namn och många kräver att deras namn är unika.

Symboliska namn

Det är viktigt att tänka på de symboliska namn som du använder för dina resurser. Anta att du har kollegor som behöver ändra mallen. Kommer de att förstå vad varje resurs är till för?

Anta till exempel att du vill definiera ett lagringskonto som innehåller produkthandböcker som användarna kan ladda ned från din webbplats. Du kan ge resursen ett symboliskt namn på (till exempel) storageAccount, men om den finns i en Bicep-fil som innehåller många andra resurser, och kanske även andra lagringskonton, är det namnet inte tillräckligt beskrivande. I stället kan du ge det ett symboliskt namn som innehåller viss information om dess syfte, till exempel productManualStorageAccount.

I Bicep använder du vanligtvis camelCase-versaler för namnen på parametrar, variabler och symboliska resursnamn. Det innebär att du använder en gemen första bokstav för det första ordet och sedan versalerar den första bokstaven i de andra orden (som i föregående exempel, productManualStorageAccount). Du behöver inte använda camelCase. Om du väljer att använda ett annat format är det viktigt att komma överens om en standard i ditt team och använda den konsekvent.

Resursnamn

Varje Azure-resurs har ett namn. Namn utgör en del av resursens identifierare. I många fall representeras de också som de värdnamn som du använder för att komma åt resursen. När du till exempel skapar en App Service-app med namnet myappblir myapp.azurewebsites.netvärdnamnet som du använder för att komma åt appen . Du kan inte byta namn på resurser när de har distribuerats.

Det är viktigt att tänka på hur du namnger dina Azure-resurser. Många organisationer definierar sin egen namngivningskonvention för resurser. Cloud Adoption Framework för Azure har specifik vägledning som kan hjälpa dig att definiera din. Syftet med en namngivningskonvention för resurser är att hjälpa alla i din organisation att förstå vad varje resurs är till för.

Dessutom har varje Azure-resurs vissa namngivningsregler och begränsningar. Det finns till exempel begränsningar kring namnlängden, vilka tecken de kan inkludera och om namn måste vara globalt unika eller bara unika i en resursgrupp.

Det kan vara komplicerat att följa alla namngivningskonventioner för din organisation samt namngivningskraven för Azure. En välskriven Bicep-mall bör dölja den här komplexiteten för användarna och automatiskt fastställa namnen på resurserna. Här är ett exempel på en metod att följa:

• Lägg till en parameter som används för att skapa ett suffix för unikhet. Detta hjälper till att säkerställa att dina resurser har unika namn. Det är en bra idé att använda uniqueString() funktionen för att generera ett standardvärde. Personer som distribuerar mallen kan åsidosätta detta med ett specifikt värde om de vill ha ett meningsfullt namn. Se till att använda dekoratören @maxLength() för att begränsa längden på det här suffixet så att resursnamnen inte överskrider deras maximala längd.

  Dricks

  Det är bättre att använda unika suffix i stället för prefix. Den här metoden gör det enklare att sortera och snabbt genomsöka resursnamnen. Vissa Azure-resurser har också begränsningar för namnets första tecken, och slumpmässigt genererade namn kan ibland bryta mot dessa begränsningar.

• Använd variabler för att konstruera resursnamn dynamiskt. Din Bicep-kod kan se till att namnen som genereras följer organisationens namngivningskonvention samt Azure-krav. Inkludera suffixet uniqueness som en del av resursnamnet.

  Kommentar

  Alla resurser kräver inte ett globalt unikt namn. Fundera på om du inkluderar suffixet uniqueness i namnen på varje resurs eller bara de som behöver den.