Procedure consigliate per Bicep

  • Articolo

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

Risorse di formazione

Se si preferisce conoscere le procedure consigliate di Bicep tramite istruzioni dettagliate, 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 chiunque possa distribuire. Si consideri ad esempio l'uso di piani tariffari a basso costo e SKU in modo che un utente che distribuisca il modello in un ambiente di test non comporta un costo elevato inutilmente.

  • Usare l'espressione Decorator @allowed con moderazione. Se si usa questo decoratore troppo ampiamente, è possibile bloccare le distribuzioni valide. Poiché i servizi di Azure aggiungono SKU e dimensioni, l'elenco consentito potrebbe non essere aggiornato. Ad esempio, l'autorizzazione solo degli SKU Premium v3 può essere utile nell'ambiente di produzione, ma impedisce di usare lo 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 dichiarazioni di parametri ovunque nel file di modello, anche se in genere è consigliabile inserirle nella parte superiore 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 più avanti 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 di risoluzione.

  • È possibile usare 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. Passando l'ID del gruppo di risorse significa che la stringa è uguale a ogni distribuzione nello stesso gruppo di risorse, ma diversa quando si distribuisce in gruppi di risorse o sottoscrizioni diverse.

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

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

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

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

    • La uniqueString() funzione non garantisce nomi univoci globali. Aggiungendo testo aggiuntivo ai nomi delle risorse, è possibile ridurre la probabilità di riutilizzare un nome di risorsa esistente.

    • A volte la uniqueString() funzione 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-04-15' = {

    Usare:

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

  • Evitare di distinguere le variabili e i parametri tramite l'uso di suffisso.

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 incollare 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 servizio app, usare la proprietà defaultHostname dell'app anziché creare una stringa per l'URL stesso. A volte questi presupposti non sono corretti in ambienti diversi o le risorse cambiano il modo in cui funzionano. È più sicuro avere la risorsa per indicare 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.

  • Se possibile, evitare di usare le funzioni reference 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.

  • Preferisce usare dipendenze implicite rispetto alle dipendenze esplicite. Anche se la dependsOn proprietà della risorsa consente di dichiarare una dipendenza esplicita tra le risorse, è in genere possibile usare le proprietà dell'altra risorsa usando il 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 existing parola chiave.

Risorse figlio

  • Evitare di annidare troppi livelli profondi. Troppo 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à o l'annidamento parent .

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à in base agli 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