Migliorare parametri e nomi
I parametri sono il modo più comune con cui i colleghi interagiranno con il modello. Quando distribuiscono il modello, devono specificare i valori per i parametri. Una volta creato, il nome di una risorsa fornisce informazioni importanti sul suo scopo a chiunque analizzi l'ambiente Azure.
In questa unità verranno illustrate alcune considerazioni chiave quando si pianificano i parametri per i file Bicep e i nomi da assegnare alle risorse.
I parametri sono comprensibili?
I parametri consentono di rendere i file Bicep riutilizzabili e flessibili. È importante che lo scopo di ogni parametro sia chiaro per chiunque lo usi. Quando i colleghi lavorano con il modello, usano i parametri per personalizzare il comportamento della distribuzione.
Si supponga, ad esempio, che sia necessario distribuire un account di archiviazione usando un file Bicep. Una delle proprietà obbligatorie dell'account di archiviazione è il codice di riferimento del prodotto (SKU), che definisce il livello di ridondanza dei dati. Lo SKU ha diverse proprietà, la più importante delle quali è name. Quando si crea un parametro per impostare il valore per lo SKU dell'account di archiviazione, usare un nome chiaramente definito, ad esempio storageAccountSkuName. L'uso di questo valore invece che di un nome generico come sku o skuName consente agli altri utenti di comprendere lo scopo del parametro e gli effetti dell'impostazione del valore.
I valori predefiniti sono un modo importante per rendere il modello utilizzabile per gli altri utenti. È importante usare i valori predefiniti dove hanno senso. Sono utili agli utenti del modello per due motivi:
- I valori predefiniti semplificano il processo di distribuzione del modello. Se i parametri hanno valori predefiniti validi che funzionano per la maggior parte degli utenti del modello, gli utenti possono omettere i valori dei parametri invece di specificarli ogni volta che distribuiscono il modello.
- I valori predefiniti offrono un esempio di come dovrebbe essere il valore del parametro. Se gli utenti del modello devono scegliere un valore diverso, il valore predefinito può fornire indicazioni utili su come dovrebbe essere il valore.
Bicep consente anche di convalidare l'input fornito dagli utenti tramite le espressioni Decorator del parametro. È possibile usare queste espressioni Decorator per fornire una descrizione del parametro o per specificare i tipi di valori consentiti. Bicep offre diversi tipi di espressioni Decorator per i parametri:
Le descrizioni forniscono informazioni leggibili sullo scopo del parametro e sugli effetti dell'impostazione del valore.
I vincoli di valore applicano limiti a ciò che gli utenti possono immettere come valore del parametro. È possibile immettere un elenco di valori specifici consentiti usando l'espressione Decorator
@allowed(). È possibile usare gli elementi Decorator@minValue()e@maxValue()per applicare i valori minimi e massimi per i parametri numerici ed è possibile usare gli elementi Decorator@minLength()e@maxLength()per applicare la lunghezza dei parametri stringa e matrice.Suggerimento
Prestare attenzione quando si usa l'espressione Decorator del parametro
@allowed()per specificare gli SKU. I servizi di Azure spesso aggiungono nuovi SKU e non si vuole che il modello ne impedisca inutilmente l'uso. Valutare l'opportunità di usare Criteri di Azure per imporre l'uso di SKU specifici e usare l'espressione Decorator@allowed()con gli SKU solo quando esistono motivi funzionali per cui gli utenti del modello non devono selezionare uno SKU specifico, ad esempio quando le funzionalità necessarie per il modello potrebbero non essere disponibili in tale SKU. Per spiegarlo, usare un'espressione Decorator@description()o un commento che chiarisca i motivi a chiunque in futuro.I metadati, anche se non sono di uso comune, possono essere applicati per fornire metadati personalizzati aggiuntivi sul parametro.
Fino a che punto deve essere flessibile un file Bicep?
Uno degli obiettivi della definizione dell'infrastruttura come codice è rendere i modelli riutilizzabili e flessibili. Non si vogliono creare modelli con un solo scopo e una configurazione hardcoded. D'altra parte, non ha senso esporre tutte le proprietà delle risorse come parametri. Creare modelli validi per un problema o una soluzione aziendale specifica, non modelli generici che devono funzionare in ogni situazione. Non è nemmeno utile avere così tanti parametri da dover impiegare molto tempo per immettere i valori prima che il modello possa essere distribuito. Ciò è importante soprattutto quando si configurano gli SKU e il numero di istanze delle risorse.
Quando si pianifica un modello, considerare come bilanciare flessibilità e semplicità. Esistono due modi comuni per specificare i parametri nei modelli:
- Specificare le opzioni di configurazione in formato libero
- Usare set di configurazione predefiniti
Valutare entrambi gli approcci usando un file Bicep di esempio che distribuisce un account di archiviazione e un piano di servizio app di Azure.
Specificare le opzioni di configurazione in formato libero
Sia il piano di servizio app che l'account di archiviazione richiedono di specificare gli SKU. Valutare l'opportunità di creare un set di parametri per controllare ogni SKU i numeri di istanze per le risorse:
Ecco come appare il codice in Bicep:
param appServicePlanSkuName string
param appServicePlanSkuCapacity int
param storageAccountSkuName string
resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
name: appServicePlanName
location: location
sku: {
name: appServicePlanSkuName
capacity: appServicePlanSkuCapacity
}
}
resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = {
name: storageAccountSkuName
location: location
sku: {
name: storageAccountSkuName
}
}
Questo formato offre la massima flessibilità, perché chiunque usi il modello può specificare qualsiasi combinazione di valori dei parametri. Tuttavia, man mano che si aggiungono altre risorse, si rendono necessari altri parametri. Il modello diventa di conseguenza più complesso. Potrebbe anche essere necessario limitare determinate combinazioni di parametri o assicurarsi che, quando una risorsa specifica viene distribuita usando uno SKU, un'altra risorsa debba essere distribuita usando uno SKU diverso. Se si specificano troppi parametri distinti, è difficile applicare queste regole.
Suggerimento
Si pensi alle persone che lavoreranno con il modello. Vedere decine di parametri potrebbe scoraggiarle e spingerle a rinunciare a usare il modello.
Si potrebbe ridurre il numero di parametri raggruppando quelli correlati sotto forma di oggetto parametro, come nell'esempio seguente:
param appServicePlanSku object = {
name: 'S1'
capacity: 2
}
Questo approccio può tuttavia limitare la possibilità di convalidare i valori dei parametri e non è sempre facile per gli utenti del modello comprendere come definire l'oggetto.
Usare set di configurazione predefiniti
In alternativa, è possibile specificare un set di configurazione: un singolo parametro, il cui valore è un elenco limitato di valori consentiti, ad esempio un elenco di tipi di ambiente. Quando gli utenti distribuiscono il modello, devono selezionare un valore per quest'unico parametro. Quando selezionano un valore per il parametro, la distribuzione eredita automaticamente un set di configurazione:
La definizione del parametro è simile a questa:
@allowed([
'Production'
'Test'
])
param environmentType string = 'Test'
I set di configurazione offrono una flessibilità inferiore, perché gli utenti che distribuiscono il modello non possono specificare le dimensioni per le singole risorse, ma è possibile convalidare ogni set di configurazioni e assicurarsi che rispettino i requisiti. Grazie ai set di configurazione, per gli utenti del modello non è più indispensabile conoscere tutte le diverse opzioni disponibili per ogni risorsa e diventa più semplice supportare, testare e risolvere i problemi dei modelli.
Quando si lavora con i set di configurazione, si crea una variabile map per definire le proprietà specifiche da impostare per più risorse, in base al valore del parametro:
var environmentConfigurationMap = {
Production: {
appServicePlan: {
sku: {
name: 'P2V3'
capacity: 3
}
}
storageAccount: {
sku: {
name: 'ZRS'
}
}
}
Test: {
appServicePlan: {
sku: {
name: 'S2'
capacity: 1
}
}
storageAccount: {
sku: {
name: 'LRS'
}
}
}
}
Le definizioni delle risorse usano quindi la mappa di configurazione per definire le proprietà delle risorse:
resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
name: appServicePlanName
location: location
sku: environmentConfigurationMap[environmentType].appServicePlan.sku
}
I set di configurazione consentono di rendere più facilmente accessibili i modelli complessi. Possono anche essere utili per applicare regole personalizzate e favorire l'uso di valori di configurazione convalidati in anticipo.
Nota
Questo approccio viene a volte definito dimensionamento di tipo t-shirt. Quando si acquista una t-shirt, non si hanno molte opzioni per lunghezza, larghezza, maniche e così via. Si sceglie semplicemente tra le taglie small, medium e large e chi ha disegnato la t-shirt ha già definito le misure in base alle taglie.
Come vengono denominate le risorse?
In Bicep è importante assegnare alle risorse nomi significativi. Le risorse in Bicep hanno due nomi:
I nomi simbolici vengono usati solo nel file Bicep e non vengono visualizzati nelle risorse di Azure. I nomi simbolici consentono agli utenti che leggono o modificano il modello di comprendere lo scopo di un parametro, una variabile o una definizione di risorsa e di prendere decisioni informate sull'opportunità di modificare il modello.
I nomi di risorsa sono i nomi delle risorse create in Azure. Molte risorse hanno vincoli relativi ai nomi e molte richiedono che i nomi siano univoci.
Nomi simbolici
È importante considerare attentamente i nomi simbolici che vengono applicati alle risorse. Si supponga che alcuni colleghi debbano modificare il modello. Saranno in grado di comprendere a che cosa serve ogni risorsa?
Si supponga, ad esempio, di voler definire un account di archiviazione contenente i manuali dei prodotti che gli utenti potranno scaricare dal sito Web. È possibile assegnare alla risorsa un nome simbolico, ad esempio storageAccount, ma, se si trova in un file Bicep che contiene molte altre risorse e magari anche altri account di archiviazione, tale nome non è sufficientemente descrittivo. È quindi possibile assegnarle un nome simbolico che ne indichi lo scopo, ad esempio productManualStorageAccount.
In Bicep si applica in genere lo stile camelCase per l'uso di maiuscole e minuscole nei nomi di parametri e variabili e nei nomi simbolici delle risorse. Ciò significa che la prima parola avrà la prima lettera minuscola, mentre le altre parole avranno la prima lettera maiuscola (come nell'esempio precedente, productManualStorageAccount). Non è obbligatorio usare lo stile camelCase. Se si sceglie di adottare uno stile diverso, è importante concordare uno standard all'interno del team e usarlo in modo coerente.
Nomi delle risorse
Ogni risorsa di Azure ha un nome. I nomi sono una parte dell'identificatore della risorsa. In molti casi, sono rappresentati anche come nomi host usati per accedere alla risorsa. Quando, ad esempio, si crea un'app di Servizio app denominata myapp, il nome host usato per accedere all'app sarà myapp.azurewebsites.net. Non è possibile rinominare le risorse dopo la distribuzione.
È importante valutare bene come assegnare il nome alle risorse di Azure. Molte organizzazioni definiscono la propria convenzione di denominazione delle risorse. Cloud Adoption Framework per Azure contiene indicazioni specifiche per definire quella desiderata. Lo scopo di una convenzione di denominazione delle risorse è consentire a tutti gli utenti dell'organizzazione di comprendere a che cosa serve ogni risorsa.
Ogni risorsa di Azure ha inoltre determinate regole e restrizioni per la denominazione. Esistono, ad esempio, restrizioni per la lunghezza dei nomi e i caratteri che possono includere e restrizioni che determinano se i nomi devono essere univoci a livello globale o solo all'interno di un gruppo di risorse.
Seguire tutte le convenzioni di denominazione per l'organizzazione e i requisiti di denominazione per Azure può essere complesso. Un modello Bicep ben scritto non deve lasciar trasparire questa complessità agli utenti e determinare automaticamente i nomi delle risorse. Ecco un esempio di approccio da seguire:
Aggiungere un parametro usato per creare un suffisso di univocità. In questo modo ci si assicura che le risorse abbiano nomi univoci. È consigliabile usare la funzione
uniqueString()per generare un valore predefinito. Le persone che distribuiscono il modello possono eseguirne l'override con un valore specifico se preferiscono un nome significativo. Assicurarsi di usare l'espressione Decorator@maxLength()per limitare la lunghezza di questo suffisso in modo che i nomi delle risorse non superino la lunghezza massima.Suggerimento
È meglio usare i suffissi di univocità invece dei prefissi. Questo approccio consente di ordinare facilmente e analizzare rapidamente i nomi delle risorse. Alcune risorse di Azure prevedono anche restrizioni relative al primo carattere del nome e i nomi generati in modo casuale possono a volte violare queste restrizioni.
Usare le variabili per costruire i nomi delle risorse in modo dinamico. Il codice Bicep può garantire che i nomi generati seguano la convenzione di denominazione dell'organizzazione, oltre che i requisiti di Azure. Includere il suffisso di univocità nel nome della risorsa.
Nota
Non per tutte le risorse è necessario un nome univoco globale. Valutare se includere il suffisso di univocità nel nome di ogni risorsa o solo di quelle per cui è necessario.