Verschillen tussen omgevingen afhandelen met bicep-parameters

  • 7 minuten

U hebt al geleerd over Bicep-parameters. Hiermee kunt u waarden opgeven die kunnen worden gewijzigd tussen implementaties van uw Bicep-bestanden.

Parameters worden vaak gebruikt ter ondersteuning van de verschillen tussen uw omgevingen. In uw niet-productieomgevingen wilt u bijvoorbeeld vaak goedkope SKU's van uw Azure-resources implementeren. In productie wilt u SKU's implementeren die betere prestaties hebben. En misschien wilt u verschillende namen gebruiken voor resources in elke omgeving.

Wanneer u uw Bicep-bestand implementeert, geeft u waarden op voor elke parameter. Er zijn verschillende opties voor het opgeven van de waarden voor elke parameter uit uw werkstroom en hoe u afzonderlijke waarden voor elke omgeving opgeeft. In deze les krijgt u informatie over de methoden voor het opgeven van Bicep-parameterwaarden in een implementatiewerkstroom.

Parameterbestanden

Een parameterbestand is een JSON-bestand met de parameterwaarden die u voor elke omgeving wilt gebruiken. U verzendt het parameterbestand naar Azure Resource Manager wanneer u de implementatie verzendt.

Hier volgt een voorbeeld van een parameterbestand:

{
  "$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"
    }
  }
}

Parameterbestanden kunnen worden doorgevoerd in uw Git-opslagplaats naast uw Bicep-bestand. U kunt vervolgens verwijzen naar het parameterbestand in uw werkstroomsjabloon waar u uw implementatie uitvoert.

Het is een goed idee om een consistente omgevingsnaamgevingsstrategie voor parameterbestanden tot stand te brengen. U kunt bijvoorbeeld de parameters van uw parameterbestanden een naam opgeven. ENVIRONMENT_NAME.json, zoals parameters. Production.json. Vervolgens kunt u een invoer voor een werkstroomsjabloon gebruiken om automatisch het juiste parameterbestand te selecteren op basis van een invoerwaarde.

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

Wanneer u parameterbestanden gebruikt, hoeven uw YAML-werkstroombestanden geen lijst met parameters te bevatten die afzonderlijk moeten worden doorgegeven aan uw implementatiestappen. Dit is vooral handig wanneer u een groot aantal parameters hebt.

Een parameterbestand houdt de parameterwaarden bij elkaar in één JSON-bestand. De parameterbestanden maken ook deel uit van uw Git-opslagplaats, zodat ze versiebeheer op dezelfde manier kunnen krijgen als al uw andere code.

Belangrijk

Parameterbestanden mogen niet worden gebruikt voor beveiligde waarden. Er is geen manier om de waarden van de geheimen in de parameterbestanden te beveiligen en u moet nooit geheimen doorvoeren in uw Git-opslagplaats.

Werkstroomvariabelen

Met GitHub Actions kunt u werkstroomvariabelen opslaan, wat handig is voor waarden die mogelijk verschillen tussen omgevingen. Ze zijn ook handig voor waarden die u slechts eenmaal wilt definiëren en vervolgens opnieuw gebruiken in uw werkstroom.

Variabelen die zijn gedefinieerd in een YAML-bestand

U kunt variabelen definiëren en hun waarden instellen in een YAML-bestand. Dit is handig wanneer u dezelfde waarde meerdere keren opnieuw moet gebruiken. U kunt een variabele definiëren voor een hele werkstroom, een taak of één stap:

env:
  MyVariable1: value1

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

Geheimen die zijn gedefinieerd in de webinterface

Net als Bicep-parameterbestanden zijn YAML-bestanden niet geschikt voor geheimen. In plaats daarvan kunt u geheimen definiëren met behulp van de GitHub-webinterface. U kunt de variabelewaarden op elk gewenst moment wijzigen en de werkstroom leest de bijgewerkte waarden de volgende keer dat deze wordt uitgevoerd. GitHub Actions probeert de waarden van de geheimen in de werkstroomlogboeken te verbergen. Dit betekent dat u waarden kunt opslaan die uw Bicep-bestand vervolgens accepteert als parameters met de @secure() decorator.

Waarschuwing

GitHub Actions verdooft standaard geheime variabelewaarden in werkstroomlogboeken, maar u moet ook goede procedures volgen. Uw werkstroomstappen hebben toegang tot de waarden van geheimen. Als uw werkstroom een stap bevat die geen geheim veilig afhandelt, is er een kans dat de geheime waarde mogelijk wordt weergegeven in de werkstroomlogboeken. U moet altijd zorgvuldig de wijzigingen in een werkstroomdefinitiebestand controleren om te controleren of de geheimen niet verkeerd worden verwerkt.

Wanneer u een geheim maakt, kunt u met GitHub kiezen of u deze wilt instellen op uw hele Git-opslagplaats of in een specifieke omgeving. Omgevingsgeheimen respecteren de beveiligingsregels die u configureert voor uw omgevingen. Als u dus een vereiste revisorregel configureert, heeft een werkstroom geen toegang tot de geheimenwaarden totdat de opgegeven GitHub-gebruiker uw pijplijn heeft goedgekeurd om in die omgeving te implementeren.

Geheimen binnen het bereik van de omgeving kunnen nuttig zijn, maar ze werken niet eenvoudig met de voorbereidende validatie of wat-als-bewerkingen van Azure Resource Manager. Deze bewerkingen moeten communiceren met Azure, wat betekent dat ze een workloadidentiteit nodig hebben. Over het algemeen wilt u implementatiegoedkeuring opgeven nadat de voorbereidende validatie of wat-als-bewerkingen zijn voltooid, zodat u wel een hoge mate van vertrouwen hebt in de wijzigingen die u implementeert. Dus als u geheimen binnen het bereik van de omgeving gebruikt, gebeurt het menselijke beoordelingsproces te vroeg in uw werkstroom.

Daarom gebruikt u in de oefeningen van deze module geen geheimen met omgevingsbereik. In plaats daarvan maakt u geheimen binnen het bereik van de opslagplaats met voorspelbare namen die de omgevingsnaam bevatten. Hierdoor kan uw werkstroom het juiste geheim identificeren dat voor elke omgeving moet worden gebruikt. In uw eigen werkstromen kunt u ervoor kiezen om geheimen met opslagplaatsbereik, geheimen met omgevingsbereik of zelfs een combinatie van beide te gebruiken.

Notitie

U kunt ook geheimen opgeven voor GitHub-organisaties. Hoewel dit niet binnen het bereik van deze module valt, wordt er een koppeling gemaakt naar meer informatie in de samenvatting.

Variabelen gebruiken in uw werkstroom

De manier waarop u toegang krijgt tot de waarde van een variabele in uw werkstroom, is afhankelijk van het type variabele.

Type Syntaxis
Variabelen die in hetzelfde bestand zijn gedefinieerd ${{ env.VARIABLE_NAME }}
Invoer in een aangeroepen werkstroom ${{ inputs.INPUT_NAME }}
Geheimen ${{ secrets.SECRET_NAME }}

Wanneer u bijvoorbeeld een Bicep-implementatie uitvoert, kunt u geheimen gebruiken om de Azure-workloadidentiteit op te geven die moet worden gebruikt, een zogenaamde werkstroominvoer om de naam van de resourcegroep op te geven en een variabele om de waarde van een parameter op te geven:

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 }}

Wat is de beste aanpak?

U hebt geleerd over verschillende manieren om de parameters te verwerken die uw Bicep-bestand nodig heeft voor uw implementatie. Het is handig om te begrijpen wanneer u mogelijk welke benadering gebruikt.

Vermijd onnodige parameters

Met parameters kunt u uw Bicep-bestanden herbruikbaar maken, maar het is eenvoudig om te veel parameters te definiëren. Wanneer u een Bicep-bestand implementeert, moet u een waarde opgeven voor elke parameter. Bij complexe implementaties voor meerdere omgevingen is het lastig om een grote set afzonderlijke parameterwaarden te beheren.

U kunt desgewenst parameters maken en standaardwaarden gebruiken die van toepassing zijn op de meeste van uw omgevingen. U kunt dan voorkomen dat uw werkstromen waarden voor de parameters moeten doorgeven.

Houd er ook rekening mee dat parameters vaak worden gebruikt in Bicep wanneer resources verbinding moeten maken met andere resources. Als u bijvoorbeeld een website hebt die verbinding moet maken met een opslagaccount, moet u de naam en toegangssleutel van het opslagaccount opgeven. Sleutels zijn veilige waarden. Houd echter rekening met deze andere benaderingen wanneer u deze combinatie van resources implementeert:

  • Gebruik de beheerde identiteit van de website om toegang te krijgen tot het opslagaccount. Wanneer u een beheerde identiteit maakt, genereert en beheert Azure automatisch de referenties. Deze aanpak vereenvoudigt de verbindingsinstellingen. Het betekent ook dat u helemaal geen geheimen hoeft af te handelen, dus het is de veiligste optie.
  • Implementeer het opslagaccount en de website samen in dezelfde Bicep-sjabloon. Gebruik Bicep-modules om de website en opslagbronnen bij elkaar te houden. Vervolgens kunt u de waarden voor de naam van het opslagaccount en de sleutel in de Bicep-code automatisch opzoeken in plaats van parameters door te geven.
  • Voeg de gegevens van het opslagaccount als geheim toe aan een sleutelkluis. De websitecode laadt vervolgens de toegangssleutel rechtstreeks vanuit de kluis. Deze aanpak voorkomt dat u de sleutel in de werkstroom helemaal hoeft te beheren.

Werkstroomvariabelen gebruiken voor kleine sets parameters

Als u slechts enkele parameters voor uw Bicep-bestanden hebt, kunt u overwegen variabelen in uw YAML-bestand te definiëren.

Parameterbestanden gebruiken voor grote sets parameters

Als u een grote set parameters voor uw Bicep-bestanden hebt, kunt u overwegen parameterbestanden te gebruiken om de niet-beveiligde waarden voor elke omgeving bij elkaar te houden. Wanneer u vervolgens de waarden wilt wijzigen, kunt u een parameterbestand bijwerken en uw wijziging doorvoeren.

Deze aanpak zorgt ervoor dat uw werkstroomstappen eenvoudiger worden, omdat u de waarde voor elke parameter niet expliciet hoeft in te stellen.

Geheimen veilig opslaan

Gebruik een geschikt proces voor het opslaan en verwerken van geheimen. Gebruik GitHub-geheimen om geheimen op te slaan in uw GitHub-opslagplaats of gebruik Key Vault om geheimen op te slaan in Azure.

Vergeet niet om voor beveiligde parameters elke parameter expliciet door te geven aan uw implementatiestappen.

GitHub kan uw opslagplaats automatisch scannen op geheimen die per ongeluk zijn doorgevoerd, zodat u hiervan op de hoogte kunt worden gesteld. Vervolgens kunt u de geheimen verwijderen en draaien. In de samenvatting vindt u een koppeling naar meer informatie over deze functie.

Benaderingen combineren

Het is gebruikelijk om meerdere benaderingen te combineren voor het afhandelen van uw parameters. U kunt bijvoorbeeld de meeste parameterwaarden opslaan in parameterbestanden en vervolgens veilige waarden instellen met behulp van een geheim. In het volgende voorbeeld ziet u de combinatie:

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 }}

Tip

Aan het einde van dit voorbeeld wordt de parameters waarde opgegeven als een YAML-tekenreeks met meerdere regels met behulp van het > teken. Hierdoor is het YAML-bestand gemakkelijker te lezen. Het is gelijk aan het opnemen van de volledige waarde op één regel.