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 pijplijn en hoe u afzonderlijke waarden voor elke omgeving opgeeft. In deze les leert u meer over de methoden voor het opgeven van Bicep-parameterwaarden in een implementatiepijplijn.

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 pijplijnsjabloon 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 parameter voor een pijplijnsjabloon gebruiken om automatisch het juiste parameterbestand te selecteren.

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

Wanneer u parameterbestanden gebruikt, hoeven uw YAML-pijplijnbestanden geen lijst met parameters te bevatten die afzonderlijk moeten worden doorgegeven aan uw implementatiestappen. Dit is 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.

Pipeline-variabelen

Met Azure Pipelines kunt u pijplijnvariabelen 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 pijplijn. Azure Pipelines ondersteunt verschillende manieren om variabelen te definiëren.

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. Maar net als Bicep-parameterbestanden zijn YAML-bestanden niet geschikt voor geheimen.

Variabelen die zijn gedefinieerd in de webinterface

U kunt variabelen definiëren met behulp van de Azure DevOps-webinterface. U kunt de variabelewaarden op elk gewenst moment wijzigen en de pijplijn leest de bijgewerkte waarden de volgende keer dat deze wordt uitgevoerd.

Variabelen die zijn gedefinieerd via de webinterface, kunnen worden gemarkeerd als geheim, waardoor Azure Pipelines de waarden van de variabelen in de pijplijnlogboeken moet verbergen. Dit betekent dat u waarden kunt opslaan die uw Bicep-bestand vervolgens accepteert als parameters met de @secure() decorator.

Waarschuwing

Standaard verdoezelt Azure Pipelines geheime variabelewaarden in pijplijnlogboeken, maar u moet ook goede procedures volgen. Uw pijplijnstappen hebben toegang tot alle variabele waarden, inclusief geheimen. Als uw pijplijn een stap bevat waarmee een veilige variabele niet veilig wordt verwerkt, is het mogelijk dat de geheime variabele wordt weergegeven in de pijplijnlogboeken.

Variabelegroepen

U kunt ook variabelegroepen definiëren. Dit zijn sets met variabelen. Net als variabelen definieert u deze groepen met behulp van de Azure DevOps-webinterface. U kunt ook variabele groepen gebruiken om geheimen veilig op te slaan. Variabelegroepen kunnen zelfs opnieuw worden gebruikt in meerdere pijplijnen in hetzelfde Azure DevOps-project.

In tegenstelling tot andere variabelen moet u expliciet een variabelegroep importeren in een pijplijn met behulp van het group trefwoord in een variables sectie, zoals:

variables:
- group: MyVariableGroup

Wanneer u met pijplijnsjablonen werkt, kunt u uw variabelegroepen een naam opgeven, zodat u ze eenvoudig kunt laden met behulp van een sjabloonparameter. Stel dat uw pijplijn in twee omgevingen wordt geïmplementeerd en u een set variabelen voor elke omgeving moet definiëren. U kunt uw variabelegroepen een naam opgeven met de omgevingsnamen die zijn opgenomen, zoals hieronder:

Omgevingsnaam Naam van variabelegroep
Testen ToyWebsiteTest
Productie ToyWebsiteProduction

In elk van deze variabelegroepen voegt u variabelen met dezelfde namen toe, maar met verschillende waarden voor elke omgeving.

Uw pijplijnsjabloonbestand maakt gebruik van de {{ parameters.PARAMETER_NAME }} macro om de juiste variabelegroep te selecteren die u wilt importeren:

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

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

Key Vault-variabelegroepen

U kunt variabelegroepen koppelen aan Azure Key Vault. Geheimen in de sleutelkluis worden beschikbaar gesteld als variabelen in de variabelegroep. De geheimen kunnen vervolgens in uw pijplijnen worden gebruikt alsof ze normale variabelen zijn.

Key Vault maakt het beheer van uw geheimen veiliger. Hiermee kunnen deze waarden ook worden beheerd door uw beveiligingsteam en de toegang tot uw pijplijnen scheiden van de geheimen die worden gebruikt.

Er zijn meer stappen vereist om een variabelegroep te koppelen aan een sleutelkluis. Deze stappen omvatten het maken van een serviceverbinding die is gemachtigd om de geheimen uit de sleutelkluis te lezen. In de samenvattingseenheid geven we een koppeling naar meer informatie over het configureren van Key Vault-variabelegroepen.

Variabelen gebruiken in uw pijplijn

Ongeacht hoe u een variabele definieert, hebt u toegang tot de waarde in uw pijplijn met behulp van de $(VariableName) syntaxis. Wanneer u bijvoorbeeld een Bicep-implementatie uitvoert, kunt u een variabele gebruiken om de waarde van een parameter op te geven:

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

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 pijplijnen waarden voor de parameters 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 pijplijn helemaal hoeft te beheren.

Variabelegroepen gebruiken voor kleine sets parameters

Als u slechts enkele parameters voor uw Bicep-bestanden hebt, kunt u overwegen een variabele groep te gebruiken. U kunt zowel geheime als niet-geheime waarden opslaan in variabele groepen.

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 benadering zorgt ervoor dat uw pijplijnstappen 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. Als u slechts een paar geheimen hebt om te beheren, werken Azure Pipelines-variabelen en -variabelegroepen vaak goed. Maar mogelijk hebt u complexere vereisten, zoals een groot aantal geheimen, veel verschillende omgevingen of beperkingen voor toegangsbeheer. Voor deze situaties kunt u overwegen de geheimen voor elke omgeving op te slaan in afzonderlijke sleutelkluizen. Gebruik variabele groepen om de kluizen aan uw pijplijn te koppelen.

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

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 beveiligde waarden instellen met behulp van een variabelegroep. In het volgende voorbeeld ziet u de combinatie:

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)

Er zijn speciale regels voor de wijze waarop serviceverbindingsnamen kunnen worden opgegeven. Deze regels kunnen van invloed zijn op de wijze waarop u namen gebruikt in pijplijnen die in meerdere omgevingen worden geïmplementeerd. U kunt bijvoorbeeld geen variabele gebruiken die is gedefinieerd in een variabelegroep om een serviceverbindingsnaam op te geven. U kunt pijplijnsjabloonparameters gebruiken om de naam op te geven van de serviceverbinding die u wilt gebruiken.