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 arbetsflödet 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 ett distributionsarbetsflöde.

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 arbetsflödesmallen 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 indata för en arbetsflödesmall för att automatiskt välja rätt parameterfil baserat på ett indatavärde.

on:
  workflow_call:
    inputs:
      environmentType:
        required: true
        type: string
      # ...

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    # ...
    - uses: azure/arm-deploy@v1
      with:
        failOnStdErr: false
        resourceGroupName: ${{ inputs.resourceGroupName }}
        template: ./deploy/main.bicep
        parameters: ./deploy/azuredeploy.parameters.${{ inputs.environmentType }}.json

När du använder parameterfiler behöver dina YAML-arbetsflödesfiler inte innehålla en lista med parametrar som måste skickas till distributionsstegen individuellt. Detta är särskilt 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.

Arbetsflödesvariabler

Med GitHub Actions kan du lagra arbetsflödesvariabler, 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 arbetsflödet.

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. Du kan definiera en variabel för ett helt arbetsflöde, ett jobb eller ett enda steg:

env:
  MyVariable1: value1

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      MyVariable2: value2
    steps:
    - run: echo Hello world!
      env:
        MyVariable3: value3

Hemligheter som definierats i webbgränssnittet

Precis som Bicep-parameterfiler är YAML-filer inte lämpliga för hemligheter. I stället kan du definiera hemligheter med hjälp av GitHub-webbgränssnittet. Du kan ändra variabelvärdena när som helst och arbetsflödet läser de uppdaterade värdena nästa gång det körs. GitHub Actions försöker dölja hemligheternas värden i arbetsflödesloggarna. Det innebär att du kan lagra värden som Bicep-filen sedan accepterar som parametrar med dekoratören @secure() .

När du skapar en hemlighet kan du med GitHub välja om du vill begränsa den till hela Git-lagringsplatsen eller till en specifik miljö. Hemligheter med miljöomfattning följer de skyddsregler som du konfigurerar i dina miljöer, så om du konfigurerar en obligatorisk granskningsregel kan ett arbetsflöde inte komma åt hemligheterna förrän den angivna GitHub-användaren har godkänt din pipeline för distribution till den miljön.

Hemligheter med miljöomfattning kan vara till hjälp, men de fungerar inte enkelt med Azure Resource Manager:s validering före start eller konsekvensåtgärder. Dessa åtgärder måste kommunicera med Azure, vilket innebär att de behöver en arbetsbelastningsidentitet. Du vill vanligtvis ge distributionsgodkännande efter att förhandsvalidering eller konsekvensåtgärder har slutförts, så att du men har en hög grad av förtroende för de ändringar som du distribuerar. Så om du använder hemligheter med miljöomfattning sker den mänskliga granskningsprocessen för tidigt i arbetsflödet.

Därför använder du inte miljöomfattningshemligheter i den här modulens övningar. I stället skapar du lagringsplatsomfattande hemligheter med förutsägbara namn som innehåller miljönamnet. Detta gör att arbetsflödet kan identifiera rätt hemlighet som ska användas för varje miljö. I dina egna arbetsflöden kan du välja att använda hemligheter med lagringsplatsomfattning, miljöomfattande hemligheter eller till och med en blandning av båda.

Använda variabler i arbetsflödet

Hur du kommer åt en variabels värde i arbetsflödet beror på typen av variabel.

Type	Syntax
Variabler som definierats i samma fil	${{ env.VARIABLE_NAME }}
Indata till ett kallat arbetsflöde	${{ inputs.INPUT_NAME }}
Hemligheter	${{ secrets.SECRET_NAME }}

När du till exempel kör en Bicep-distribution kan du använda hemligheter för att ange den Azure-arbetsbelastningsidentitet som ska användas, ett kallat arbetsflödesindata för att ange resursgruppens namn och en variabel för att ange värdet för en parameter:

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      MyParameter: value-of-parameter
    steps:
    - uses: actions/checkout@v3
    - uses: azure/login@v1
      with:
        client-id: ${{ secrets.AZURE_CLIENT_ID }}
        tenant-id: ${{ secrets.AZURE_TENANT_ID }}
        subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
    - uses: azure/arm-deploy@v1
      with:
        failOnStdErr: false
        resourceGroupName: ${{ inputs.resourceGroupName }}
        template: ./deploy/main.bicep
        parameters: myParameter=${{ env.MyParameter }}

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 arbetsflöden 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 arbetsflödet alls.

Använda arbetsflödesvariabler för små uppsättningar parametrar

Om du bara har några få parametrar för dina Bicep-filer kan du överväga att definiera variabler i YAML-filen.

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 arbetsflödesstegen enklare eftersom du inte uttryckligen behöver ange värdet för varje parameter.

Lagra hemligheter på ett säkert sätt

Använd en lämplig process för att lagra och hantera hemligheter. Använd GitHub-hemligheter för att lagra hemligheter på din GitHub-lagringsplats eller använda Key Vault för att lagra hemligheter i Azure.

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

GitHub kan automatiskt genomsöka lagringsplatsen efter hemligheter som har checkats in av misstag, så att du kan meddelas. Du kan sedan ta bort och rotera hemligheterna. Vi länkar till mer information om den här funktionen i sammanfattningen.

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 hemlighet. I följande exempel visas kombinationen:

on:
  workflow_dispatch:
    inputs:
      environmentType:
        required: true
        type: string
      resourceGroupName:
        required: true
        type: string
    secrets:
      AZURE_CLIENT_ID:
        required: true
      AZURE_TENANT_ID:
        required: true
      AZURE_SUBSCRIPTION_ID:
        required: true
      MySecureParameter:
        required: true

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - uses: azure/login@v1
      with:
        client-id: ${{ secrets.AZURE_CLIENT_ID }}
        tenant-id: ${{ secrets.AZURE_TENANT_ID }}
        subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
    - uses: azure/arm-deploy@v1
      with:
        failOnStdErr: false
        resourceGroupName: ${{ inputs.resourceGroupName }}
        template: ./deploy/main.bicep
        parameters: >
          ./deploy/azuredeploy.parameters.${{ inputs.environmentType }}.json
          mySecureParameter=${{ secrets.MySecureParameter }}