Gestire le differenze tra ambienti usando i parametri di Bicep

7 minuti

Sono già stati illustrati i parametri di Bicep che consentono di specificare i valori che possono cambiare tra le distribuzioni dei file Bicep.

I parametri vengono comunemente usati per supportare le differenze tra gli ambienti. Ad esempio, negli ambienti non di produzione, spesso si vogliono distribuire SKU economici delle risorse di Azure. Nell'ambiente di produzione si vogliono distribuire SKU con prestazioni migliori. È possibile usare nomi diversi per le risorse in ogni ambiente.

Quando si distribuisce il file Bicep, specificare i valori per ogni parametro. Esistono diverse opzioni per specificare i valori per ogni parametro della pipeline e come specificare valori separati per ogni ambiente. In questa unità verranno illustrati gli approcci per specificare i valori dei parametri Bicep in una pipeline di distribuzione.

File dei parametri

Un file di parametri è un file in formato JSON che elenca i valori dei parametri che si desidera usare per ogni ambiente. L'utente invia il file di parametri ad Azure Resource Manager quando invia la distribuzione.

Ecco un file di parametri di esempio:

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

I file di parametri possono essere sottoposti a commit nel repository Git insieme al file Bicep. È quindi possibile fare riferimento al file di parametri nel modello di pipeline in cui si esegue la distribuzione.

È consigliabile stabilire una strategia di denominazione degli ambienti coerente per i file di parametri. Ad esempio, è possibile assegnare un nome ai file di parametri parametri.NOME_AMBIENTE.json, ad esempio parametri.Produzione.json. È quindi possibile usare un parametro del modello di pipeline per selezionare automaticamente il file di parametri corretto.

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

Quando si usano i file di parametri, i file YAML della pipeline non devono contenere un elenco di parametri che devono essere passati singolarmente ai passaggi di distribuzione. Ciò è utile quando si dispone di un numero elevato di parametri.

Un file di parametri mantiene tutti i valori dei parametri in un singolo file JSON. Anche i file di parametri fanno parte del repository Git, in modo che possano essere sottoposti al controllo della versione esattamente come tutti gli altri codici.

Importante

I file di parametri non devono essere usati per i valori sicuri. Non è possibile proteggere i valori dei segreti nei file di parametri e non è mai necessario eseguire il commit dei segreti nel repository Git.

Variabili della pipeline

Azure Pipelines consente di archiviare le variabili della pipeline, utili per i valori che potrebbero essere diversi tra gli ambienti. Sono utili anche per i valori che si desidera definire una sola volta e quindi riutilizzare in tutta la pipeline. Azure Pipelines supporta diversi modi per definire le variabili.

Variabili definite in un file YAML

È possibile definire le variabili e impostare i relativi valori all'interno di un file YAML. Questo è utile quando è necessario riutilizzare lo stesso valore più volte. Ma, allo stesso modo dei file di parametri Bicep, i file YAML non sono adatti ai segreti.

Variabili definite nell'interfaccia Web

È possibile definire le variabili usando l'interfaccia Web di Azure DevOps. È possibile modificare i valori delle variabili in qualsiasi momento e la pipeline leggerà i valori aggiornati alla successiva esecuzione.

Le variabili definite tramite l'interfaccia Web possono essere contrassegnate come segreto, che indica ad Azure Pipelines di provare a nascondere i valori delle variabili nei log della pipeline. Ciò significa che è possibile archiviare i valori che il file Bicep accetta come parametri con l'elemento Decorator @secure().

Avviso

Per impostazione predefinita, Azure Pipelines offusca i valori delle variabili segrete nei log della pipeline, ma è necessario seguire anche le procedure consigliate. I passaggi della pipeline hanno accesso a tutti i valori delle variabili, inclusi i segreti. Se la pipeline include un passaggio che non gestisce una variabile sicura in modo efficace, è possibile che la variabile segreta venga visualizzata nei log della pipeline.

Gruppi di variabili

È anche possibile definire gruppi di variabili, ovvero set di variabili. Come le variabili, si definiscono questi gruppi usando l'interfaccia Web di Azure DevOps. È anche possibile usare gruppi di variabili per archiviare in modo sicuro i segreti. I gruppi di variabili possono essere riutilizzati anche in più pipeline nello stesso progetto di Azure DevOps.

A differenza di altre variabili, è necessario importare in modo esplicito un gruppo di variabili in una pipeline usando la parola chiave group in una sezione variables, come illustrato di seguito:

variables:
- group: MyVariableGroup

Quando si usano modelli di pipeline, è possibile assegnare un nome ai gruppi di variabili in modo da poterli caricare facilmente usando un parametro modello. Si supponga, ad esempio, che la pipeline esegua la distribuzione in due ambienti e sia necessario definire un set di variabili per ogni ambiente. È possibile assegnare un nome ai gruppi di variabili con i nomi di ambiente inclusi, come illustrato di seguito:

Nome ambiente	Nome del gruppo di variabili
Test	`ToyWebsiteTest`
Produzione	`ToyWebsiteProduction`

In ognuno di questi gruppi di variabili si aggiungono variabili con gli stessi nomi, ma con valori diversi per ogni ambiente.

Il file del modello di pipeline usa la macro {{ parameters.PARAMETER_NAME }} per selezionare il gruppo di variabili corretto da importare:

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

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

Gruppi di variabili Key Vault

È possibile collegare gruppi di variabili ad Azure Key Vault. I segreti nell'insieme di credenziali delle chiavi vengono resi disponibili come variabili nel gruppo di variabili. I segreti possono quindi essere usati nelle pipeline come se fossero variabili normali.

Key Vault rende più sicura la gestione dei segreti. Consente inoltre al team di sicurezza di gestire tali valori e di separare l'accesso alle pipeline dai segreti usati.

Sono necessari altri passaggi per collegare un gruppo di variabili a un insieme di credenziali delle chiavi. Questi passaggi includono la creazione di una connessione al servizio che dispone dell'autorizzazione per leggere i segreti dall'insieme di credenziali delle chiavi. Nell'unità di riepilogo viene fornito un collegamento ad altre informazioni su come configurare i gruppi di variabili Key Vault.

Usare le variabili nella pipeline

Indipendentemente dalla modalità di definizione di una variabile, si accede al relativo valore nella pipeline usando la sintassi $(VariableName). Ad esempio, quando si esegue una distribuzione Bicep, è possibile usare una variabile per specificare il valore di un parametro:

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

Qual è l'approccio migliore?

Sono stati illustrati diversi modi per gestire i parametri necessari per la distribuzione del file Bicep. È utile comprendere quando è possibile usare ciascun approccio.

Evitare parametri non necessari

I parametri consentono di rendere riutilizzabili i file Bicep, ma è possibile che venga definito un numero eccessivo di parametri. Quando si distribuisce un file Bicep, è necessario specificare un valore per ogni parametro. Nelle distribuzioni complesse in più ambienti, è difficile gestire un numero elevato di singoli valori di parametri.

Ove possibile, è consigliabile rendere facoltativi i parametri e usare i valori predefiniti che si applicano alla maggior parte degli ambienti. È quindi possibile evitare la necessità di passare i valori delle pipeline per i parametri.

Tenere presente anche che i parametri vengono spesso usati in Bicep quando le risorse devono connettersi ad altre risorse. Ad esempio, se si dispone di un sito Web che deve connettersi a un account di archiviazione, è necessario specificare il nome dell'account di archiviazione e la chiave di accesso. Le chiavi sono valori sicuri. Tuttavia, prendere in considerazione questi altri approcci quando si distribuisce questa combinazione di risorse:

Usare l'identità gestita del sito Web per accedere all'account di archiviazione. Quando si crea un'identità gestita, Azure genera automaticamente e gestisce le proprie credenziali. Questo approccio semplifica le impostazioni di connessione. Significa anche che non è necessario gestire tutti i segreti, quindi è l'opzione più sicura.
Distribuire insieme l'account di archiviazione e il sito Web nello stesso modello di Bicep. Usare i moduli di Bicep per tenere insieme il sito Web e le risorse di archiviazione. È quindi possibile cercare automaticamente i valori per il nome dell'account di archiviazione e la chiave all'interno del codice Bicep, anziché passare i parametri.
Aggiungere i dettagli dell'account di archiviazione a un insieme di credenziali delle chiavi come segreto. Il codice del sito Web carica quindi la chiave di accesso direttamente dall'insieme di credenziali. Questo approccio evita la necessità di gestire la chiave nella pipeline.

Usare gruppi di variabili per piccoli set di parametri

Se per i file Bicep sono disponibili solo pochi parametri, è consigliabile usare un gruppo di variabili. Nei gruppi di variabili è possibile archiviare sia i valori segreti che non segreti.

Usare i file di parametri per set di parametri di grandi dimensioni

Se si dispone di un numero elevato di parametri per i file Bicep, è consigliabile usare i file di parametri per mantenere insieme i valori non sicuri per ogni ambiente. Quindi, ogni volta che è necessario modificare i valori, è possibile aggiornare un file di parametri ed eseguire il commit della modifica.

Questo approccio semplifica i passaggi della pipeline, perché non è necessario impostare in modo esplicito il valore per ogni parametro.

Archiviare i segreti in modo sicuro

Usare un processo appropriato per archiviare e gestire i segreti. Se si dispone solo di pochi segreti da gestire, variabili e gruppi di variabili di Azure Pipelines spesso sono sufficienti. Tuttavia, potrebbero essere presenti requisiti più complessi, ad esempio un numero elevato di segreti, molti ambienti diversi o restrizioni di controllo di accesso. Per queste situazioni, è consigliabile archiviare i segreti per ogni ambiente in insiemi di credenziali delle chiavi separati. Usare i gruppi di variabili per collegare gli insiemi di credenziali alla pipeline.

Per i parametri sicuri, ricordarsi di passare in modo esplicito ogni parametro nei passaggi di distribuzione.

Combinare gli approcci

È comune combinare più approcci per gestire i parametri. Ad esempio, è possibile archiviare la maggior parte dei valori dei parametri nei file di parametri e quindi impostare valori sicuri usando un gruppo di variabili. Nell'esempio che segue viene illustrata la combinazione:

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)

Esistono regole speciali sul modo in cui è possibile specificare i nomi di connessione del servizio. Queste regole possono influire sul modo in cui si usano i nomi nelle pipeline distribuite in più ambienti. Ad esempio, non è possibile usare una variabile definita all'interno di un gruppo di variabili per specificare un nome di connessione al servizio. È possibile usare i parametri del modello di pipeline per specificare il nome della connessione al servizio da usare.