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. Per specificare i valori di ogni parametro del flusso di lavoro e specificare valori separati per ogni ambiente esistono diverse opzioni. In questa unità verranno illustrati gli approcci per specificare i valori dei parametri di Bicep in un flusso di lavoro 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 flusso di lavoro 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 input del modello del flusso di lavoro per selezionare automaticamente il file di parametri corretto in base a un valore di input.

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

Quando si usano i file di parametri, i file YAML del flusso di lavoro non devono contenere un elenco di parametri che devono essere passati singolarmente ai passaggi di distribuzione. Ciò è particolarmente 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 del flusso di lavoro

GitHub Actions consente di archiviare le variabili del flusso di lavoro, 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 tutto il flusso di lavoro.

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. È possibile definire una variabile per un intero flusso di lavoro, un processo o un singolo passaggio:

env:
  MyVariable1: value1

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

Segreti definiti nell'interfaccia Web

Come i file di parametri Bicep, i file YAML non sono adatti ai segreti. È invece possibile definire i segreti usando l'interfaccia Web di GitHub. È possibile modificare i valori delle variabili in qualsiasi momento e il flusso di lavoro leggerà i valori aggiornati alla successiva esecuzione. GitHub Actions tenta di nascondere i valori dei segreti nei log del flusso di lavoro. Ciò significa che è possibile archiviare i valori che il file Bicep accetta come parametri con l'elemento Decorator @secure().

Avviso

Per impostazione predefinita, GitHub Actions offusca i valori delle variabili segrete nei log del flusso di lavoro, ma è necessario seguire anche le procedure consigliate. I passaggi del flusso di lavoro hanno accesso ai valori dei segreti. Se il flusso di lavoro include un passaggio che non gestisce un segreto in modo sicuro, il valore del segreto potrebbe venire visualizzato nei log del flusso di lavoro. È consigliabile esaminare sempre attentamente le modifiche apportate a un file di definizione di flusso di lavoro per verificare che i segreti non siano gestiti in modo improprio.

Quando si crea un segreto, GitHub consente di scegliere se definire l'ambito nell'intero repository Git o in un ambiente specifico. I segreti con ambito in un determinato ambiente rispettano le regole di protezione configurate negli ambienti, perciò se si configura una regola del revisore necessaria, il flusso di lavoro non può accedere ai valori dei segreti fino a quando l'utente specificato di GitHub non ha approvato la pipeline per la distribuzione in tale ambiente.

I segreti con ambito ambiente possono essere utili, ma non funzionano facilmente con le operazioni di convalida preliminare o di simulazione di Azure Resource Manager. Queste operazioni devono comunicare con Azure, il che significa che è necessaria un'identità del carico di lavoro. In genere l'approvazione della distribuzione deve essere data dopo il completamento delle operazioni di convalida preliminare o di simulazione, in modo da avere un livello elevato di attendibilità nelle modifiche che vengono distribuite. Pertanto, se si usano segreti con ambito ambiente, il processo di revisione umana avviene troppo presto nel flusso di lavoro.

Per questo motivo, non si usano segreti con ambito ambiente negli esercizi di questo modulo. Si creano invece segreti con ambito repository con nomi prevedibili che includono il nome dell'ambiente. Ciò consente al flusso di lavoro di identificare il segreto corretto da usare per ogni ambiente. Nei propri flussi di lavoro è possibile scegliere di usare segreti con ambito repository, segreti con ambito ambiente o anche una combinazione di entrambi.

Nota

È anche possibile definire l'ambito dei segreti per organizzazioni GitHub. Anche se questo aspetto non rientra in questo modulo, nel riepilogo è presente un collegamento ad altre informazioni.

Usare le variabili nel flusso di lavoro

Il modo in cui si accede al valore di una variabile nel flusso di lavoro dipende dal tipo di variabile.

Tipo Sintassi
Variabili definite nello stesso file ${{ env.VARIABLE_NAME }}
Input in un flusso di lavoro denominato ${{ inputs.INPUT_NAME }}
Segreti ${{ secrets.SECRET_NAME }}

Ad esempio, quando si esegue una distribuzione Bicep, è possibile usare i segreti per specificare l'identità del carico di lavoro di Azure da usare, un input del flusso di lavoro denominato per specificare il nome del gruppo di risorse e una variabile per specificare il valore di un parametro:

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

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 che i flussi di lavoro debbano essere passati in valori 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 nel flusso di lavoro.

Usare le variabili del flusso di lavoro per piccoli set di parametri

Se per i file Bicep sono disponibili solo pochi parametri, è consigliabile definire le variabili nel proprio file YAML.

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 del flusso di lavoro, perché non è necessario impostare in modo esplicito il valore di ogni parametro.

Archiviare i segreti in modo sicuro

Usare un processo appropriato per archiviare e gestire i segreti. Usare i segreti di GitHub per archiviare i segreti nel repository di GitHub o usare Key Vault per archiviare i segreti in Azure.

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

GitHub può analizzare automaticamente il repository per individuare i segreti di cui è stato eseguito accidentalmente il commit, in modo che sia possibile ricevere una notifica. È quindi possibile rimuovere e ruotare i segreti. Per altre informazioni su questa funzionalità, vedere il riepilogo.

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 segreto. Nell'esempio che segue viene illustrata la combinazione:

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

Suggerimento

Alla fine di questo esempio, il valore parameters viene specificato come stringa multilinea YAML usando il carattere > in modo da migliorare la leggibilità del file YAML. Questo equivale a includere l'intero valore in una singola riga.