Vytvoření souborů parametrů pro nasazení Bicep

  • Článek

Místo předávání parametrů jako vložených hodnot ve skriptu můžete použít soubor parametrů Bicep s .bicepparam příponou souboru nebo souborem parametrů JSON, který obsahuje hodnoty parametrů. Tento článek ukazuje, jak vytvořit soubory parametrů.

Poznámka:

Soubor parametrů Bicep se podporuje jenom v Rozhraní příkazového řádku Bicep verze 0.18.4 nebo novější, Azure CLI verze 2.47.0 nebo novější a Azure PowerShell verze 9.7.1 nebo novější.

Jeden soubor Bicep může mít přiřazených více souborů parametrů Bicep. Každý soubor parametrů Bicep je však určený pro jeden konkrétní soubor Bicep. Tato relace se naváže pomocí using příkazu v souboru parametrů Bicep.

Soubory parametrů Bicep můžete zkompilovat do souborů parametrů JSON a nasadit je pomocí souboru Bicep. Viz build-params. Můžete také dekompilovat soubor parametrů JSON do souboru parametrů Bicep. Viz dekompil-params.

Soubor parametrů

Soubor parametrů používá následující formát:

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

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

Příkaz using můžete použít se souborem Bicep, šablonami JSON ARM, moduly Bicep a specifikacemi šablon. Příklad:

using './main.bicep'
...

using './azuredeploy.json'
...

using 'br/public:storage/storage-account:3.0.1'
...

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

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

Další informace najdete v příkazu using.

Výrazy můžete použít s výchozí hodnotou. Příklad:

using 'main.bicep'

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

Proměnné prostředí můžete odkazovat jako hodnoty parametrů. Příklad:

using './main.bicep'

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

Můžete definovat a používat proměnné. Bicep CLI verze 0.21.X nebo vyšší je vyžadována pro použití proměnných v souboru .bicepparam. Několik příkladů:

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
}

Je třeba poznamenat, že soubor parametrů ukládá hodnoty parametrů jako prostý text. Z bezpečnostních důvodů se tento přístup nedoporučuje pro citlivé hodnoty, jako jsou hesla. Pokud musíte předat parametr s citlivou hodnotou, ponechte hodnotu v trezoru klíčů. Místo přidání citlivé hodnoty do souboru parametrů použijte funkci getSecret k načtení. Další informace najdete v tématu Použití služby Azure Key Vault k předání hodnoty zabezpečeného parametru během nasazení Bicep.

Formáty typů parametrů

Následující příklad ukazuje formáty různých typů parametrů: string, integer, boolean, array a 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'
}

Pomocí syntaxe Bicep deklarujte objekty a pole.

Název souboru

Soubor parametrů Bicep má příponu .bicepparamsouboru .

Pokud chcete nasadit do různých prostředí, vytvoříte více než jeden soubor parametrů. Když pojmenujete soubory parametrů, identifikujte jejich použití, jako je vývoj a produkce. K nasazení prostředků použijte například main.dev.bicepparam a main.prod.bicepparam .

Definování hodnot parametrů

Chcete-li zjistit, jak definovat názvy a hodnoty parametrů, otevřete váš soubor Bicep. Podívejte se na část parametrů v souboru Bicep. Následující příklady ukazují parametry ze souboru Bicep s názvem main.bicep.

@maxLength(11)
param storagePrefix string

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

V souboru parametrů je prvním detailem, který si všimněte, název každého parametru. Názvy parametrů v souboru parametrů musí odpovídat názvům parametrů v souboru Bicep.

using 'main.bicep'

param storagePrefix
param storageAccountType

Příkaz using prováže soubor parametrů Bicep na soubor Bicep. Další informace najdete v příkazu using.

Po zadání klíčového slova param v editoru Visual Studio Code se zobrazí výzva k zadání dostupných parametrů a jejich popisů z propojeného souboru Bicep:

Snímek obrazovky s výzvou dostupných parametrů

Když najedete myší na název parametru, zobrazí se datový typ a popis parametru.

Snímek obrazovky s datovým typem a popisem parametru

Všimněte si typu parametru. Typy parametrů v souboru parametrů musí používat stejné typy jako váš soubor Bicep. V tomto příkladu jsou oba typy parametrů řetězce.

using 'main.bicep'

param storagePrefix = ''
param storageAccountType = ''

Zkontrolujte parametry v souboru Bicep s výchozí hodnotou. Pokud má parametr výchozí hodnotu, můžete zadat hodnotu v souboru parametrů, ale nevyžaduje se. Hodnota souboru parametrů přepíše výchozí hodnotu souboru Bicep.

using 'main.bicep'

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

Zkontrolujte povolené hodnoty Bicep a všechna omezení, jako je maximální délka. Tyto hodnoty určují rozsah hodnot, které můžete zadat pro parametr. V tomto příkladu storagePrefix může mít maximálně 11 znaků a storageAccountType musí zadat povolenou hodnotu.

using 'main.bicep'

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

Vygenerování souboru parametrů

Pokud chcete vygenerovat soubor parametrů, máte dvě možnosti: buď prostřednictvím editoru Visual Studio Code, nebo pomocí rozhraní příkazového řádku Bicep. Obě metody umožňují odvodit soubor parametrů ze souboru Bicep. V editoru Visual Studio Code naleznete v tématu Generování souboru parametrů. V rozhraní příkazového řádku Bicep viz vygenerování souboru parametrů.

Soubor parametrů sestavení Bicep

Z rozhraní příkazového řádku Bicep můžete sestavit soubor parametrů Bicep do souboru parametrů JSON. Další informace naleznete v tématu Soubor parametrů sestavení.

Nasazení souboru Bicep se souborem parametrů

Azure CLI

Z Azure CLI můžete předat soubor parametrů s nasazením souboru Bicep.

Pomocí Azure CLI verze 2.53.0 nebo novější a rozhraní příkazového řádku Bicep verze 0.22.X nebo vyšší můžete nasadit soubor Bicep pomocí souboru parametrů Bicep. S příkazem using v souboru parametrů Bicep není nutné při zadávání souboru parametrů Bicep pro --parameters přepínač zadat --template-file přepínač.

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

V rámci stejné operace nasazení můžete použít vložené parametry a soubor parametrů umístění. Příklad:

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

Další informace najdete v tématu Nasazení prostředků pomocí Bicep a Azure CLI.

Azure PowerShell

V Azure PowerShellu předejte soubor místních parametrů pomocí parametru TemplateParameterFile .

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

V rámci stejné operace nasazení můžete použít vložené parametry a soubor parametrů umístění. Příklad:

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

Další informace najdete v tématu Nasazení prostředků pomocí Bicep a Azure PowerShellu. K nasazení souborů .bicep potřebujete Azure PowerShell verze 5.6.0 nebo novější.

Priorita parametru

Ve stejné operaci nasazení můžete použít vložené parametry a místní soubor parametrů. Můžete například zadat některé hodnoty v souboru místních parametrů a přidat další hodnoty vložené během nasazení. Pokud zadáte hodnoty parametru v místním souboru parametrů i vložené, bude mít přednost vložená hodnota.

Externí soubor parametrů JSON je možné použít zadáním identifikátoru URI souboru. Externí soubor parametrů Bicep se v současné době nepodporuje. Pokud používáte soubor externích parametrů, nemůžete předávat jiné hodnoty buď vložené, nebo z místního souboru. Všechny vložené parametry se ignorují. Zadejte všechny hodnoty parametrů v externím souboru.

Konflikty názvů parametrů

Pokud váš soubor Bicep obsahuje parametr se stejným názvem jako jeden z parametrů v příkazu PowerShellu, PowerShell zobrazí parametr z vašeho souboru Bicep s příponou FromTemplate. Například parametr pojmenovaný ResourceGroupName v souboru Bicep je v konfliktu s parametrem ResourceGroupName v rutině New-AzResourceGroupDeployment . Zobrazí se výzva k zadání hodnoty ResourceGroupNameFromTemplate. Abyste se vyhnuli tomuto nejasnostem, použijte názvy parametrů, které se nepoužívají pro příkazy nasazení.

Další kroky