Pubblicare un modulo in un registro privato

4 minuti

Si è appreso cosa sono i registri Bicep e come possono essere utili quando si condividono i moduli nell'organizzazione. In questa unità si apprenderà come pubblicare un modulo in un registro privato.

Percorsi dei moduli

Dopo aver usato i moduli in passato, è probabile che sia stato usato il percorso del file del modulo per farvi riferimento nei modelli. Quando si usano moduli e registri privati, è necessario usare un percorso di modulo diverso in modo che Bicep sappia come individuare il modulo nel registro.

Ecco un percorso di esempio per un modulo in un registro contenitori di Azure privato:

Diagram that shows the syntax for a module path.

Il percorso contiene quattro segmenti:

Schema: Bicep supporta diversi tipi di modulo, denominati schemi. Quando si lavora con i registri Bicep, lo schema è br.
Registro: nome del registro che contiene il modulo che si vuole usare. Nell'esempio precedente il nome del registro è toycompany.azurecr.io, ovvero il nome del registro contenitori.
Identificatore del modulo: percorso completo del modulo all'interno del registro.
Tag: i tag rappresentano in genere le versioni dei moduli, perché un singolo modulo può avere più versioni pubblicate. Nella prossima sezione verranno fornite altre informazioni sui tag e sulle versioni.

Quando si pubblica un identificatore di modulo personalizzato, usare un identificatore significativo che indica lo scopo del modulo. Facoltativamente, è possibile usare gli spazi dei nomi, in cui si usano le barre (/) per distinguere tra le parti di un nome. Tuttavia, Registro Azure Container e Bicep non comprendono una gerarchia. Considerano l'identificatore del modulo come un singolo valore.

Tag e versioni

Un tag rappresenta la versione di un modulo. Un singolo modulo in un registro può avere più versioni. Tutte le versioni condividono un identificatore di modulo, ma hanno tag diversi. Quando si usa un modulo, è necessario usare un tag per specificare la versione da usare, in modo che Bicep conosca il file di modulo da recuperare.

È consigliabile pianificare attentamente come si assegnerà il numero di versione ai moduli. Due decisioni chiave da prendere sono lo schema di controllo delle versioni e i criteri di versione da usare.

Schemi di controllo delle versioni

Lo schema di controllo delle versioni determina come si generano i numeri di versione. I comuni schemi controllo delle versioni includono:

I numeri interi di base possono essere usati come numeri di versione. La prima versione, ad esempio, potrebbe essere denominata 1, la seconda 2 e così via. In alternativa, è possibile aggiungere un prefisso a ogni numero di versione, ad esempio v1 e v2.
Anche le date possono essere usate come numeri di versione. Se ad esempio si pubblica la prima versione del modulo il 16 gennaio 2022, è possibile assegnare alla versione il nome 2022-01-16 (usando il formato aaaa-mm-gg). Quando si pubblica un'altra versione il 3 marzo, è possibile assegnare alla versione il nome 2022-03-03.
Il Versionamento Semantico è un sistema di controllo delle versioni usato spesso nel software, in cui un singolo numero di versione contiene più parti. Ogni parte fornisce informazioni diverse sulla natura della modifica.

Anche se è possibile usare qualsiasi schema di controllo delle versioni, è consigliabile sceglierne uno che determinerà un ordinamento significativo. In tal senso numeri e date sono scelte per lo più valide.

Nota

Il Registro Azure Container archivia la data di creazione di ogni tag. Anche se non si usa il controllo delle versioni basato sulla data, è ugualmente possibile visualizzare queste informazioni.

Criteri di controllo delle versioni

I moduli offrono la flessibilità necessaria per scegliere quando creare nuove versioni o aggiornare una versione esistente. È ad esempio possibile rifiutare esplicitamente il controllo delle versioni creando e pubblicando una singola versione denominata latest. Ogni volta che è necessario modificare il modulo, è sufficiente aggiornare tale versione. Anche se questo criterio funziona, non è una procedura consigliata.

Al contrario, se si apporta a un modulo esistente una piccola modifica che non influisce sull'uso che ne viene fatto, la creazione di una nuova versione non è probabilmente la soluzione più idonea. Sarebbe necessario comunicare il nuovo numero di versione a chiunque usi il modulo.

Il seguente è un criterio di controllo delle versioni che spesso funziona bene:

Ogni volta che si apportano modifiche significative a un modulo, creare una nuova versione. Le modifiche significative includono qualsiasi elemento che possa fare la differenza per chi usa il modulo. Gli esempi includono l'aggiunta di un'altra risorsa al modulo o la modifica delle proprietà di una risorsa.
Ogni volta che si apportano piccole modifiche a un modulo, definite a volte hotfix, aggiornare la versione del modulo esistente.
Eliminare le versioni precedenti quando non sono più rilevanti o si vuole che nessuno le usi.

Suggerimento

Considerare gli utenti del modulo e valutarne le aspettative. Se qualcuno usa il modulo più volte ottenendo un determinato risultato, quindi lo usa di nuovo dopo un hotfix e ottiene un risultato diverso, probabilmente ne sarà sorpreso. Provare a evitare di sorprendere gli utenti.

Pubblicare il modulo

Quando si crea un modulo Bicep che si vuole condividere, si crea il file Bicep come di consueto. Quindi si pubblica il file in un registro usando il comando bicep publish. Quando lo si pubblica, è necessario specificare il percorso in cui salvare il modulo:

az bicep publish \
   --file module.bicep \
   --target 'br:toycompany.azurecr.io/mymodules/modulename:moduleversion'

bicep publish module.bicep `
   --target 'br:toycompany.azurecr.io/mymodules/modulename:moduleversion'

L'operazione di pubblicazione esegue gli stessi passaggi di convalida che si verificano durante la compilazione o la distribuzione di un file Bicep. Nei passaggi seguenti è incluso:

Verificare che il codice non contenga errori sintattici.
Assicurarsi di specificare definizioni di risorse valide.
Eseguire il linter Bicep per verificare che il codice superi una serie di controlli di qualità.