Condividi tramite

Creare un file di parametri per la distribuzione Bicep

I file di parametri Bicep consentono di definire i valori in un singolo file che vengono quindi passati al main.bicep file. Il file di parametri espone valori che possono cambiare da una determinata sottoscrizione, ambiente e/o area. L'uso di un file di parametri determina la coerenza nelle distribuzioni IaC, offrendo al tempo stesso flessibilità. Alcune di queste flessibilità potrebbero consentire a un'organizzazione di sfruttare i vantaggi dei costi ridimensionando correttamente gli ambienti non di produzione mantenendo allo stesso tempo la stessa infrastruttura di base.

Questi file di parametri consentono anche di abilitare un approccio di distribuzione CI/CD semplificato. Ogni file di parametri è sotto il controllo del codice sorgente e viene passato ai passaggi di distribuzione automatizzati appropriati. Questi file di parametri garantiscono un'esperienza di distribuzione coerente.

Questo articolo illustra come creare un file di parametri, che è possibile usare invece di passare parametri come valori inline nello script. È possibile usare un file di parametri Bicep con l'estensione .bicepparam di file o un file di parametri JSON che contiene il valore del parametro.

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. La using none funzionalità è supportata in Bicep CLI dalla versione 0.31.0 in poi.

Un singolo file Bicep può essere associato a più file di parametri. Tuttavia, in genere ogni file di parametri è collegato a un file Bicep specifico, a meno che non venga specificato using none. Questa associazione viene stabilita usando l'istruzioneusing all'interno del file di parametri.

È possibile compilare file di parametri Bicep in file di parametri JSON che è possibile distribuire usando 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.

File dei parametri

Un file di parametri usa il formato seguente:

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

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

È possibile applicare l'istruzione using usando un file Bicep, i modelli di Azure Resource Manager JSON, i moduli Bicep e le specifiche dei modelli. Ad esempio:

using './main.bicep'
...

using './azuredeploy.json'
...

using 'br/public:avm/res/storage/storage-account:0.9.0' 
...

using 'br:myacr.azurecr.io/bicep/modules/storage:v1'
...

using 'ts:00000000-0000-0000-0000-000000000000/myResourceGroup/storageSpec:1.0'
...

Per altre informazioni, vedere Utilizzo dell’istruzione.

È possibile applicare l'istruzione using none per indicare che il file di parametri non è associato a un modello Bicep specifico durante la creazione o la compilazione. In questo modo il file di parametri viene separato da un modello specifico, consentendo una maggiore flessibilità nella definizione e nell'uso dei parametri tra le distribuzioni. Per altre informazioni, vedere Using none statement.

You can use expressions with the default value. For example:

```bicep
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
}

Note

Un file di parametri salva i valori dei parametri come testo normale. Per motivi di sicurezza, non è consigliabile usare questo approccio con valori sensibili, ad esempio password.

Se è necessario passare un parametro con un valore sensibile, è necessario mantenere il valore in un insieme di credenziali 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.

Formati dei tipi di parametro

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.

Nome del file

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

Per eseguire la distribuzione in più ambienti, creare più 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.

Definire i valori dei parametri

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, cercare 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 dei parametri Bicep a un file Bicep. 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 è obbligatorio. 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'

Generare 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.

Creare un file dei parametri 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

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. Con l'istruzione using all'interno del file di parametri Bicep, non è necessario fornire l'opzione --template-file quando si specifica un file di parametri Bicep per l'opzione --parameters.

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.

Precedenza 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.

Conflitti nei nomi di parametro

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