Aggiungere parametri e output ai moduli

  • 7 minuti

Ogni modulo che si crea deve avere uno scopo chiaro. È come se il modulo avesse un contratto. Accetta un set di parametri, crea un set di risorse e può fornire alcuni output al modello padre. Chi usa il modulo non deve preoccuparsi di come funziona, solo che esegua quanto previsto.

Durante la pianificazione di un modulo, valutare:

  • Le informazioni da conoscere per poter soddisfare lo scopo del modulo.
  • Le informazioni che dovranno essere fornite da coloro che utilizzano il modulo.
  • Quali sono gli output previsti da coloro che utilizzano il modulo.

Parametri di modulo

Pensare ai parametri accettati dal modulo e per ogni parametro valutare se dovrà essere facoltativo o obbligatorio.

Quando si creano parametri per i modelli, è consigliabile aggiungere parametri predefiniti, laddove possibile. Nei moduli non è sempre importante aggiungere parametri predefiniti perché il modulo verrà usato da un modello padre che potrebbe usare i propri parametri predefiniti. Se sono presenti parametri simili in entrambi i file, entrambi con valori predefiniti, è difficile che gli utenti del modello comprendano quale valore predefinito verrà applicato e come imporre la coerenza. È spesso preferibile lasciare il valore predefinito nel modello padre e rimuoverlo dal modulo.

È anche consigliabile considerare come gestire i parametri che controllano gli SKU per le risorse e altre impostazioni di configurazione importanti. Quando si crea un modello Bicep autonomo, è comune incorporare nel modello le regole business. Ad esempio: Quando si distribuisce un ambiente di produzione, l'account di archiviazione deve usare il livello di archiviazione con ridondanza geografica. La creazione dei moduli presenta talvolta alcune problematiche.

Se si sta creando un modulo che deve essere riutilizzabile e flessibile, tenere presente che le regole business per ogni modello padre potrebbero essere diverse, quindi potrebbe non avere molto senso incorporare regole business in moduli generici. Valutare l'opportunità di definire le regole business nel modello padre, quindi passare in modo esplicito la configurazione del modulo tramite i parametri.

Tuttavia, se si crea un modulo destinato a semplificare la distribuzione delle risorse che soddisfano esigenze specifiche per l'organizzazione, è consigliabile includere regole business per semplificare i modelli padre.

Per qualsiasi parametro incluso nel modulo, assicurarsi di aggiungere una descrizione significativa usando l'attributo @description:

@description('The name of the storage account to deploy.')
param storageAccountName string

Usare le condizioni

Uno degli obiettivi della distribuzione di un'infrastruttura usando codice come Bicep consiste nell'evitare eventuali attività duplicate o anche la creazione di diversi modelli per gli stessi scopi o per scopi simili. Le funzionalità di Bicep offrono una potente casella degli strumenti per creare moduli riutilizzabili che funzionano per svariate situazioni. È possibile combinare funzionalità come moduli, espressioni, valori di parametri predefiniti e condizioni per compilare codice riutilizzabile che offre la flessibilità necessaria.

Si supponga di creare un modulo che distribuisce un account Azure Cosmos DB. Quando viene distribuito nell'ambiente di produzione, è necessario configurare l'account per inviare i log a un'area di lavoro Log Analytics. Per configurare i log da inviare a Log Analytics, definire una risorsa diagnosticSettings.

È possibile soddisfare questo requisito aggiungendo una condizione alla definizione della risorsa e rendendo facoltativo il parametro ID area di lavoro aggiungendo un valore predefinito:

param logAnalyticsWorkspaceId string = ''

resource cosmosDBAccount 'Microsoft.DocumentDB/databaseAccounts@2022-08-15' = {
  // ...
}

resource cosmosDBAccountDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' =  if (logAnalyticsWorkspaceId != '') {
  scope: cosmosDBAccount
  name: 'route-logs-to-log-analytics'
  properties: {
    workspaceId: logAnalyticsWorkspaceId
    logs: [
      {
        category: 'DataPlaneRequests'
        enabled: true
      }
    ]
  }
}

Quando si include questo modulo in un modello Bicep, è possibile configurarlo facilmente per inviare i log dell'account Azure Cosmos DB a Log Analytics impostando un ID area di lavoro. In alternativa, se non sono necessari log per l'ambiente distribuito, omettere il parametro. Ha un valore predefinito. Il modulo incapsula la logica necessaria per eseguire le operazioni appropriate in base ai requisiti.

Suggerimento

Ricordare di testare la validità del modello per entrambi gli scenari: quando l'istruzione if viene valutata come true o false.

Output del modulo

I moduli possono invece definire un output. È consigliabile creare un output per le informazioni che il modello padre potrebbe dover usare. Ad esempio, se il modulo definisce un account di archiviazione, è opportuno creare un output per il nome dell'account di archiviazione in modo che il modello padre possa accedervi.

Avviso

Non usare gli output per i valori segreti. Gli output vengono registrati come parte della cronologia della distribuzione, quindi non sono appropriati per i valori sicuri. In tal caso, valutare una delle opzioni seguenti:

  • Usare un output per specificare il nome della risorsa. Il modello padre può quindi creare una risorsa existing con tale nome e cercare il valore sicuro in modo dinamico.
  • Scrivere il valore in un segreto di Azure Key Vault. Quando è necessario, il modello padre leggerà il segreto dall'insieme di credenziali.

Un modello padre può usare gli output del modulo nelle variabili, può usare le proprietà per altre definizioni di risorsa oppure può esporre variabili e proprietà come output. Esponendo e usando gli output in tutti i file Bicep, è possibile creare set riutilizzabili di moduli Bicep che possono essere condivisi con il team e riutilizzati in più distribuzioni. È anche consigliabile aggiungere una descrizione significativa agli output usando l'attributo @description:

@description('The fully qualified Azure resource ID of the blob container within the storage account.')
output blobContainerResourceId string = storageAccount::blobService::container.id

Suggerimento

È anche possibile usare servizi dedicati per archiviare, gestire e accedere alle impostazioni create dal modello Bicep. Key Vault è progettato per archiviare valori sicuri. Configurazione app di Azure è un servizio progettato per archiviare altri valori (non sicuri).

Concatenare i moduli

È prassi comune creare un file Bicep padre che composto da più moduli. Si supponga, ad esempio, di creare un nuovo modello Bicep per distribuire macchine virtuali che usano reti virtuali dedicate. È possibile creare un modulo per definire una rete virtuale. È quindi possibile accettare l'ID risorsa della subnet di rete virtuale come output da tale modulo e usarlo come input per il modulo della macchina virtuale:

@description('Username for the virtual machine.')
param adminUsername string

@description('Password for the virtual machine.')
@minLength(12)
@secure()
param adminPassword string

module virtualNetwork 'modules/vnet.bicep' = {
  name: 'virtual-network'
}

module virtualMachine 'modules/vm.bicep' = {
  name: 'virtual-machine'
  params: {
    adminUsername: adminUsername
    adminPassword: adminPassword
    subnetResourceId: virtualNetwork.outputs.subnetResourceId
  }
}

In questo esempio vengono usati nomi simbolici per il riferimento tra i moduli. Questo riferimento consente a Bicep di comprendere automaticamente le relazioni tra i moduli.

Poiché Bicep riconosce che esiste una dipendenza, distribuisce i moduli in sequenza:

  1. Bicep distribuisce tutto nel modulo virtualNetwork.
  2. Se la distribuzione ha esito positivo, Bicep accede al valore di output subnetResourceId e lo passa al modulo virtualMachine come parametro.
  3. Bicep distribuisce tutto nel modulo virtualMachine.

Nota

Quando si dipende da un modulo, Bicep attende il completamento dell'intera distribuzione del modulo. È importante ricordarlo quando si pianificano i moduli. Se si crea un modulo che definisce una risorsa che richiede molto tempo per la distribuzione, tutte le altre risorse che dipendono da tale modulo attenderanno il completamento della distribuzione dell'intero modulo.