Distribuire file Bicep usando una pipeline

Completato

Dopo aver creato una pipeline semplice, si è pronti per configurarla per distribuire i file Bicep. In questa unità si apprenderà come distribuire codice Bicep da una pipeline 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.

Connessioni al servizio

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, si accede ad Azure. In genere gli strumenti chiedono di immettere l'indirizzo di posta elettronica e la password 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.

L'autenticazione è necessaria anche per la distribuzione tramite pipeline. Poiché le pipeline vengono eseguite senza intervento umano, devono eseguire l'autenticazione in Azure usando un'entità servizio. Le credenziali di un'entità servizio sono costituite da un ID applicazione e un segreto, che in genere è una chiave o un certificato. In Azure Pipelines si usa una connessione al servizio per archiviare in modo sicuro queste credenziali in modo che la pipeline possa usarle. Una connessione al servizio include anche altre informazioni che consentono alla pipeline di identificare l'ambiente di Azure in cui si vuole eseguire la distribuzione.

Suggerimento

In questo modulo si userà Azure DevOps per creare automaticamente un'entità servizio quando crea una connessione al servizio. Il modulo Autenticare la pipeline di distribuzione di Azure usando le entità servizio offre una spiegazione più dettagliata delle entità servizio, tra cui il funzionamento, nonché il modo in cui vengono create, come assegnarvi ruoli e gestirle.

Al momento della creazione di una connessione al servizio, si assegna un nome alla connessione. Poiché i passaggi sono relativi alla connessione al servizio tramite questo nome, il codice YAML della pipeline non deve contenere informazioni segrete.

All'avvio della pipeline, l'agente che esegue i passaggi di distribuzione ha accesso alla connessione al servizio, incluse le relative credenziali. Un passaggio della pipeline usa le credenziali per accedere ad Azure, proprio come con l'accesso manuale. Le azioni definite nel passaggio usano quindi l'identità dell'entità servizio.

È necessario assicurarsi che l'entità servizio abbia le autorizzazioni necessarie per eseguire i passaggi di distribuzione. Ad esempio, potrebbe essere necessario assegnare all'entità servizio il ruolo Collaboratore per il gruppo di risorse in cui distribuisce le risorse.

Avviso

Potrebbe sembrare più facile archiviare le credenziali dell'entità servizio nel file YAML e quindi accedere usando il comando az login. Non è mai consigliabile usare questo approccio per autenticare l'entità servizio. 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 all'organizzazione e al progetto di Azure DevOps, ogni volta che un utente clona il repository, il file YAML che contiene le credenziali sarà disponibile nel computer di tale utente. È importante usare una connessione al servizio ogni volta che si utilizza Azure da una pipeline. Le connessioni al servizio offrono anche altre funzionalità di sicurezza e controllo di accesso.

Le connessioni al servizio vengono create nel progetto di Azure DevOps. Una singola connessione al servizio può essere condivisa da più pipeline. Tuttavia, in genere è buona norma configurare una connessione al servizio e l'entità servizio corrispondente per ogni pipeline e ogni ambiente in cui si esegue la distribuzione. Questa prassi consente di ottenere maggiore sicurezza per le pipeline e riduce la probabilità di distribuire o configurare accidentalmente risorse in un ambiente diverso da quello previsto.

È anche possibile configurare la connessione al servizio in modo che possa essere usata solo in pipeline specifiche. Ad esempio, quando si crea una connessione al servizio che viene distribuita nell'ambiente di produzione del sito Web, è consigliabile assicurarsi che solo la pipeline del sito Web possa usare questa connessione al servizio. Limitando una connessione al servizio a pipeline specifiche, si impedisce che qualcun altro possa usare inavvertitamente la stessa connessione al servizio per un progetto diverso e rendere il sito Web di produzione potenzialmente non disponibile.

Distribuire un file Bicep usando l'attività Distribuzione gruppo di risorse di Azure

Quando è necessario distribuire un file Bicep da una pipeline, è possibile usare l'attività Distribuzione gruppo di risorse di Azure. Ecco un esempio di come configurare un passaggio per usare l'attività:

- task: AzureResourceManagerTemplateDeployment@3
  inputs:
    connectedServiceName: 'MyServiceConnection'
    location: 'westus3'
    resourceGroupName: Example
    csmFile: deploy/main.bicep
    overrideParameters: >
        -parameterName parameterValue

La prima riga specifica AzureResourceManagerTemplateDeployment@3. La riga indica ad Azure Pipelines che l'attività che si vuole usare per questo passaggio è denominata AzureResourceManagerTemplateDeployment e si vuole usare la versione 3 dell'attività.

Quando si usa l'attività Distribuzione gruppo di risorse di Azure, occorre specificare gli input per indicare all'attività le operazioni da eseguire. Ecco alcuni input che è possibile specificare quando si usa l'attività:

• connectedServiceName è il nome della connessione al servizio da usare.
• location deve essere specificato anche se il relativo valore potrebbe non essere usato. L'attività Distribuzione gruppo di risorse di Azure può anche creareautomaticamente un gruppo di risorse e, in caso affermativo, deve conoscere l'area di Azure in cui creare il gruppo di risorse. In questo modulo verrà specificato valore di input location, anche se non verrà usato.
• resourceGroupName specifica il nome del gruppo di risorse in cui deve essere distribuito il file Bicep.
• overrideParameters contiene tutti i valori dei parametri da passare al file Bicep in fase di distribuzione.

Quando l'attività viene avviata, usa la connessione al servizio per accedere ad Azure. Nel momento in cui l'attività esegue la distribuzione specificata, l'attività è stata autenticata. Non è necessario eseguire az login.

Eseguire i comandi dell'interfaccia della riga di comando di Azure e di Azure PowerShell

Due delle attività predefinite più utili in Azure Pipelines sono le attività dell'interfaccia della riga di comando di Azure e di Azure PowerShell. È possibile usare queste attività per eseguire uno o più comandi dell'interfaccia della riga di comando di Azure o PowerShell.

Nei moduli futuri di Microsoft Learn verrà illustrato in che modo il comando dell'interfaccia della riga di comando di Azure consente di automatizzare più parti del processo di distribuzione da una pipeline.

Variabili

Spesso le pipeline contengono valori che devono rimanere separati dal file YAML. Ad esempio, quando si distribuisce un file Bicep in un gruppo di risorse, si specifica il nome del gruppo di risorse. Il nome del gruppo di risorse è probabilmente diverso quando si esegue la distribuzione in ambienti diversi. Potrebbe anche essere necessario specificare parametri per i file Bicep, inclusi segreti come le password del server di database. Non archiviare questi valori nel file YAML della pipeline o in qualsiasi altra posizione nel repository Git. Per aumentare la sicurezza e rendere riutilizzabili le definizioni della pipeline, usare invece le variabili.

Creazione di una variabile

L'interfaccia Web di Azure Pipelines ha un editor che è possibile usare per creare le variabili per la pipeline:

È possibile impostare un valore per la variabile di Azure Pipelines come segreto. Quando si imposta un valore di una variabile come segreto, non è possibile visualizzare il valore dopo averlo impostato. Azure Pipelines è progettato per non rivelare i valori dei segreti nei log della pipeline.

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.

È possibile consentire agli utenti di sostituire il valore di una variabile quando eseguono manualmente la pipeline. Il valore fornito da un utente viene usato solo per tale esecuzione specifica della pipeline. Le sostituzioni delle variabili possono essere utili durante i test della pipeline.

Usare una variabile nella pipeline

Dopo aver creato una variabile, si userà una sintassi specifica per fare riferimento alla variabile nel file YAML della pipeline:

- task: AzureResourceManagerTemplateDeployment@3
  inputs:
    connectedServiceName: $(ServiceConnectionName)
    location: $(DeploymentDefaultLocation)
    resourceGroupName: $(ResourceGroupName)
    csmFile: deploy/main.bicep
    overrideParameters: >
      -environmentType $(EnvironmentType)

Il formato del file di definizione della pipeline include una sintassi $(VariableName) speciale. È possibile fare riferimento a qualsiasi variabile usando questo approccio, indipendentemente dal fatto che sia segreta o meno.

Suggerimento

Si noti che nell'esempio precedente il nome del file Bicep non è archiviato in una variabile. 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. Poiché la pipeline userà sempre lo stesso file modello, non è necessario creare una variabile per il percorso.

Variabili di sistema

Azure Pipelines usa anche variabili di sistema che contengono informazioni predefinite utilizzabili nella pipeline. Ecco alcune delle variabili di sistema che è possibile usare nella pipeline:

• Build.BuildNumber è l'identificatore univoco per l'esecuzione della pipeline. Nonostante il nome, il valore Build.BuildNumber è spesso una stringa e non un numero. È possibile usare questa variabile per assegnare un nome alla distribuzione di Azure, per poter tenere traccia della distribuzione fino all'esecuzione della pipeline specifica che l'ha attivata.
• Agent.BuildDirectory è il percorso nel file system del computer dell'agente in cui sono archiviati i file dell'esecuzione della pipeline. Queste informazioni possono essere utili quando si vuole fare riferimento a file nell'agente di compilazione.

Creare variabili nel file YAML della pipeline

Oltre a usare l'interfaccia Web di Azure Pipelines per creare variabili, è possibile impostare i valori delle variabili nel file YAML della pipeline. Si può usare questa opzione in presenza di valori non segreti, quando i valori possono essere archiviati nel repository e quando si vogliono mantenere i valori delle variabili in un'unica posizione nel file per potervi fare riferimento in tutta la definizione della pipeline. È possibile usare questo approccio per tenere traccia delle modifiche apportate alla variabile nel sistema di controllo della versione.

Per impostare una variabile nel file YAML, aggiungere una sezione variables:

trigger: none

pool:
  vmImage: ubuntu-latest

variables:
  ServiceConnectionName: 'MyServiceConnection'
  EnvironmentType: 'Test'
  ResourceGroupName: 'MyResourceGroup'
  DeploymentDefaultLocation: 'westus3'

jobs:
- job:
  steps:
  - task: AzureResourceManagerTemplateDeployment@3
    inputs:
      connectedServiceName: $(ServiceConnectionName)
      location: $(DeploymentDefaultLocation)
      resourceGroupName: $(ResourceGroupName)
      csmFile: deploy/main.bicep
      overrideParameters: >
        -environmentType $(EnvironmentType)

Questo esempio di pipeline definisce quattro variabili: ServiceConnectionName, EnvironmentType, ResourceGroupName e DeploymentDefaultLocation.

Più avanti in questo modulo si vedrà come combinare le variabili definite in posizioni diverse in una pipeline.