Håndter forskelle mellem miljøer ved hjælp af Bicep-parametre

  • 7 minutter

Du har allerede lært om Bicep-parametre. De hjælper dig med at angive værdier, der kan ændres mellem udrulninger af dine Bicep-filer.

Parametre bruges ofte til at understøtte forskellene mellem dine miljøer. I dine ikke-produktionsmiljøer vil du f.eks. ofte udrulle billige SKU'er af dine Azure-ressourcer. I produktionen vil du udrulle SKU'er, der har en bedre ydeevne. Og det kan være en god idé at bruge forskellige navne til ressourcer i hvert miljø.

Når du installerer din Bicep-fil, angiver du værdier for hver parameter. Der er flere muligheder for, hvordan du angiver værdierne for hver parameter fra arbejdsprocessen, og hvordan du angiver separate værdier for hvert miljø. I dette undermodul får du mere at vide om metoderne til angivelse af Bicep-parameterværdier i en udrulningsarbejdsproces.

Parameterfiler

En parameterfil er en JSON-formateret fil, der viser de parameterværdier, du vil bruge til hvert miljø. Du sender parameterfilen til Azure Resource Manager, når du sender udrulningen.

Her er et eksempel på en parameterfil:

{
  "$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 sendes til dit Git-lager sammen med din Bicep-fil. Du kan derefter se parameterfilen i arbejdsprocesskabelonen, hvor du udfører installationen.

Det er en god idé at etablere en ensartet strategi for navngivning af miljø for parameterfiler. Du kan f.eks. navngive parameterfilerne parameters.ENVIRONMENT_NAME.json, f.eks. parameters.Production.json. Derefter kan du bruge et input fra en arbejdsprocesskabelon til automatisk at vælge den korrekte parameterfil baseret på en inputværdi.

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 bruger parameterfiler, behøver dine YAML-arbejdsprocesfiler ikke at indeholde en liste over parametre, der skal overføres til dine installationstrin enkeltvist. Dette er især nyttigt, når du har et stort antal parametre.

En parameterfil holder parameterværdierne samlet i en enkelt JSON-fil. Parameterfilerne er også en del af dit Git-lager, så de kan blive versioneret på samme måde som al din anden kode.

Vigtig

Parameterfiler bør ikke bruges til sikre værdier. Det er ikke muligt at beskytte værdierne for hemmelighederne i parameterfilerne, og du bør aldrig sende hemmeligheder til dit Git-lager.

Arbejdsprocesvariabler

Med GitHub-handlinger kan du gemme arbejdsprocesvariabler, hvilket er nyttigt for værdier, der kan være forskellige mellem miljøer. De er også nyttige til værdier, som du kun vil definere én gang og derefter genbruge i hele arbejdsprocessen.

Variabler, der er defineret i en YAML-fil

Du kan definere variabler og angive deres værdier i en YAML-fil. Dette er nyttigt, når du har brug for at genbruge den samme værdi flere gange. Du kan definere en variabel for en hel arbejdsproces, et job eller et enkelt trin:

env:
  MyVariable1: value1

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

Hemmeligheder, der er defineret i webgrænsefladen

Ligesom Bicep-parameterfiler er YAML-filer ikke egnede til hemmeligheder. Du kan i stedet definere hemmeligheder ved hjælp af GitHub-webgrænsefladen. Du kan når som helst ændre variabelværdierne, så læser arbejdsprocessen de opdaterede værdier, næste gang den køres. GitHub-handlinger forsøger at skjule hemmelighedernes værdier i arbejdsproceslogfilerne. Det betyder, at du kan gemme værdier, som din Bicep-fil derefter accepterer som parametre med @secure() dekoratøren.

Advarsel

Som standard slører GitHub-handlinger hemmelige variabelværdier i arbejdsproceslogge, men du skal også følge gode fremgangsmåder. Dine arbejdsprocestrin har adgang til værdierne for hemmeligheder. Hvis arbejdsprocessen indeholder et trin, der ikke håndterer en hemmelighed sikkert, er der risiko for, at den hemmelige værdi vises i arbejdsprocesloggene. Du skal altid omhyggeligt gennemse eventuelle ændringer af en arbejdsprocesdefinitionsfil for at kontrollere, at hemmelighederne ikke håndteres forkert.

Når du opretter en hemmelighed, giver GitHub dig mulighed for at vælge, om du vil tilpasse den til hele Git-lageret eller til et bestemt miljø. Miljøomfangede hemmeligheder ærer de beskyttelsesregler, du konfigurerer i dine miljøer, så hvis du konfigurerer en påkrævet regel for korrekturlæsere, kan en arbejdsproces ikke få adgang til hemmelighedernes værdier, før den angivne GitHub-bruger har godkendt din pipeline til installation i det pågældende miljø.

Miljøomfangede hemmeligheder kan være nyttige, men de fungerer ikke nemt sammen med Azure Resource Manager's forhåndsgodkendelse eller what if-handlinger. Disse handlinger skal kommunikere med Azure, hvilket betyder, at de har brug for en arbejdsbelastningsidentitet. Du vil generelt angive godkendelse af udrulning efter forhåndskontrollen eller what if-handlingerne er fuldført, så du, men har stor tillid til de ændringer, du udruller. Så hvis du bruger hemmeligheder, der er begrænset til miljøet, sker den menneskelige gennemgang for tidligt i din arbejdsproces.

Derfor bruger du ikke miljøbaserede hemmeligheder i øvelserne i dette modul. I stedet opretter du hemmeligheder med lagerområder med forudsigelige navne, der indeholder miljønavnet. Dette gør det muligt for din arbejdsproces at identificere den korrekte hemmelighed, der skal bruges til hvert miljø. I dine egne arbejdsprocesser kan du vælge at bruge lagerbaserede hemmeligheder, miljøbaserede hemmeligheder eller endda en blanding af begge.

Seddel

Du kan også bruge hemmeligheder til GitHub-organisationer. Selvom dette ikke er inden for dette moduls område, linker vi til flere oplysninger i oversigten.

Brug variabler i din arbejdsproces

Den måde, du får adgang til en variabels værdi i arbejdsprocessen på, afhænger af variabeltypen.

Slags Syntaks
Variabler, der er defineret i den samme fil ${{ env.VARIABLE_NAME }}
Input til en kaldet arbejdsproces ${{ inputs.INPUT_NAME }}
Hemmeligheder ${{ secrets.SECRET_NAME }}

Når du f.eks. kører en Bicep-installation, kan du bruge hemmeligheder til at angive den Azure-arbejdsbelastningsidentitet, der skal bruges, et kaldet arbejdsprocesinput til at angive navnet på ressourcegruppen og en variabel til at angive værdien af 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 }}

Hvad er den bedste tilgang?

Du har lært om flere måder at håndtere de parametre, som din Bicep-fil skal bruge til din installation. Det er nyttigt at forstå, hvornår du kan bruge hvilken fremgangsmåde.

Undgå unødvendige parametre

Parametre hjælper dig med at gøre dine Bicep-filer genbrugelige, men det er nemt at definere for mange parametre. Når du installerer en Bicep-fil, skal du angive en værdi for hver parameter. I komplekse udrulninger i forhold til flere miljøer bliver det svært at administrere et stort sæt individuelle parameterværdier.

Overvej at gøre parametre valgfrie, hvor du kan, og brug standardværdier, der gælder for de fleste af dine miljøer. Du kan derefter undgå behovet for, at dine arbejdsprocesser overfører værdier for parametrene.

Husk også, at parametre ofte bruges i Bicep, når ressourcer skal oprette forbindelse til andre ressourcer. Hvis du f.eks. har et websted, der skal oprette forbindelse til en lagerkonto, skal du angive navnet på lagerkontoen og adgangsnøglen. Nøgler er sikre værdier. Overvej dog disse andre metoder, når du udruller denne kombination af ressourcer:

  • Brug webstedets administrerede identitet til at få adgang til lagerkontoen. Når du opretter en administreret identitet, genererer og administrerer Azure automatisk sine legitimationsoplysninger. Denne fremgangsmåde forenkler forbindelsesindstillingerne. Det betyder også, at du ikke behøver at håndtere hemmeligheder overhovedet, så det er den mest sikre mulighed.
  • Udrul lagerkontoen og webstedet sammen i den samme Bicep-skabelon. Brug Bicep-moduler til at holde webstedet og lagerressourcerne samlet. Derefter kan du automatisk slå værdierne for lagerkontonavnet og nøglen op i Bicep-koden i stedet for at angive parametre.
  • Føj lagerkontoens oplysninger til en key vault som en hemmelighed. Webstedskoden indlæser derefter adgangsnøglen direkte fra vaulten. Denne fremgangsmåde undgår overhovedet behovet for at administrere nøglen i arbejdsprocessen.

Brug arbejdsprocesvariabler til små sæt parametre

Hvis du kun har nogle få parametre for dine Bicep-filer, kan du overveje at definere variabler i YAML-filen.

Brug parameterfiler til store sæt parametre

Hvis du har et stort sæt parametre til dine Bicep-filer, kan du overveje at bruge parameterfiler til at holde de ikke-sikre værdier sammen for hvert miljø. Når du derefter har brug for at ændre værdierne, kan du opdatere en parameterfil og bekræfte ændringen.

Denne fremgangsmåde gør trinnene i arbejdsprocessen enklere, fordi du ikke behøver at angive værdien for hver parameter eksplicit.

Gem hemmeligheder sikkert

Brug en passende proces til lagring og håndtering af hemmeligheder. Brug GitHub-hemmeligheder til at gemme hemmeligheder i dit GitHub-lager, eller brug Key Vault til at gemme hemmeligheder i Azure.

For sikre parametre skal du huske eksplicit at overføre hver parameter til dine installationstrin.

GitHub kan automatisk scanne dit lager for hemmeligheder, der er blevet bekræftet ved et uheld, så du kan få besked. Du kan derefter fjerne og rotere hemmelighederne. Vi linker til flere oplysninger om denne funktion i oversigten.

Kombiner tilgange

Det er almindeligt at kombinere flere metoder til håndtering af dine parametre. Du kan f.eks. gemme de fleste af dine parameterværdier i parameterfiler og derefter angive sikre værdier ved hjælp af en hemmelighed. I følgende eksempel illustreres 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 }}

Drikkepenge

I slutningen af dette eksempel angives værdien parameters som en YAML-flerlinjestreng ved hjælp af >-tegnet. Det gør det nemmere at læse YAML-filen. Det svarer til at inkludere hele værdien på en enkelt linje.