Een parameterbestand maken voor Bicep-implementatie

Met Bicep-parameterbestanden kunt u parameterwaarden definiëren in een apart bestand en deze doorgeven aan uw main.bicep. Ze zijn perfect voor waarden die variëren per abonnement, omgeving of regio.

Belangrijke voordelen zijn onder andere:

  • Behoud consistentie tussen IaC-implementaties (Infrastructure as Code) terwijl u flexibiliteit mogelijk maakt.
  • Ondersteuning voor kostenoptimalisatie, zoals het juiste formaat van niet-productieomgevingen zonder de kerninfrastructuur te wijzigen.
  • Schakel gestroomlijnde CI/CD-pijplijnen in door parameterbestanden in broncodebeheer te houden en het juiste bestand door te geven aan elke implementatiefase.

Notitie

Bicep-parametersbestanden worden alleen ondersteund in Bicep CLI versie 0.18.4 of hoger, Azure CLI versie 2.47.0 of hoger en Azure PowerShell versie 9.7.1 of hoger.

U kunt een van de volgende opties gebruiken:

  • Een systeemeigen Bicep parameterbestand (.bicepparam-extensie) of
  • Een standaardbestand met JSON-parameters.

De bestandsextensie voor een Bicep-parametersbestand is .bicepparam.

Als u wilt implementeren in meerdere omgevingen, maakt u meer dan één parameterbestand. Wanneer u meerdere parameterbestanden gebruikt, moet u ze labelen op basis van hun gebruik. Als u bijvoorbeeld resources wilt implementeren, gebruikt u het label main.dev.bicepparam voor ontwikkeling en het label main.prod.bicepparam voor productie.

U kunt Bicep parameterbestanden compileren in JSON-parameterbestanden die u kunt implementeren met behulp van een Bicep-bestand. Zie build-params voor meer informatie. U kunt ook een JSON-parameterbestand decompileren in een Bicep parameterbestand. Zie decompile-params voor meer informatie.

Warning

In een parameterbestand worden parameterwaarden opgeslagen als tekst zonder opmaak. Gebruik deze methode om veiligheidsredenen niet met gevoelige waarden zoals wachtwoorden. Als u een parameter met een gevoelige waarde moet doorgeven, bewaar de waarde dan in een sleutelkluis. In plaats van een gevoelige waarde toe te voegen aan uw parameterbestand, gebruikt u de getSecret functie om deze op te halen. Zie Azure Key Vault gebruiken om een geheim door te geven als parameter tijdens de bicep-implementatie voor meer informatie.

Parametersbestand definiëren

Een parameterbestand gebruikt de volgende indeling:

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

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

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

import {<symbol_name> [as <alias_name>], ...} from '<bicep_file_name>'

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

Als u wilt bepalen hoe u parameternamen en -waarden definieert, opent u het Bicep-bestand. Bekijk de parameters sectie van het Bicep-bestand. In de volgende voorbeelden ziet u de parameters uit een Bicep-bestand met de naam main.bicep:

@maxLength(11)
param storagePrefix string

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

Gebruik in het parameterbestand de naam van elke parameter. De parameternamen in het parameterbestand moeten overeenkomen met de parameternamen in uw Bicep-bestand.

using 'main.bicep'

param storagePrefix
param storageAccountType

De instructie using koppelt het Bicep-parameterbestand aan een Bicep-bestand. U kunt meerdere parameterbestanden koppelen aan één Bicep-bestand. Elk parameterbestand wordt doorgaans gekoppeld aan een specifiek Bicep-bestand met behulp van de instructie using.

Gebruik using none als u het parameterbestand niet wilt koppelen aan een bepaald Bicep bestand. Bicep CLI-versie 0.31.0 of hoger ondersteunt de functie using none.

Zie Using-instructie voor meer informatie.

De extends-instructie neemt parameters over van een basisbestand .bicepparam, waardoor parameterwaarden kunnen worden hergebruikt en in het huidige parameterbestand selectief kunnen worden overschreven. Zie Uitbreidbare parameterbestanden voor meer informatie.

Wanneer u het trefwoord param in Visual Studio Code typt, wordt u gevraagd om de beschikbare parameters en de bijbehorende beschrijvingen uit het gekoppelde Bicep-bestand.

Schermopname van de prompt van de beschikbare parameters.

Wanneer u een param naam aanwijst, ziet u het gegevenstype en de beschrijving van de parameter.

Schermopname van het gegevenstype en de beschrijving van de parameter.

Controleer het parametertype, omdat de parametertypen in het parameterbestand dezelfde typen moeten gebruiken als uw Bicep-bestand. In dit voorbeeld zijn beide parametertypen tekenreeksen:

using 'main.bicep'

param storagePrefix = ''
param storageAccountType = ''

Controleer het Bicep-bestand op parameters die een standaardwaarde bevatten. Als een parameter een standaardwaarde heeft, kunt u een waarde opgeven in het parameterbestand, maar dat hoeft u niet te doen. De parameterbestandswaarde overschrijft de standaardwaarde van het Bicep-bestand.

using 'main.bicep'

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

Als u wilt zien of er beperkingen zijn zoals maximale lengte, controleert u de toegestane waarden van het Bicep-bestand. De toegestane waarden geven het bereik van waarden op dat u voor een parameter kunt opgeven. In dit voorbeeld storagePrefix mogen maximaal 11 tekens zijn en storageAccountType moet een toegestane waarde worden opgegeven.

using 'main.bicep'

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

In het volgende voorbeeld ziet u de indelingen van verschillende parametertypen: tekenreeks, geheel getal, Booleaanse waarde, matrix en object.

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'
}

Gebruik bicep-syntaxis om objecten en matrices te declareren.

U kunt expressies gebruiken als parameterwaarden. Voorbeeld:

using './main.bicep'

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

U kunt naar omgevingsvariabelen verwijzen als parameterwaarden. Voorbeeld:

using './main.bicep'

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

U kunt variabelen definiëren en gebruiken. U moet Bicep CLI versie 0.21.X of hoger gebruiken om variabelen in .bicepparam bestanden te kunnen gebruiken. Zie de volgende voorbeelden:

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
}

U kunt door de gebruiker gedefinieerde gegevenstypen definiëren. Voorbeeld:

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

U kunt ook variabelen, door de gebruiker gedefinieerde gegevenstypen en door de gebruiker gedefinieerde functies importeren vanuit een Bicep-bestand. Zie Importeren voor meer informatie.

Bestand met uitbreidbare parameters

Zie Parameterbestand uitbreiden voor meer informatie.

Parametersbestand genereren en bouwen

U kunt een parameterbestand maken met Visual Studio Code of de Bicep CLI. Met beide hulpprogramma's kunt u een Bicep-bestand gebruiken om een parameterbestand te genereren. Zie Parametersbestand genereren voor de Visual Studio Code-methode en Parametersbestand genereren voor de Bicep CLI-methode.

Vanuit de Bicep CLI kunt u een Bicep-parametersbestand bouwen in een JSON-parametersbestand. Zie buildparametersbestand voor meer informatie.

Bicep-bestand met parametersbestand implementeren

U kunt inlineparameters en een lokaal parameterbestand in dezelfde implementatiebewerking gebruiken. U kunt bijvoorbeeld bepaalde waarden opgeven in het bestand met lokale parameters en andere waarden inline toevoegen tijdens de implementatie. Als u waarden opgeeft voor een parameter in zowel het lokale parameterbestand als inline, heeft de inlinewaarde voorrang.

Hoewel externe Bicep-parametersbestanden momenteel niet worden ondersteund, kunt u een extern JSON-parameterbestand gebruiken door de URI aan het bestand op te geven. Wanneer u een bestand met externe parameters gebruikt, geeft u alle parameterwaarden op in het externe bestand. Wanneer u een extern bestand gebruikt, kunt u geen andere waarden inline of vanuit een lokaal bestand doorgeven en worden alle inlineparameters genegeerd.

In het volgende voorbeeld ziet u een Azure CLI voorbeeld voor het gebruik van een extern JSON-parameterbestand:

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

Azure-CLI

Vanuit de Azure CLI kunt u een parameterbestand bij de implementatie van uw Bicep-bestand doorgeven.

U kunt een Bicep-bestand implementeren met behulp van een Bicep-parametersbestand met Azure CLI versie 2.53.0 of hoger en Bicep CLI versie 0.22.X of hoger. Als u de instructie using in het parameterbestand Bicep gebruikt, hoeft u de schakeloptie --template-file niet op te geven bij het opgeven van een Bicep parameterbestand voor de --parameters-switch.

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

U kunt inlineparameters en een locatieparametersbestand gebruiken in dezelfde implementatiebewerking. Voorbeeld:

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

Zie Bicep-bestanden implementeren met behulp van de Azure CLI voor meer informatie.

Azure PowerShell

Geef vanuit Azure PowerShell een lokaal parameterbestand door met behulp van de TemplateParameterFile parameter.

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

U kunt inlineparameters en een locatieparametersbestand gebruiken in dezelfde implementatiebewerking. Voorbeeld:

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

Zie Bicep-bestanden implementeren met Azure PowerShell voor meer informatie. Als u bestanden wilt implementeren .bicep , hebt u Azure PowerShell versie 5.6.0 of hoger nodig.

Als uw Bicep-bestand een parameter bevat met dezelfde naam als een van de parameters in de Azure PowerShell-opdracht, geeft Azure PowerShell de parameter uit uw Bicep-bestand weer met het FromTemplate achtervoegsel. Als een parameter met de naam ResourceGroupName in uw Bicep-bestand bijvoorbeeld conflicteert met de ResourceGroupName parameter in de New-AzResourceGroupDeployment cmdlet, wordt u gevraagd een waarde op te geven voor ResourceGroupNameFromTemplate. Gebruik parameternamen die niet worden gebruikt voor implementatieopdrachten om deze verwarring te voorkomen.

Gerelateerde inhoud

  • Last updated on