Hantera skillnader mellan miljöer med hjälp av Bicep-parametrar

7 minuter

Du har redan lärt dig om Bicep-parametrar. De hjälper dig att ange värden som kan ändras mellan distributioner av dina Bicep-filer.

Parametrar används ofta för att stödja skillnaderna mellan dina miljöer. I dina icke-produktionsmiljöer vill du till exempel ofta distribuera billiga SKU:er för dina Azure-resurser. I produktion vill du distribuera SKU:er som har bättre prestanda. Och du kanske vill använda olika namn för resurser i varje miljö.

När du distribuerar Bicep-filen anger du värden för varje parameter. Det finns flera alternativ för hur du anger värdena för varje parameter från pipelinen och hur du anger separata värden för varje miljö. I den här lektionen får du lära dig mer om metoderna för att ange Bicep-parametervärden i en distributionspipeline.

Parameterfiler

En parameterfil är en JSON-formaterad fil som visar de parametervärden som du vill använda för varje miljö. Du skickar parameterfilen till Azure Resource Manager när du skickar distributionen.

Här är en exempelparameterfil:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "reviewApiUrl": {
      "value": "https://sandbox.contoso.com/reviews"
    }
  }
}

Parameterfiler kan checkas in på din Git-lagringsplats tillsammans med din Bicep-fil. Du kan sedan referera till parameterfilen i pipelinemallen där du kör distributionen.

Det är en bra idé att upprätta en konsekvent strategi för miljönamngivning för parameterfiler. Du kan till exempel namnge parametrarna för parameterfiler . ENVIRONMENT_NAME.json, till exempel parametrar. Production.json. Sedan kan du använda en pipelinemallparameter för att automatiskt välja rätt parameterfil.

parameters: 
- name: environmentType
  type: string
- name: serviceConnectionName
  type: string
- name: resourceGroupName
  type: string

- stage: Deploy
  jobs:
  - deployment: DeployWebsite
    displayName: Deploy Website
    environment: Website
    strategy:
      runOnce:
        deploy:
          steps:
            - checkout: self
            - task: AzureCLI@2
              name: DeployBicepFile
              displayName: Deploy Bicep file
              inputs:
                azureSubscription: ${{parameters.serviceConnectionName}}
                scriptType: 'bash'
                scriptLocation: 'inlineScript'
                inlineScript: |
                  az deployment group create \
                    --resource-group ${{parameters.resourceGroupName}} \
                    --template-file deploy/main.bicep \
                    --parameters deploy/azuredeploy.parameters.${{parameters.environmentType}}.json

När du använder parameterfiler behöver dina YAML-pipelinefiler inte innehålla en lista med parametrar som behöver skickas till distributionsstegen individuellt. Detta är användbart när du har ett stort antal parametrar.

En parameterfil håller ihop parametervärdena i en enda JSON-fil. Parameterfilerna är också en del av din Git-lagringsplats, så att de kan få versionshantering på samma sätt som all annan kod.

Viktigt!

Parameterfiler ska inte användas för säkra värden. Det finns inget sätt att skydda värdena för hemligheterna i parameterfilerna och du bör aldrig checka in hemligheter till din Git-lagringsplats.

Pipeline-variabler

Med Azure Pipelines kan du lagra pipelinevariabler, som är användbara för värden som kan skilja sig åt mellan miljöer. De är också användbara för värden som du bara vill definiera en gång och sedan återanvända i hela pipelinen. Azure Pipelines stöder flera sätt att definiera variabler.

Variabler som definierats i en YAML-fil

Du kan definiera variabler och ange deras värden i en YAML-fil. Detta är användbart när du behöver återanvända samma värde flera gånger. Men precis som Bicep-parameterfiler är YAML-filer inte lämpliga för hemligheter.

Variabler som definierats i webbgränssnittet

Du kan definiera variabler med hjälp av Azure DevOps-webbgränssnittet. Du kan ändra variabelvärdena när som helst och pipelinen läser de uppdaterade värdena nästa gång den körs.

Variabler som definieras via webbgränssnittet kan markeras som hemlighet, vilket talar om för Azure Pipelines att försöka dölja variablernas värden i pipelineloggarna. Det innebär att du kan lagra värden som Bicep-filen sedan accepterar som parametrar med dekoratören @secure() .

Varning

Som standard fördunklar Azure Pipelines hemliga variabelvärden i pipelineloggar, men du måste också följa god praxis. Dina pipelinesteg har åtkomst till alla variabelvärden, inklusive hemligheter. Om din pipeline innehåller ett steg som inte hanterar en säker variabel på ett säkert sätt finns det en risk att den hemliga variabeln visas i pipelineloggarna.

Variabelgrupper

Du kan också definiera variabelgrupper, som är uppsättningar med variabler. Precis som variabler definierar du dessa grupper med hjälp av Azure DevOps-webbgränssnittet. Du kan också använda variabelgrupper för att lagra hemligheter på ett säkert sätt. Variabelgrupper kan till och med återanvändas i flera pipelines i samma Azure DevOps-projekt.

Till skillnad från andra variabler måste du uttryckligen importera en variabelgrupp till en pipeline med hjälp av nyckelordet group i ett variables avsnitt, så här:

variables:
- group: MyVariableGroup

När du arbetar med pipelinemallar kan du namnge dina variabelgrupper så att du enkelt kan läsa in dem med hjälp av en mallparameter. Anta till exempel att din pipeline distribueras till två miljöer och att du behöver definiera en uppsättning variabler för varje miljö. Du kan namnge dina variabelgrupper med de miljönamn som ingår, så här:

Miljönamn	Namn på variabelgrupp
Testa	`ToyWebsiteTest`
Produktion	`ToyWebsiteProduction`

I var och en av dessa variabelgrupper lägger du till variabler med samma namn men med olika värden för varje miljö.

Pipelinemallfilen använder makrot {{ parameters.PARAMETER_NAME }} för att välja rätt variabelgrupp som ska importeras:

parameters: 
- name: environmentType
  type: string
  default: 'Test'

variables: 
- group: ToyWebsite${{ parameters.environmentType }}

Key Vault-variabelgrupper

Du kan länka variabelgrupper till Azure Key Vault. Hemligheter i nyckelvalvet görs tillgängliga som variabler i variabelgruppen. Hemligheterna kan sedan användas i dina pipelines som om de vore normala variabler.

Key Vault gör hanteringen av dina hemligheter säkrare. Det gör också att dessa värden kan hanteras av ditt säkerhetsteam och att separera åtkomsten till dina pipelines från de hemligheter som används.

Fler steg krävs för att länka en variabelgrupp till ett nyckelvalv. De här stegen omfattar att skapa en tjänstanslutning som har behörighet att läsa hemligheterna från nyckelvalvet. I sammanfattningsenheten tillhandahåller vi en länk till mer information om hur du konfigurerar Key Vault-variabelgrupper.

Använda variabler i pipelinen

Oavsett hur du definierar en variabel får du åtkomst till dess värde i pipelinen med hjälp av syntaxen $(VariableName) . När du till exempel kör en Bicep-distribution kan du använda en variabel för att ange värdet för en parameter:

- stage: Deploy
  jobs:
  - deployment: DeployWebsite
    displayName: Deploy Website
    environment: Website
    strategy:
      runOnce:
        deploy:
          steps:
            - checkout: self
            - task: AzureCLI@2
              name: DeployBicepFile
              displayName: Deploy Bicep file
              inputs:
                azureSubscription: MyServiceConnection
                scriptType: 'bash'
                scriptLocation: 'inlineScript'
                inlineScript: |
                  az deployment group create \
                    --resource-group $(ResourceGroupName) \
                    --template-file deploy/main.bicep \
                    --parameters environmentType=$(EnvironmentType)

Vilken är den bästa metoden?

Du har lärt dig om flera sätt att hantera de parametrar som din Bicep-fil behöver för distributionen. Det är bra att förstå när du kan använda vilken metod.

Undvik onödiga parametrar

Parametrar hjälper dig att göra dina Bicep-filer återanvändbara, men det är enkelt att definiera för många parametrar. När du distribuerar en Bicep-fil måste du ange ett värde för varje parameter. I komplexa distributioner mot flera miljöer blir det svårt att hantera en stor uppsättning enskilda parametervärden.

Överväg att göra parametrar valfria där du kan och använd standardvärden som gäller för de flesta av dina miljöer. Du kan sedan undvika behovet av att dina pipelines skickar in värden för parametrarna.

Tänk också på att parametrar ofta används i Bicep när resurser behöver ansluta till andra resurser. Om du till exempel har en webbplats som behöver ansluta till ett lagringskonto måste du ange lagringskontots namn och åtkomstnyckel. Nycklar är säkra värden. Tänk dock på dessa andra metoder när du distribuerar den här kombinationen av resurser:

Använd webbplatsens hanterade identitet för att komma åt lagringskontot. När du skapar en hanterad identitet genererar och hanterar Azure automatiskt sina autentiseringsuppgifter. Den här metoden förenklar anslutningsinställningarna. Det innebär också att du inte behöver hantera hemligheter alls, så det är det säkraste alternativet.
Distribuera lagringskontot och webbplatsen tillsammans i samma Bicep-mall. Använd Bicep-moduler för att hålla ihop webbplatsen och lagringsresurserna. Sedan kan du automatiskt leta upp värdena för lagringskontots namn och nyckeln i Bicep-koden i stället för att skicka in parametrar.
Lägg till lagringskontots information i ett nyckelvalv som en hemlighet. Webbplatskoden läser sedan in åtkomstnyckeln direkt från valvet. Den här metoden undviker behovet av att hantera nyckeln i pipelinen alls.

Använda variabelgrupper för små uppsättningar parametrar

Om du bara har några få parametrar för dina Bicep-filer kan du överväga att använda en variabelgrupp. Du kan lagra både hemliga och icke-hemliga värden i variabelgrupper.

Använda parameterfiler för stora uppsättningar parametrar

Om du har en stor uppsättning parametrar för dina Bicep-filer kan du överväga att använda parameterfiler för att hålla ihop de icke-säkra värdena för varje miljö. När du sedan behöver ändra värdena kan du uppdatera en parameterfil och checka in ändringen.

Den här metoden gör pipelinestegen enklare eftersom du inte behöver ange värdet för varje parameter uttryckligen.

Lagra hemligheter på ett säkert sätt

Använd en lämplig process för att lagra och hantera hemligheter. Om du bara har några hemligheter att hantera fungerar Azure Pipelines-variabler och variabelgrupper ofta bra. Men du kan ha mer komplexa krav, till exempel ett stort antal hemligheter, många olika miljöer eller begränsningar för åtkomstkontroll. För dessa situationer bör du överväga att lagra hemligheterna för varje miljö i separata nyckelvalv. Använd variabelgrupper för att länka valven till din pipeline.

Kom ihåg att uttryckligen skicka varje parameter till distributionsstegen för säkra parametrar.

Kombinera metoder

Det är vanligt att kombinera flera metoder för att hantera dina parametrar. Du kan till exempel lagra de flesta av dina parametervärden i parameterfiler och sedan ange säkra värden med hjälp av en variabelgrupp. I följande exempel visas kombinationen:

variables:
- group: MyVariableGroup # This group imports a parameter named MySecureParameter.

stages:

- stage: Deploy
  jobs:
  - deployment: DeployWebsite
    displayName: Deploy Website
    environment: Website
    strategy:
      runOnce:
        deploy:
          steps:
            - checkout: self
            - task: AzureCLI@2
              name: DeployBicepFile
              displayName: Deploy Bicep file
              inputs:
                azureSubscription: MyServiceConnection
                scriptType: 'bash'
                scriptLocation: 'inlineScript'
                inlineScript: |
                  az deployment group create \
                    --resource-group ${{parameters.resourceGroupName}} \
                    --template-file deploy/main.bicep \
                    --parameters deploy/azuredeploy.parameters.${{parameters.environmentName}}.json \
                                 mySecureParameter=$(MySecureParameter)

Det finns särskilda regler för hur tjänstanslutningsnamn kan anges. Dessa regler kan påverka hur du använder namn i pipelines som distribueras till flera miljöer. Du kan till exempel inte använda en variabel som definierats i en variabelgrupp för att ange ett namn på tjänstanslutningen. Du kan använda parametrar för pipelinemallar för att ange namnet på tjänstanslutningen som ska användas.