Gestire una specifica di modello

Completato

Le specifiche dei modelli consentono di pubblicare e condividere in modo pratico i modelli all'interno dell'organizzazione. Quando si usano più specifiche dei modelli, è importante sapere come gestirle.

In questa unità verrà illustrato il controllo delle versioni e si apprenderà come modificare ed eliminare le specifiche dei modelli e come controllare l'accesso alle specifiche dei modelli.

Nota

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

Aggiungere le versioni

Si è appreso che una singola specifica di modello può avere più versioni. Una specifica di modello è un contenitore per una o più versioni e ogni versione è associata a un file modello. Quando si distribuisce una specifica di modello, è necessario specificare la versione che si vuole usare, in modo che Azure Resource Manager sappia quale file modello recuperare.

L'interfaccia della riga di comando di Azure e Azure PowerShell semplificano l'uso di più versioni. In realtà si è già lavorato con le versioni nell'esercizio precedente, quando è stata distribuita la specifica di modello.

È consigliabile pianificare attentamente come si assegnerà il numero di versione alle specifiche di modello. 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.
• Anche le date possono essere usate come numeri di versione. Se ad esempio si pubblica la prima versione della specifica di modello il 16 gennaio 2021, è possibile assegnare alla versione il nome 2021-01-16 (usando il formato aaaa-mm-gg). Quando si pubblica un'altra versione il 3 marzo, è possibile assegnare alla versione il nome 2021-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 come numeri e date.

Nota

Azure archivia la data in cui ogni versione viene creata. Anche se non si usa il controllo delle versioni basato sulla data, è ugualmente possibile visualizzare queste informazioni.

Criteri di controllo delle versioni

Le specifiche dei modelli 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 la specifica di modello, è sufficiente aggiornare tale versione. Anche se questo criterio funziona, non è una procedura consigliata.

Al contrario, se si apporta a un modello esistente una piccola modifica che non influisce sul relativo utilizzo, la creazione di una nuova versione non è probabilmente una buona idea. Sarebbe necessario comunicare il nuovo numero di versione a chiunque usi la specifica di modello.

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

• Ogni volta che si apportano modifiche significative a una specifica di modello, creare una nuova versione. Le modifiche significative apportate alla specifica di modello includono qualsiasi elemento che possa fare la differenza per l'utente che lo distribuisce. Gli esempi includono l'aggiunta di un'altra risorsa al modello o la modifica delle proprietà di una risorsa.
• Ogni volta che si apportano a una specifica di modello piccole modifiche, chiamate a volte hotfix, aggiornare la versione della specifica di modello esistente.
• Eliminare le versioni precedenti quando non sono più rilevanti o si vuole che nessuno le usi.

Suggerimento

Considerare gli utenti della specifica di modello e valutarne le aspettative. Se un utente distribuisce la specifica di modello più volte ottenendo un determinato risultato, quindi la distribuisce di nuovo dopo un hotfix e ottiene un risultato diverso, probabilmente ne sarà sorpreso. Cercare di ridurre al minimo la probabilità che gli utenti ottengano un risultato non previsto.

Descrizioni delle versioni

Quando si crea una nuova versione di una specifica di modello, è facoltativamente possibile immettere una descrizione della versione. Fornire una descrizione della versione è una procedura consigliata, anche se non è necessaria. La descrizione della versione riepiloga le modifiche apportate, consentendo a chiunque usi la specifica di modello di selezionare la versione più adatta alle proprie esigenze.

Apportare modifiche a una specifica di modello

Poiché le specifiche di modello sono risorse di Azure, è possibile gestirle come qualsiasi altra risorsa. È quindi possibile visualizzare i dettagli di una specifica di modello, aggiornarla ed eliminarla come di consueto.

Ad esempio, per elencare le versioni di una specifica di modello, usare il cmdlet Get-AzTemplateSpec:

Get-AzTemplateSpec `
  -ResourceGroupName MyResourceGroup `
  -Name MyTemplateSpec

Lo stesso cmdlet viene usato per visualizzare una versione della specifica di modello. Aggiungere il parametro -Version per ottenere i dettagli di una versione:

Get-AzTemplateSpec `
  -ResourceGroupName MyResourceGroup `
  -Name MyTemplateSpec `
  -Version 1.0

È possibile accedere al modello JSON leggendo la proprietà MainTemplate dalla matrice Versions:

(Get-AzTemplateSpec `
  -ResourceGroupName MyResourceGroup `
  -Name MyTemplateSpec `
  -Version 1.0 `
).Versions[0].MainTemplate

Ad esempio, per elencare le versioni di una specifica di modello, usare il comando az ts show:

az ts show \
  --resource-group MyResourceGroup \
  --name MyTemplateSpec

Lo stesso comando viene usato per visualizzare una versione della specifica di modello. Aggiungere l'argomento --version per ottenere i dettagli di una versione:

az ts show \
  --resource-group MyResourceGroup \
  --name MyTemplateSpec \
  --version 1.0

Il modello JSON è incluso nell'output.

Nota

Un file Bicep viene convertito in JSON quando viene pubblicato in una specifica di modello. Non è possibile visualizzare il file Bicep originale, quindi è consigliabile conservarlo in un'altra posizione.

Per aggiornare una specifica di modello esistente, usare il cmdlet Set-AzTemplateSpec. È ad esempio possibile usare questo cmdlet per applicare un aggiornamento rapido a una versione già pubblicata:

Set-AzTemplateSpec `
  -ResourceGroupName MyResourceGroup `
  -Name MyTemplateSpec `
  -Version 1.0 `
  -TemplateFile azuredeploy.json

È invece possibile eliminare una versione della specifica di modello usando il cmdlet Remove-AzTemplateSpec:

Remove-AzTemplateSpec `
  -ResourceGroupName MyResourceGroup `
  -Name MyTemplateSpec `
  -Version 1.0

Per aggiornare una specifica di modello esistente, usare il comando az ts update. È ad esempio possibile usare questo comando per applicare un aggiornamento rapido a una versione già pubblicata:

az ts update \
  --resource-group MyResourceGroup \
  --name MyTemplateSpec \
  --version 1.0 \
  --template-file azuredeploy.json

È invece possibile eliminare una versione della specifica di modello usando il comando az ts delete:

az ts delete \
  --resource-group MyResourceGroup \
  --name MyTemplateSpec \
  --version 1.0

Esportare una specifica di modello

Dopo aver pubblicato un modello come specifica di modello, è possibile esportarlo. Esportando una specifica di modello, il file modello viene scaricato nel computer locale dove è possibile modificare il file modello o semplicemente esaminarlo per comprenderne la funzione.

Suggerimento

Se la specifica di modello include modelli collegati, esportandola vengono scaricati anche i modelli collegati. Viene persino mantenuta la struttura delle cartelle.

Importante

Quando si pubblica un file Bicep come specifica di modello, il codice Bicep viene convertito in un modello JSON. Il processo di conversione del codice Bicep in JSON rimuove alcune informazioni nel file Bicep. Ad esempio, i commenti, i nomi simbolici per le risorse e l'ordine in cui si definiscono le risorse potrebbero mancare o essere diversi in JSON. Non è pertanto possibile pubblicare facilmente un file Bicep come specifica di modello e quindi recuperare il file Bicep originale (roundtrip). È consigliabile conservare una copia del codice Bicep originale in un repository di codice come Git, soprattutto quando si usano le specifiche dei modelli.

Per esportare una specifica di modello, usare il cmdlet Export-AzTemplateSpec. Usare il valore -OutputFolder per specificare dove si vogliono salvare i file modello:

Export-AzTemplateSpec `
  -ResourceGroupName MyResourceGroup `
  -Name MyTemplateSpec `
  -Version 1.0 `
  -OutputFolder ./mytemplate

Per esportare una specifica di modello, usare il comando az ts export. Usare il valore --output-folder per specificare dove si vogliono salvare i file modello:

az ts export \
  --resource-group MyResourceGroup \
  --name MyTemplateSpec \
  --version 1.0 \
  --output-folder ./mytemplate

Controllare l'accesso a una specifica di modello

Le specifiche di modello, essendo risorse di Azure, usano la gestione delle identità e degli accessi (IAM) di Azure. Quando un utente distribuisce una specifica di modello, Azure controlla che l'utente abbia accesso per leggere prima la specifica di modello.

Nota

Per distribuire una specifica di modello, un utente deve:

• Accedere per leggere la specifica di modello.
• Accedere per eseguire la distribuzione nel gruppo di risorse o in un altro ambito richiesto per la distribuzione.

Azure controlla entrambe le condizioni prima dell'avvio della distribuzione.