Procedure consigliate per Bicep

  • Articolo

Questo articolo consiglia le procedure da seguire per lo sviluppo di file Bicep. Queste procedure semplificano la comprensione e l'uso del file Bicep.

Risorse di formazione

Per informazioni sulle procedure consigliate di Bicep, vedere Strutturare il codice Bicep per la collaborazione.

Parametri

  • È importante scegliere con cura i nomi usati nelle dichiarazioni dei parametri. Nomi adeguati rendono i modelli facili da leggere e da capire. Assicurarsi di usare nomi chiari e descrittivi e una denominazione coerente.

  • Riflettere attentamente sui parametri utilizzati dal modello. Provare a usare parametri per le impostazioni che cambiano tra una distribuzione e l'altra. Per le impostazioni che non cambiano tra le distribuzioni si possono usare variabili e valori hardcoded.

  • Prestare attenzione ai valori predefiniti che si usano. Assicurarsi che i valori predefiniti siano sicuri per tutti gli utenti da distribuire. Si consideri, ad esempio, l'uso di piani tariffari e SKU a basso costo in modo che un utente che distribuisce il modello in un ambiente di test non incorra inutilmente in un costo elevato.

  • Usare l'espressione Decorator @allowed con moderazione. Se si usa questo elemento Decorator in modo troppo ampio, è possibile bloccare le distribuzioni valide. Man mano che i servizi di Azure aggiungono SKU e dimensioni, l'elenco consentito potrebbe non essere aggiornato. Ad esempio, la possibilità di consentire solo SKU Premium v3 potrebbe avere senso nell'ambiente di produzione, ma impedisce l'uso dello stesso modello in ambienti non di produzione.

  • È buona norma fornire descrizioni per i parametri. Provare a creare descrizioni utili e fornire tutte le informazioni importanti sui requisiti del modello in termini di valori dei parametri.

    È anche possibile usare commenti // per aggiungere note all'interno dei file Bicep.

  • È possibile inserire le dichiarazioni di parametri in qualsiasi punto del file modello, anche se in genere è consigliabile inserirle all'inizio del file in modo che il codice Bicep sia facile da leggere.

  • È consigliabile specificare la lunghezza minima e massima del carattere per i parametri che controllano la denominazione. Queste limitazioni consentono di evitare errori in un secondo momento durante la distribuzione.

Per altre informazioni sui parametri Bicep, vedere Parametri in Bicep.

Variabili

  • Quando si definisce una variabile, il tipo di dati non è necessario. Le variabili deducono il tipo dal valore risolvere.

  • È possibile usare le funzioni Bicep per creare una variabile.

  • Dopo aver definito una variabile nel file Bicep, si fa riferimento al valore usando il nome della variabile.

Per altre informazioni sulle variabili Bicep, vedere Variabili in Bicep.

Nomi

  • Usare maiuscole minuscole per i nomi, ad esempio myVariableName o myResource.

  • La funzione uniqueString() è utile per la creazione di nomi di risorse univoci. Quando si specificano gli stessi parametri, restituisce la stessa stringa ogni volta. Il passaggio all'ID del gruppo di risorse significa che la stringa è la stessa in ogni distribuzione nello stesso gruppo di risorse, ma diversa quando si esegue la distribuzione in gruppi di risorse o sottoscrizioni diversi.

  • È consigliabile usare espressioni modello per creare nomi di risorse, come in questo esempio:

    param shortAppName string = 'toy'
param shortEnvironmentName string = 'prod'
param appServiceAppName string = '${shortAppName}-${shortEnvironmentName}-${uniqueString(resourceGroup().id)}'

    L'uso delle espressioni modello per creare nomi di risorse offre diversi vantaggi:

    • Le stringhe generate da uniqueString() non sono significative. È utile usare un'espressione modello per creare un nome che includa informazioni significative, ad esempio un breve descrittore del progetto o del nome dell'ambiente, nonché un componente casuale per rendere più probabile che il nome sia univoco.

    • La funzione uniqueString() non garantisce nomi univoci a livello globale. Aggiungendo testo aggiuntivo ai nomi delle risorse, si riduce la probabilità di riutilizzare un nome di risorsa esistente.

    • A volte la funzione uniqueString() crea stringhe che iniziano con un numero. Alcune risorse di Azure come gli account di archiviazione, tuttavia, non supportano nomi che iniziano con un numero. Questo requisito significa che è consigliabile usare l'interpolazione di stringhe per creare nomi di risorse. È possibile aggiungere un prefisso alla stringa univoca.

    • Per molti tipi di risorse di Azure sono previste regole specifiche per i caratteri consentiti e la lunghezza dei nomi. Incorporando la creazione dei nomi di risorse nel modello, chiunque usi il modello non deve ricordarsi di seguire queste regole.

  • Evitare di usare name in un nome simbolico. Il nome simbolico rappresenta la risorsa, non il nome della risorsa. Ad esempio, anziché la sintassi seguente:

    resource cosmosDBAccountName 'Microsoft.DocumentDB/databaseAccounts@2023-11-15' = {

    Usare:

    resource cosmosDBAccount 'Microsoft.DocumentDB/databaseAccounts@2023-11-15' = {

  • Evitare di distinguere variabili e parametri usando suffissi.

Definizioni delle risorse

  • Anziché incorporare espressioni complesse direttamente nelle proprietà delle risorse, usare le variabili per contenere le espressioni. Questo approccio semplifica la lettura e la comprensione del file Bicep. Evita di includere le definizioni delle risorse con la logica.

  • Cercare di usare proprietà di risorse come output, anziché azzardare supposizioni sul comportamento delle risorse. Ad esempio, se è necessario restituire l'URL a un'app del servizio app, usare la proprietà defaultHostname dell'app invece di creare una stringa per l'URL manualmente. A volte questi presupposti non sono corretti in ambienti diversi o le risorse cambiano il modo in cui funzionano. È più sicuro che la risorsa dica le proprie proprietà.

  • È consigliabile usare una versione recente dell'API per ogni risorsa. Le nuove funzionalità dei servizi di Azure sono talvolta disponibili solo nelle versioni più recenti dell'API.

  • Quando possibile, evitare di usare le funzioni di riferimento e resourceId nel file Bicep. È possibile accedere a qualsiasi risorsa in Bicep usando il nome simbolico. Ad esempio, se si definisce un account di archiviazione con il nome simbolico toyDesignDocumentsStorageAccount, è possibile accedere al relativo ID risorsa usando l'espressione toyDesignDocumentsStorageAccount.id. Usando il nome simbolico, si crea una dipendenza implicita tra le risorse.

  • Preferire l'uso di dipendenze implicite rispetto alle dipendenze esplicite. Anche se la proprietà della risorsa dependsOn consente di dichiarare una dipendenza esplicita tra le risorse, in genere è possibile usare le proprietà dell'altra risorsa usando il relativo nome simbolico. Questo approccio crea una dipendenza implicita tra le due risorse e consente a Bicep di gestire la relazione stessa.

  • Se la risorsa non viene distribuita nel file Bicep, è comunque possibile ottenere un riferimento simbolico alla risorsa usando la parola chiave existing.

Risorse figlio

  • Evitare di annidare troppi livelli in profondità. Un numero eccessivo di annidamento rende il codice Bicep più difficile da leggere e usare.

  • Evitare di costruire nomi di risorse per le risorse figlio. Si perdono i vantaggi offerti da Bicep quando comprende le relazioni tra le risorse. Usare invece la proprietà parent o l'annidamento.

Output

  • Assicurarsi di non creare output per i dati sensibili. I valori di output sono accessibili a chiunque abbia accesso alla cronologia di distribuzione. Non sono appropriati per la gestione dei segreti.

  • Anziché passare i valori delle proprietà tramite output, usare la parola chiave esistente per cercare le proprietà delle risorse già esistenti. È consigliabile cercare le chiavi da altre risorse in questo modo anziché passarle attraverso gli output. Si otterranno sempre i dati più aggiornati.

Per altre informazioni sugli output bicep, vedere Output in Bicep.

Ambiti tenant

Non è possibile creare criteri o assegnazioni di ruolo nell'ambito del tenant. Tuttavia, se è necessario concedere l'accesso o applicare criteri all'intera organizzazione, è possibile distribuire queste risorse nel gruppo di gestione radice.

Passaggi successivi