Delen via

Een parameterbestand maken voor Bicep-implementatie

Met Bicep-parameterbestanden kunt u waarden definiëren in een afzonderlijk bestand dat vervolgens aan uw main.bicep bestand wordt doorgegeven. In het parameterbestand worden waarden weergegeven die kunnen veranderen van een bepaald abonnement, een bepaalde omgeving en/of regio. Door gebruik te maken van een parameterbestand, wordt consistentie in uw IaC-implementaties aangedreven en biedt u ook flexibiliteit. Met sommige van deze flexibiliteit kan een organisatie profiteren van kostenvoordelen door de juiste grootte van hun niet-productieomgevingen te wijzigen en tegelijkertijd dezelfde kerninfrastructuur te onderhouden.

Deze parameterbestanden helpen ook bij het inschakelen van een gestroomlijnde CI/CD-implementatie. Elk parameterbestand staat onder broncodebeheer en wordt doorgegeven aan de juiste geautomatiseerde implementatiestappen. Deze parameterbestanden zorgen voor een consistente implementatie-ervaring.

In dit artikel leest u hoe u een parameterbestand maakt, dat u kunt gebruiken in plaats van parameters door te geven als inlinewaarden in uw script. U kunt een Bicep-parametersbestand gebruiken met de .bicepparam bestandsextensie of een JSON-parameterbestand dat de parameterwaarde bevat.

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. De using none functie wordt ondersteund in Bicep CLI versie 0.31.0 of hoger.

Eén Bicep-bestand kan worden gekoppeld aan meerdere parameterbestanden. Elk parameterbestand wordt echter meestal gekoppeld aan één specifiek Bicep-bestand, tenzij dit is opgegeven using none. Deze koppeling wordt tot stand gebracht met behulp van de using instructie in het parameterbestand.

U kunt Bicep-parametersbestanden compileren in JSON-parametersbestanden 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-parametersbestand. Zie decompile-params voor meer informatie.

Parametersbestand

Een parameterbestand gebruikt de volgende indeling:

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

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

U kunt de using instructie toepassen met behulp van een Bicep-bestand, JSON Azure Resource Manager-sjablonen, Bicep-modules en sjabloonspecificaties. Voorbeeld:

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

Zie Using-instructie voor meer informatie.

U kunt de using none instructie toepassen om aan te geven dat het parameterbestand niet is gekoppeld aan een specifieke Bicep-sjabloon tijdens het ontwerpen of compileren. Hierdoor wordt het parameterbestand losgekoppeld van een bepaalde sjabloon, waardoor u meer flexibiliteit hebt bij het definiëren en gebruiken van parameters voor implementaties. Zie Gebruik van none statement voor meer informatie.

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

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

Notitie

In een parameterbestand worden parameterwaarden opgeslagen als tekst zonder opmaak. Om veiligheidsredenen raden we u niet aan deze benadering te gebruiken met gevoelige waarden, zoals wachtwoorden.

Als u een parameter met een gevoelige waarde moet doorgeven, moet u de waarde in een sleutelkluis behouden. 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.

Parametertype-indelingen

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.

Bestandsnaam

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.

Parameterwaarden definiëren

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'

Zoek in het parameterbestand naar 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 using instructie koppelt het Bicep-parameterbestand aan een Bicep-bestand. Zie Using-instructie 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 deze is niet vereist. 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'

Parametersbestand genereren

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.

Bicep-parametersbestand bouwen

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

Bicep-bestand met parametersbestand implementeren

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. Met de using instructie in het Bicep-parametersbestand hoeft u de --template-file schakeloptie niet op te geven bij het opgeven van een Bicep-parametersbestand 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.

Parameterprioriteit

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.

Conflicten in parameternamen

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