Progettare un flusso di lavoro e una strategia di controllo delle versioni
Quando si inizia a pubblicare il codice Bicep riutilizzabile, è probabile che si usi un approccio manuale. È facile determinare quale file Bicep è necessario pubblicare e probabilmente esiste un processo manuale per incrementare il numero di versione.
Quando si automatizza il processo di pubblicazione, è necessario considerare come automatizzare questi passaggi. In questa unità si apprenderà come adottare un sistema di controllo delle versioni che comunica le modifiche apportate al codice. Si apprenderà anche come definire l'ambito dei flussi di lavoro per pubblicare solo il codice previsto.
Numeri di versione
Nei moduli di apprendimento precedenti di Microsoft Learn si è appresa l'importanza del controllo delle versioni per le specifiche di modello e i moduli Bicep. È possibile scegliere tra molti approcci diversi di controllo delle versioni. In molte situazioni è consigliabile usare un sistema di controllo delle versioni in più parti. Un sistema di controllo delle versioni in più parti è costituito da una versione principale, una versione secondaria e un numero di revisione, simile all'esempio seguente:
Nell'esempio precedente la versione principale è 1, la versione secondaria è 4 e il numero di revisione è 106.
Le modifiche apportate alle diverse parti dei numeri di versione comunicano informazioni importanti sui tipi di modifiche apportate al codice:
Ogni volta che si apporta una modifica che causa un'interruzione, è necessario incrementare il numero di versione principale. Si supponga, ad esempio, di aggiungere un nuovo parametro obbligatorio o di rimuovere un parametro dal file Bicep. Questi sono esempi di modifiche che causano un'interruzione, perché Bicep richiede che i parametri obbligatori vengano specificati in fase di distribuzione e non consentano l'impostazione dei valori per i parametri inesistenti. Quindi, si aggiorna il numero di versione principale.
Ogni volta che si aggiunge qualcosa di nuovo al codice, ma non si tratta di una modifica che causa un'interruzione, è necessario incrementare il numero di versione secondaria. Si supponga, ad esempio, di aggiungere un nuovo parametro facoltativo con un valore predefinito. I parametri facoltativi non sono modifiche che causano un'interruzione, pertanto è consigliabile aggiornare il numero di versione secondaria.
Ogni volta che si apportano correzioni di bug compatibili con le versioni precedenti o altre modifiche che non influiscono sul funzionamento del codice, è necessario incrementare il numero di revisione. Si supponga, ad esempio, di effettuare il refactoring del codice Bicep per usare meglio variabili ed espressioni. Se il refactoring non modifica affatto il comportamento del codice Bicep, aggiornare il numero di revisione.
Il flusso di lavoro può anche impostare automaticamente il numero di revisione. Il numero di esecuzione del flusso di lavoro può essere usato come numero di revisione. Questa convenzione consente di garantire che i numeri di versione siano sempre univoci, anche se non si aggiornano gli altri componenti dei numeri di versione.
Si supponga, ad esempio, di usare un modulo Bicep pubblicato da un altro utente. Il numero di versione del modulo è 2.0.496. Si noterà che una nuova versione del modulo è disponibile con il numero di versione 2.1.502. L'unica modifica significativa viene apportata al numero di versione secondaria, che indica che non ci si deve aspettare una modifica che causa un'interruzione quando si usa la nuova versione.
Nota
Il Versionamento Semantico è una struttura di controllo delle versioni formalizzata simile al controllo delle versioni in più parti. Il Versionamento Semantico include componenti aggiuntivi nel numero di versione, insieme a regole rigide su quando è necessario impostare o reimpostare ogni componente. Per altre informazioni sul Versionamento Semantico, vedere il riepilogo.
Il team deve decidere come definire una modifica che causa un'interruzione per il controllo delle versioni. Si supponga, ad esempio, di aver creato un modulo Bicep che distribuisce un account di archiviazione. Si sta aggiornando il file Bicep per abilitare gli endpoint privati nell'account di archiviazione. Si aggiunge contemporaneamente una zona DNS privata al file Bicep.
In questo esempio l'utente potrebbe essere in grado di apportare la modifica senza influire sui parametri o gli output del file Bicep. In questo modo, chiunque distribuisca il file potrebbe non notare le differenze. Tuttavia, questa modifica cambia notevolmente il comportamento delle risorse, quindi è possibile decidere di considerarla come un aggiornamento della versione principale.
È anche possibile scegliere di usare una strategia di controllo delle versioni più semplice, ad esempio usando il numero di esecuzione del flusso di lavoro come numero di versione. Anche se questo approccio è più semplice da implementare, significa che non è possibile comunicare in modo efficace le differenze tra le versioni a chiunque usi il codice.
Versioni e flussi di lavoro
Quando si pubblica il codice in modo interattivo, ad esempio usando l'interfaccia della riga di comando di Azure, è probabile che si consideri il numero di versione assegnato alla specifica di modello o al modulo durante la pubblicazione. Tuttavia, in un flusso di lavoro di distribuzione automatizzato, è necessario modificare l'approccio per assegnare i numeri di versione. Il flusso di lavoro non è in grado di rilevare automaticamente le modifiche che causano un'interruzione o consigliare quando incrementare i numeri di versione principali o secondari. Valutare attentamente il controllo delle versioni prima di pubblicare la specifica di modello o il modulo.
Un approccio consiste nell'archiviare un file di metadati con il codice Bicep, come illustrato nel diagramma seguente:
Ogni volta che si aggiorna il codice Bicep, si aggiornano le informazioni sulla versione nel file di metadati corrispondente. Assicurarsi di identificare correttamente le modifiche che causano o meno un'interruzione in modo da poter incrementare correttamente i numeri di versione.
Suggerimento
Se il team esamina il codice Bicep usando le richieste pull, chiedere ai revisori di verificare se le modifiche apportate al codice richiedono la modifica dei numeri di versione principali o secondari.
Nell'esercizio successivo verrà illustrato come usare un file di metadati.
Quanti flussi di lavoro?
È comune creare una raccolta di specifiche di modello e moduli. Spesso, è opportuno mantenerli nello stesso repository Git.
Usando i filtri di percorso in GitHub Actions, è possibile creare flussi di lavoro separati per ogni modulo o specifica di modello all'interno del repository. Questo approccio consente di evitare di pubblicare una nuova versione per ogni file Bicep all'interno del repository ogni volta che si modifica un file. È possibile usare flussi di lavoro riutilizzabili per definire i passaggi del flusso di lavoro in un file centralizzato, che non appesantisce il flusso di lavoro di ogni modulo e specifica di modello.
Si supponga, ad esempio, di avere una struttura di file simile a quella illustrata in precedenza. È possibile configurare tre flussi di lavoro separati, uno per ogni file Bicep. Selezionare ogni scheda per visualizzare la definizione del flusso di lavoro corrispondente e il relativo filtro del percorso:
name: 'publish-module-1'
on:
push:
branches:
- main
paths:
- 'module-1/**'
jobs:
publish:
uses: ./.github/workflows/publish-module.yml
with:
path: 'module-1/main.bicep'
Si supponga di modificare solo il file module-2/main.bicep. Viene eseguito solo il flusso di lavoro per le esecuzioni del modulo 2. Tuttavia, se si modificano più file nello stesso commit, viene attivato ogni flusso di lavoro pertinente.
Nota
L'approccio alla creazione di un flusso di lavoro per ogni file Bicep riutilizzabile è semplice e flessibile. Ma può diventare complesso quando si ha un numero elevato di file Bicep o se non si desidera mantenere flussi di lavoro separati per ogni modulo e specifica di modello.
È anche possibile scrivere script all'interno del flusso di lavoro per trovare il codice modificato e pubblicare solo questi file. Si tratta di un approccio più complesso e non rientra nell'ambito di questo modulo di apprendimento di Microsoft Learn.
Ambienti per il codice Bicep riutilizzabile
Quando si esegue la distribuzione in Azure usando Bicep, è comune usare più ambienti per convalidare e testare il codice prima di pubblicare il codice in un ambiente di produzione. Nei moduli di apprendimento precedenti di Microsoft Learn si è appreso come usare più ambienti di un flusso di lavoro di distribuzione.
Alcune organizzazioni applicano gli stessi principi ai moduli e alle specifiche di modello Bicep. Ad esempio, è possibile pubblicare prima nuove versioni dei moduli in un registro non di produzione in modo che gli utenti di ogni modulo possano provare le nuove versioni. Dopo la disconnessione, è quindi possibile pubblicare i moduli nel registro di produzione dell'organizzazione.
Come per le distribuzioni regolari, è possibile usare i processi e i flussi di lavoro riutilizzabili per definire la sequenza di distribuzione negli ambienti. In questo modulo di apprendimento di Microsoft Learn si esegue la pubblicazione in un unico ambiente per non complicare il flusso di lavoro.
Quando si utilizzano i moduli di un Registro di sistema o si usa una specifica di modello come modulo Bicep, è possibile usare gli alias. Anziché specificare il nome del Registro di sistema o la posizione della specifica di modello ogni volta che si definisce un modulo, si usa il relativo alias.
Usando gli alias, è possibile far funzionare il processo di distribuzione in più ambienti. Ad esempio, quando si definisce un modulo, è possibile usare un alias anziché un nome del Registro di sistema. È quindi possibile progettare un flusso di lavoro di distribuzione per configurare l'alias di cui eseguire il mapping in:
- Un registro dei moduli di sviluppo quando si esegue la distribuzione in un ambiente sandbox.
- Un registro di produzione quando si esegue la distribuzione in altri ambienti.
Nota
Gli alias non si applicano quando si esegue la pubblicazione. Funzionano solo quando si usano le specifiche di modello o i moduli all'interno di un file Bicep.