Pianificare la struttura del file Bicep

Completato

Bicep offre la flessibilità necessaria per decidere come strutturare il codice. In questa unità si vedrà come è possibile strutturare il codice Bicep e verrà illustrata l'importanza di uno stile coerente e di un codice Bicep chiaro e comprensibile.

Quale ordine deve seguire il codice Bicep?

I modelli Bicep possono contenere molti elementi, tra cui parametri, variabili, risorse, moduli, output e un elemento targetScope per l'intero modello. Bicep non impone agli elementi un ordine da seguire. È tuttavia importante considerare l'ordine degli elementi per assicurarsi che il modello sia chiaro e comprensibile.

È possibile ordinare il codice in base a due approcci principali:

• Raggruppare gli elementi per tipo
• Raggruppare gli elementi per risorsa

Concordare con il team quello da adottare e usarlo in modo coerente.

Raggruppare gli elementi per tipo

È possibile raggruppare tutti gli elementi dello stesso tipo. In questo modo, tutti i parametri vengono collocati nella stessa posizione, in genere all'inizio del file. Poi vengono le variabili, seguite da risorse e moduli, e infine gli output. Si potrebbe avere, ad esempio, un file Bicep che distribuisce un database SQL Azure e un account di archiviazione.

Quando si raggruppano gli elementi per tipo, questi potrebbero essere simili al seguente:

Suggerimento

Se si segue questa convenzione, valutare l'opportunità di inserire targetScope all'inizio del file.

Questo ordinamento ha senso quando si è abituati ad altre infrastrutture come linguaggi di codice(ad esempio, il linguaggio nei modelli di Azure Resource Manager). Può anche rendere più comprensibile il modello, perché è chiaro dove cercare tipi specifici di elementi. Nei modelli più lunghi, tuttavia, può essere difficile spostarsi tra gli elementi e passare da uno all'altro.

È comunque necessario decidere come ordinare gli elementi all'interno di queste categorie. È consigliabile raggruppare i parametri correlati. Ad esempio, tutti i parametri relativi a un account di archiviazione vanno insieme e, al suo interno, i parametri SKU dell'account di archiviazione vanno insieme.

Analogamente, è possibile raggruppare le risorse correlate. In questo modo, chiunque usi il modello, può esplorarlo rapidamente e comprenderne le parti importanti.

A volte, si crea un modello che distribuisce una risorsa primaria, con più risorse di supporto secondarie. È ad esempio possibile creare un modello per distribuire un sito Web ospitato in Servizio app di Azure. La risorsa primaria è l'app del servizio app. Le risorse secondarie nello stesso modello possono includere il piano di servizio app, l'account di archiviazione, l'istanza di Application Insights e altre. Con un modello come questo, è consigliabile inserire la risorsa primaria o le risorse all'inizio della sezione delle risorse del modello, in modo che chiunque apra il modello possa identificarne rapidamente lo scopo e trovare le risorse importanti.

Raggruppare gli elementi per risorsa

In alternativa, è possibile raggruppare gli elementi in base al tipo di risorse da distribuire. Continuando con l'esempio precedente, è possibile raggruppare tutti i parametri, le variabili, le risorse e gli output correlati alle risorse del database SQL Azure. È quindi possibile aggiungere i parametri, le variabili, le risorse e gli output per l'account di archiviazione, come illustrato di seguito:

Con il raggruppamento per risorsa, è più facile leggere il modello, perché tutti gli elementi necessari per una risorsa specifica sono in un'unica posizione, Tuttavia, è più difficile controllare rapidamente come vengono dichiarati i tipi di elementi specifici quando, ad esempio, si vogliono esaminare tutti i parametri.

È anche necessario considerare come gestire i parametri e le variabili comuni a più risorse, ad esempio un parametro environmentType, quando si usa una mappa di configurazione. I parametri e le variabili comuni dovrebbero trovarsi nella stessa posizione, in genere all'inizio del file Bicep.

Suggerimento

Valutare l'opportunità di creare moduli per i gruppi di risorse correlate e quindi usare un modello più semplice per combinare i moduli. I moduli Bicep sono illustrati in modo più dettagliato nei percorsi di apprendimento relativi a Bicep.

Qual è l'utilità degli spazi per la creazione della struttura?

Le righe vuote, ovvero gli spazi, consentono di aggiungere una struttura visiva al modello. Usando attentamente gli spazi, è possibile raggruppare le sezioni del codice Bicep in modo logico, rendendo più chiare le relazioni tra le risorse. A tale scopo, valutare l'opportunità di aggiungere una riga vuota tra le sezioni principali, indipendentemente dallo stile di raggruppamento preferito.

Come si definiscono più risorse simili?

Con Bicep è possibile usare i cicli per distribuire le risorse simili da una singola definizione. Usando la parola chiave for per definire i cicli di risorse, è possibile rendere il codice Bicep più chiaro e ridurre la duplicazione non necessaria delle definizioni delle risorse. In futuro, quando sarà necessario modificare la definizione delle risorse, sarà sufficiente aggiornare una sola posizione. Per impostazione predefinita, quando Azure Resource Manager distribuisce le risorse, le distribuisce tutte contemporaneamente nel ciclo, in modo che la distribuzione sia il più efficiente possibile.

Cercare le posizioni in cui si definiscono più risorse identiche o con poche differenze nelle proprietà. Aggiungere quindi una variabile per elencare le risorse da creare, insieme alle proprietà diverse da quelle delle altre risorse. L'esempio seguente usa un ciclo per definire un set di contenitori di Azure Cosmos DB, ognuno dei quali ha un nome e una chiave di partizione specifici:

var cosmosDBContainerDefinitions = [
  {
    name: 'customers'
    partitionKey: '/customerId'
  }
  {
    name: 'orders'
    partitionKey: '/orderId'
  }
  {
    name: 'products'
    partitionKey: '/productId'
  }
]

resource cosmosDBContainers 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers@2024-05-15' = [for cosmosDBContainerDefinition in cosmosDBContainerDefinitions: {
  parent: cosmosDBDatabase
  name: cosmosDBContainerDefinition.name
  properties: {
    resource: {
      id: cosmosDBContainerDefinition.name
      partitionKey: {
        kind: 'Hash'
        paths: [
          cosmosDBContainerDefinition.partitionKey
        ]
      }
    }
    options: {}
  }
}]

Come si distribuiscono le risorse solo in determinati ambienti?

In alcuni casi, si definiscono risorse che devono essere distribuite solo in ambienti specifici o in determinate condizioni. Usando la parola chiave if, è possibile distribuire le risorse in modo selettivo in base al valore di un parametro, alla variabile di una mappa di configurazione o a un'altra condizione. L'esempio seguente usa una mappa di configurazione per distribuire le risorse di registrazione per gli ambienti di produzione, ma non per gli ambienti di test:

var environmentConfigurationMap = {
  Production: {
    enableLogging: true
  }
  Test: {
    enableLogging: false
  }
}

resource logAnalyticsWorkspace 'Microsoft.OperationalInsights/workspaces@2023-09-01' = if (environmentConfigurationMap[environmentType].enableLogging) {
  name: logAnalyticsWorkspaceName
  location: location
}

resource cosmosDBAccountDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = if (environmentConfigurationMap[environmentType].enableLogging) {
  scope: cosmosDBAccount
  name: cosmosDBAccountDiagnosticSettingsName
  properties: {
    workspaceId: logAnalyticsWorkspace.id
    // ...
  }
}

Come si esprimono le dipendenze tra le risorse?

In qualsiasi modello Bicep complesso è necessario esprimere le dipendenze tra le risorse. Quando Bicep comprende le dipendenze tra le risorse, le distribuisce nell'ordine corretto.

Bicep consente di specificare in modo esplicito una dipendenza usando la proprietà dependsOn. Nella maggior parte dei casi, tuttavia, è possibile consentire a Bicep di rilevare automaticamente le dipendenze. Quando si usa il nome simbolico di una risorsa in una proprietà di un'altra, Bicep rileva la relazione. È meglio consentire a Bicep di gestirle direttamente ogni volta che è possibile. In questo modo, quando si modifica il modello, Bicep verifica che le dipendenze siano sempre corrette e si evita di aggiunge codice non necessario che rende il modello più complesso e più difficile da leggere.

Come si esprimono le relazioni padre-figlio?

Azure Resource Manager e Bicep prevedono l'uso delle risorse figlio, che ha senso solo quando vengono distribuite nel contesto del padre. Un database SQL di Azure, ad esempio, è un figlio di un'istanza di SQL server. Le risorse figlio possono essere definite in diversi modi, ma nella maggior parte dei casi è consigliabile usare la proprietà parent, Ciò consente a Bicep di comprendere la relazione in modo che possa fornire la convalida in Visual Studio Code e rende chiara la relazione con chiunque altro legge il modello.

Come si impostano le proprietà delle risorse?

È necessario specificare i valori per le proprietà delle risorse nei file Bicep. È bene prestare attenzione quando si impostano come hardcoded i valori nelle definizioni delle risorse. Se si è certi che i valori non cambieranno, potrebbe essere meglio impostarli come hardcoded invece di usare un altro parametro che renderebbe il modello più difficile da testare e usare. Se invece esiste la possibilità che i valori cambino, valutare l'opportunità di definirli come parametri o variabili per rendere il codice Bicep più dinamico e riutilizzabile.

Quando si impostano i valori come hardcoded, è bene assicurarsi che siano comprensibili per gli altri utenti. Se ad esempio una proprietà deve essere impostata su un valore specifico in modo che il comportamento della risorsa sia corretto per la soluzione, valutare l'opportunità di creare una variabile con un nome descrittivo che fornisca una spiegazione e quindi di assegnare il valore usando la variabile. Nei casi in cui il nome di una variabile non è sufficientemente descrittivo, valutare l'opportunità di aggiungere un commento. Altre informazioni sui commenti verranno fornite più avanti in questo modulo.

Per alcune proprietà delle risorse, per costruire automaticamente i valori, è necessario creare espressioni complesse che includono le funzioni e l'interpolazione delle stringhe. Il codice Bicep è in genere più chiaro quando si dichiarano le variabili, a cui si fa riferimento nei blocchi di codice delle risorse.

Suggerimento

Quando si creano output, provare a usare le proprietà delle risorse ovunque sia possibile. Evitare di incorporare i propri presupposti sul funzionamento delle risorse, perché questi presupposti potrebbero cambiare nel tempo.

Ad esempio, se è necessario restituire l'URL di un'app servizio app, evitare di costruire un URL:

output hostname string = '${app.name}.azurewebsites.net'

L'approccio precedente avrà esito negativo se servizio app modifica il modo in cui assegna nomi host alle app o se si esegue la distribuzione negli ambienti di Azure che usano URL diversi.

È consigliabile usare invece la proprietà defaultHostname della risorsa app:

output hostname string = app.properties.defaultHostname

Come usare il controllo della versione in modo efficace?

I sistemi di controllo della versione come Git consentono di semplificare il lavoro quando si effettua il refactoring del codice.

Poiché i sistemi di controllo della versione sono progettati per tenere traccia delle modifiche ai file, è possibile usarli per tornare facilmente a una versione precedente del codice se si commette un errore. È consigliabile eseguire spesso il commit del lavoro per poter tornare esattamente al momento necessario.

Il controllo della versione consente anche di rimuovere il codice precedente dai file Bicep. Come comportarsi se il codice Bicep include la definizione di una risorsa che non è più necessaria? Poiché la definizione potrebbe essere di nuovo necessaria in futuro, si potrebbe essere tentati di limitarsi a impostarla come commento e lasciarla nel file. In realtà, conservandola si crea solo disordine nel file Bicep e per gli altri utenti sarà difficile comprendere perché le risorse impostate come commento sono ancora presenti.

Si deve anche considerare la possibilità che qualcuno rimuova accidentalmente il commento dalla definizione, con conseguenze imprevedibili o potenzialmente negative. Quando si usa un sistema di controllo della versione, è sufficiente rimuovere la definizione precedente della risorsa. Se la definizione sarà nuovamente necessaria in futuro, sarà possibile recuperarla dalla cronologia del file.