Creare un file di parametri per la distribuzione Bicep

I file di parametri Bicep consentono di definire i valori dei parametri in un file separato e di passarli al file main.bicep. Sono ideali per i valori che variano in base a sottoscrizione, ambiente o area geografica.

I vantaggi principali includono:

  • Mantenere la coerenza tra le distribuzioni IaC (Infrastructure as Code) abilitando al contempo la flessibilità.
  • Supportare l'ottimizzazione dei costi, ad esempio il ridimensionamento corretto degli ambienti non di produzione senza modificare l'infrastruttura di base.
  • Abilitare pipeline CI/CD semplificate mantenendo i file dei parametri nel controllo del codice sorgente e passando il file appropriato a ogni fase di distribuzione.

Note

I file di parametri Bicep sono supportati solo nell'interfaccia della riga di comando di Bicep versione 0.18.4 o successiva, nell'interfaccia della riga di comando di Azure versione 2.47.0 o successiva e in Azure PowerShell versione 9.7.1 o successiva.

È possibile usare una delle due operazioni seguenti:

  • Un file di parametri Bicep nativo (con estensione .bicepparam) o
  • Un file di parametri JSON standard.

L'estensione di file per un file di parametri Bicep è .bicepparam.

Per eseguire la distribuzione in più ambienti, creare più di un file di parametri. Quando si usano più file di parametri, etichettarli in base al loro uso. Ad esempio, per distribuire le risorse, usare l'etichetta main.dev.bicepparam per lo sviluppo e l'etichetta main.prod.bicepparam per la produzione.

È possibile compilare i file di parametri Bicep in file di parametri JSON da distribuire tramite un file Bicep. Per altre informazioni, vedere build-params. È anche possibile decompilare un file di parametri JSON in un file di parametri Bicep. Per altre informazioni, vedere decompile-params.

Avvertimento

Un file di parametri salva i valori dei parametri come testo normale. Per motivi di sicurezza, non usare questo approccio con valori sensibili, ad esempio password. Se si deve passare un parametro con un valore sensibile, conservare il valore in un archivio protetto delle chiavi. Invece di aggiungere un valore sensibile al file dei parametri, utilizzare la funzione getSecret per recuperarlo. Per altre informazioni, vedere Usare Azure Key Vault per passare un segreto come parametro durante la distribuzione di Bicep.

Definire il file dei parametri

Un file di parametri usa il formato seguente:

using '<path>/<file-name>.bicep' | using none

type <user-defined-data-type-name> = <type-expression>

var <variable-name> <data-type> = <variable-value>

param <first-parameter-name> = <first-value>
param <second-parameter-name> = <second-value>
param <third-parameter-name> = <variable-name>

Per determinare come definire i nomi e i valori dei parametri, aprire il file Bicep. Esaminare la sezione del file Bicep relativa ai parametri. Gli esempi seguenti illustrano i parametri di un file Bicep denominato main.bicep:

@maxLength(11)
param storagePrefix string

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
param storageAccountType string = 'Standard_LRS'

Nel file dei parametri usare il nome di ogni parametro. I nomi dei parametri nel file di parametri devono corrispondere ai nomi dei parametri nel file Bicep.

using 'main.bicep'

param storagePrefix
param storageAccountType

L'istruzione using collega il file di parametri di Bicep a un file Bicep. È possibile associare più file di parametri a un singolo file Bicep. Ogni file di parametri si collega in genere a un file di Bicep specifico usando l'istruzione using.

Usare using none se non si vuole collegare il file dei parametri a un determinato file di Bicep. Bicep CLI versione 0.31.0 o versione successiva supporta la funzionalità using none.

Per altre informazioni, vedere Utilizzo dell’istruzione.

Quando si digita la parola chiave param in Visual Studio Code, vengono richiesti i parametri disponibili e le relative descrizioni dal file Bicep collegato.

Screenshot della richiesta dei parametri disponibili.

Quando si passa il puntatore del mouse su un nome param, è possibile visualizzare il tipo di dati e la descrizione del parametro.

Screenshot del tipo di dati e della descrizione del parametro.

Esaminare il tipo di parametro, perché i tipi di parametro nel file dei parametri devono usare gli stessi tipi del file Bicep. In questo esempio, entrambi i tipi di parametro sono stringhe:

using 'main.bicep'

param storagePrefix = ''
param storageAccountType = ''

Controllare il file Bicep per i parametri che includono un valore predefinito. Se un parametro ha un valore predefinito, è possibile specificare un valore nel file dei parametri, ma non è necessario. Il valore del file dei parametri sostituisce il valore predefinito del file Bicep.

using 'main.bicep'

param storagePrefix = '' // This value must be provided.
param storageAccountType = '' // This value is optional. Bicep uses default value if not provided.

Per verificare se sono presenti restrizioni come la lunghezza massima, controllare i valori consentiti del file Bicep. I valori consentiti specificano l'intervallo di valori che è possibile specificare per un parametro. In questo esempio, storagePrefix può avere un massimo di 11 caratteri e storageAccountType deve specificare un valore consentito.

using 'main.bicep'

param storagePrefix = 'storage'
param storageAccountType = 'Standard_ZRS'

Il seguente esempio mostra i formati dei vari tipi di parametro: stringa, intero, booleano, matrice e oggetto.

using './main.bicep'

param exampleString = 'test string'
param exampleInt = 2 + 2
param exampleBool = true
param exampleArray = [
  'value 1'
  'value 2'
]
param exampleObject = {
  property1: 'value 1'
  property2: 'value 2'
}

Usare la sintassi Bicep per dichiarare oggetti e matrici.

È possibile usare espressioni come valori del parametro. Ad esempio:

using './main.bicep'

param storageName = toLower('MyStorageAccount')
param intValue = 2 + 2

È possibile fare riferimento alle variabili di ambiente come valori dei parametri. Ad esempio:

using './main.bicep'

param intFromEnvironmentVariables = int(readEnvironmentVariable('intEnvVariableName'))

È possibile definire e usare le variabili. È necessario usare l'interfaccia della riga di comando di Bicep versione 0.21.X o successiva per usare le variabili nei file .bicepparam. Vedere gli esempi seguenti:

using './main.bicep'

var storagePrefix = 'myStorage'
param primaryStorageName = '${storagePrefix}Primary'
param secondaryStorageName = '${storagePrefix}Secondary'

using './main.bicep'

var testSettings = {
  instanceSize: 'Small'
  instanceCount: 1
}

var prodSettings = {
  instanceSize: 'Large'
  instanceCount: 4
}

param environmentSettings = {
  test: testSettings
  prod: prodSettings
}

È possibile definire tipi di dati definiti dall'utente. Ad esempio:

using './main.bicep'

// Define a reusable type for tags with optional properties
type TagValues = {
  environment: 'dev' | 'test' | 'production'
  project: string
}

var tagsExample TagValues = {
  environment: 'dev'
  project: 'bicep-sample'
}

param tags = tagsExample

Generare e compilare un file di parametri

È possibile creare un file di parametri usando Visual Studio Code o l'interfaccia della riga di comando di Bicep. Entrambi gli strumenti consentono di usare un file Bicep per generare un file di parametri. Vedere Generare un file di parametri per il metodo con Visual Studio Code e Generare un file di parametri per il metodo con l'interfaccia della riga di comando Bicep.

Dall'interfaccia della riga di comando di Bicep è possibile compilare un file di parametri Bicep in un file di parametri JSON. Per ulteriori informazioni, vedere File di parametri di compilazione.

Distribuire il file Bicep con il file dei parametri

È possibile usare i parametri inline e un file di parametri locale nella stessa operazione di distribuzione. Ad esempio, è possibile specificare alcuni valori nel file di parametri locale e aggiungere altri valori inline durante la distribuzione. Se si specificano valori per un parametro sia nel file dei parametri locale che inline, il valore inline ha la precedenza.

Anche se i file di parametri Bicep esterni non sono attualmente supportati, è possibile usare un file di parametri JSON esterno fornendo l'URI al file. Quando si usa un file di parametri esterni, specificare tutti i valori dei parametri nel file esterno. Quando si usa un file esterno, non è possibile passare altri valori inline o da un file locale e tutti i parametri inline vengono ignorati.

L'esempio seguente mostra un esempio interfaccia della riga di comando di Azure per l'uso di un file di parametri JSON esterno:

az deployment group create \
  --resource-group my-rg \
  --template-file main.bicep \
  --parameters https://storageaccount.blob.core.windows.net/templates/main.parameters.json

Interfaccia della riga di comando di Azure

Dall'interfaccia della riga di comando di Azure è possibile passare un file di parametri con la distribuzione di file Bicep.

È possibile distribuire un file Bicep usando un file di parametri Bicep con l'interfaccia della riga di comando di Azure versione 2.53.0 o successiva e l'interfaccia della riga di comando Bicep versione 0.22.X o successiva. Usando l'istruzione all'interno del file dei parametri Bicep, non è necessario fornire l'opzione quando si specifica un file di parametri Bicep per l'opzione .

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --parameters storage.bicepparam

È possibile usare parametri inline e un file di parametri di posizione nella stessa operazione di distribuzione. Ad esempio:

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --parameters storage.bicepparam \
  --parameters storageAccountType=Standard_LRS

Per altre informazioni, vedere Distribuire file Bicep usando l'interfaccia della riga di comando di Azure.

Azure PowerShell

Da Azure PowerShell, passare un file di parametri locale usando il parametro TemplateParameterFile.

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateFile C:\MyTemplates\storage.bicep `
  -TemplateParameterFile C:\MyTemplates\storage.bicepparam

È possibile usare parametri inline e un file di parametri di posizione nella stessa operazione di distribuzione. Ad esempio:

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateFile C:\MyTemplates\storage.bicep `
  -TemplateParameterFile C:\MyTemplates\storage.bicepparam `
  -storageAccountType Standard_LRS

Per altre informazioni, vedere Distribuire file Bicep con Azure PowerShell. Per distribuire .bicep file, è necessario Azure PowerShell versione 5.6.0 o successiva.

Se il file Bicep include un parametro con lo stesso nome di uno dei parametri nel comando di Azure PowerShell, Azure PowerShell aggiunge al parametro del file Bicep il suffisso FromTemplate. Ad esempio, se un parametro denominato ResourceGroupName nel file Bicep è in conflitto con il parametro ResourceGroupName nel New-AzResourceGroupDeployment cmdlet, viene richiesto di specificare un valore per ResourceGroupNameFromTemplate. Per evitare questa confusione, usare i nomi dei parametri che non vengono usati per i comandi di distribuzione.

Contenuti correlati

  • Last updated on