Distribuire file Bicep usando un flusso di lavoro

  • 7 minuti

Dopo aver creato un flusso di lavoro semplice, si è pronti per configurarlo per distribuire i file Bicep. In questa unità si apprenderà come distribuire codice Bicep da un flusso di lavoro e come configurare i passaggi di distribuzione.

Nota

I comandi riportati in questa unità vengono illustrati per spiegare i concetti. Non eseguire ancora i comandi. Presto sarà possibile provare quanto appreso.

Estrarre il codice

I file Bicep sono archiviati nel repository Git. In GitHub Actions è necessario indicare in modo esplicito al flusso di lavoro di estrarre i file dal repository Git. In caso contrario, il flusso di lavoro non avrà accesso ai file. Questo passaggio è in genere il prima eseguito dal processo.

Per estrarre il codice, è possibile usare l'azione actions/checkout@v3:

name: MyWorkflow

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
      with:
        path: repo

Si noti che il flusso di lavoro include la parola chiave uses La parola chiave indica che si vuole usare un'azione predefinita denominata actions/checkout.

Come le risorse Bicep, le azioni vengono sempre sottoposte al controllo delle versioni. In questo caso il flusso di lavoro usa la versione 3, quindi viene aggiunto @v3 al nome dell'azione.

Una volta che il flusso di lavoro include questa azione, il codice del repository viene estratto nel file system dello strumento di esecuzione. Usare il parametro path per specificare il percorso in cui archiviare i file.

Autenticazione con Azure

Quando si distribuisce un file Bicep dal proprio computer, si usa l'interfaccia della riga di comando di Azure o Azure PowerShell. Prima di poter distribuire il codice, è necessario accedere ad Azure. In genere, gli strumenti richiedono di immettere le credenziali in un browser. Dopo la verifica delle credenziali, le autorizzazioni per distribuire le risorse vengono confermate ed è possibile usare gli strumenti per distribuire il file Bicep.

Suggerimento

In questo modulo verrà creata un'identità del carico di lavoro, pronta per essere usata dal flusso di lavoro. Il modulo Autenticare il flusso di lavoro di distribuzione di Azure usando le identità dei carichi di lavoro offre una spiegazione più dettagliata delle identità dei carichi di lavoro, ad esempio come funzionano, come vengono create, come assegnare loro i ruoli e come gestirle.

L'autenticazione è necessaria anche per la distribuzione tramite flusso di lavoro. Poiché i flussi di lavoro vengono eseguiti senza intervento umano, devono eseguire l'autenticazione in Azure usando un'identità del carico di lavoro. GitHub e Microsoft Entra ID interagiscono per autenticare in modo sicuro il flusso di lavoro senza dover richiedere credenziali.

Quando il flusso di lavoro deve comunicare con Azure, un passaggio del flusso di lavoro accede ad Azure usando un'identità del carico di lavoro. I passaggi definiti nel flusso di lavoro usano quindi l'identità del flusso di lavoro.

Diagram that shows a workflow that includes an Azure deployment step, which accesses a secret and then deploys to Azure.

È necessario assicurarsi che l'identità del carico di lavoro disponga delle autorizzazioni necessarie per eseguire i passaggi di distribuzione. Ad esempio, potrebbe essere necessario assegnare all'identità del carico di lavoro il ruolo Collaboratore per il gruppo di risorse in cui si distribuiscono le risorse.

Avviso

Potrebbe sembrare più facile archiviare le credenziali nel file YAML e quindi accedere usando il comando az login. Non è mai consigliabile usare questo approccio per autenticare il flusso di lavoro. Le credenziali in un file YAML vengono archiviate come testo non crittografato. Chiunque abbia accesso al repository può visualizzare e usare le credenziali. Anche se si limita l'accesso al repository GitHub, ogni volta che un utente clona il repository, il file YAML che contiene le credenziali sarà disponibile nel computer di tale utente.

Accedere ad Azure

Il flusso di lavoro deve eseguire l'accesso prima di poter eseguire i comandi nell'ambiente di Azure. L'azione azure/login consente di gestire il processo di accesso. È anche necessario concedere l'autorizzazione affinché il flusso di lavoro possa usare i token di autenticazione.

name: MyWorkflow

on: [workflow_dispatch]

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
      with:
        path: repo
    - uses: azure/login@v1
      with:
        client-id: ${{ secrets.AZURE_CLIENT_ID }}
        tenant-id: ${{ secrets.AZURE_TENANT_ID }}
        subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

L'azione azure/login richiede di fornire tre informazioni per usare un'identità del carico di lavoro: un ID applicazione di Microsoft Entra, l'ID (directory) tenant di Microsoft Entra e l'ID sottoscrizione di Azure da usare.

Dopo l'esecuzione di questa azione, lo strumento di esecuzione verrà autenticato e potrà eseguire le istruzioni nell'ambiente Azure.

Distribuire il file Bicep

Una volta che il flusso di lavoro ha eseguito l'accesso ad Azure, può usare l'identità del carico di lavoro per eseguire la distribuzione Bicep. In GitHub Actions si usa l'azione azure/arm-deploy per avviare una distribuzione Bicep.

Nota

Esistono altri modi per distribuire i file Bicep da GitHub Actions. È ad esempio possibile usare l'azione azure/CLI e quindi fornire i comandi dell'interfaccia della riga di comando di Azure per eseguire le distribuzioni. Tuttavia in questo modulo userai l'attività azure/arm-deploy, che è progettata specificamente per le distribuzioni.

Ecco un esempio di come configurare un passaggio per usare l'azione azure/arm-deploy:

name: MyWorkflow

on: [workflow_dispatch]

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
      with:
        path: repo
    - 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:
        resourceGroupName: ${{ env.AZURE_RESOURCEGROUP_NAME }}
        template: ./deploy/main.bicep
        parameters: environmentType=Test

L'azione azure/arm-deploy accetta diversi parametri, tra cui:

  • resourceGroupName: Nome del gruppo di risorse in cui si desidera distribuire le risorse definite nel file Bicep.
  • template: Percorso del file Bicep nel repository. Il percorso è relativo alla radice del repository.
  • parameters: Indica i valori dei parametri specificati in fase di distribuzione. In questo esempio viene fornito un valore per il parametro environmentType.

Poiché l'azione azure/login precedente ha già connesso il flusso di lavoro ad Azure, il passaggio azure/arm-deploy viene eseguito in uno strumento di esecuzione autenticato.

Variabili

I flussi di lavoro contengono spesso valori da riutilizzare in più punti del file del flusso di lavoro. Potrebbe anche essere utile archiviare questi valori all'inizio del file del flusso di lavoro per individuarli e modificarli con facilità. Nel flusso di lavoro le variabili definite verranno visualizzate come variabili di ambiente. Per definire valori riutilizzabili, usare le variabili.

Creazione di una variabile

È possibile creare variabili a livelli diversi nel file del flusso di lavoro. Se tuttavia si vuole che siano disponibili per l'intero file del flusso di lavoro, definirle nella parte iniziale del file, appena sotto l'istruzione on. Per definire le variabili, usare il parametro env:

env:
    AZURE_RESOURCEGROUP_NAME: gh-actions
    AZURE_WEBAPP_NAME: webapp-gh-actions

Nell'esempio precedente vengono specificate due variabili di ambiente.

Usare una variabile nel flusso di lavoro

Dopo aver creato una variabile, si usa una sintassi speciale per fare riferimento a tale variabile all'interno del file YAML del flusso di lavoro, come illustrato di seguito:

${{ env.AZURE_RESOURCEGROUP_NAME }}

Variabili di ambiente predefinite

GitHub Actions usa anche le variabili di ambiente predefinite che contengono informazioni predefinite utilizzabili nel flusso di lavoro. Ecco alcune delle variabili di ambiente predefinite che è possibile usare nel flusso di lavoro:

  • github.sha: identificatore del commit Git che ha attivato l'esecuzione del flusso di lavoro.
  • github.run_number: numero univoco per ogni esecuzione di un flusso di lavoro specifico in un repository. Questo numero corrisponde a 1 per la prima esecuzione del flusso di lavoro e viene incrementato a ogni nuova esecuzione. È possibile usare questa variabile per assegnare un nome alla distribuzione di Azure, per poter tenere traccia della distribuzione fino all'esecuzione del flusso di lavoro specifico che l'ha attivata.

    Nota

    In GitHub Actions è possibile ripetere un'esecuzione del flusso di lavoro. Quando si esegue questa operazione, il numero di esecuzione non cambia, quindi non è consigliabile usare la variabile github.run_number per stabilire quante volte è stato eseguito il flusso di lavoro.

Segreti

A volte è necessario archiviare le informazioni segrete che verranno usate dal flusso di lavoro, ad esempio una password del database o una chiave API. Si usano i segreti di GitHub per archiviare in modo sicuro le informazioni contenenti credenziali o informazioni sensibili. Il flusso di lavoro può accedere al valore del segreto.

I segreti vengono creati nelle impostazioni del repository GitHub. Un segreto è disponibile per tutti i flussi di lavoro nel repository. In un modulo successivo verranno illustrati gli ambienti, che consentono di limitare l'uso dei segreti alle distribuzioni in un ambiente specifico.

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.

Puoi creare segreti usando l'interfaccia Web di GitHub. Per fare riferimento al valore di un segreto nel flusso di lavoro, usare la sintassi seguente:

${{ secrets.NAME_OF_THE_SECRET }}

All'avvio del flusso di lavoro, lo strumento di esecuzione che esegue i passaggi di distribuzione ha accesso al valore del segreto GitHub decrittografato. GitHub Actions è progettato per non rivelare i valori dei segreti nei log del flusso di lavoro.

Suggerimento

Analogamente ai parametri Bicep, non è necessario creare variabili per tutti gli elementi. È consigliabile creare variabili per qualsiasi elemento che potrebbe cambiare tra gli ambienti e per gli eventuali segreti GitHub. Poiché il flusso di lavoro userà sempre lo stesso file Bicep, non è necessario creare una variabile per il percorso.

In questo modulo userai i segreti di GitHub per archiviare le informazioni necessarie per consentire all'attività azure/login di accedere ad Azure: la sottoscrizione di Microsoft Entra, l'ID tenant e l'ID di registrazione dell'applicazione dell'identità del carico di lavoro.