Bicep デプロイ用のパラメーター ファイルを作成する

  • [アーティクル]

パラメーターをスクリプト内のインライン値として渡す代わりに、.bicepparam ファイル拡張子を持つ Bicep パラメーター ファイルまたはパラメーター値を含む JSON パラメーター ファイルを使用できます。 この記事では、パラメーター ファイルを作成する方法について説明します。

Note

Bicep パラメーター ファイルは、Bicep CLI バージョン 0.18.4 以降、Azure CLI バージョン 2.47.0 以降、Azure PowerShell バージョン 9.7.1 以降でのみサポートされています。

1 つの Bicep ファイルには複数の Bicep パラメーター ファイルを関連付けることができます。 ただし、各 Bicep パラメーター ファイルは、1 つの特定の Bicep ファイルを対象としています。 この関係は、Bicep パラメーター ファイル内の usingステートメントを使用して確立されます。

Bicep パラメーター ファイルを JSON パラメーター ファイルにコンパイルし、Bicep ファイルを使用してデプロイを行うことができます。 詳しくは、「build-params」をご覧ください。 Bicep パラメーター ファイルを JSON パラメーター ファイルに逆コンパイルすることもできます。 「decompile-params」を参照してください。

パラメーター ファイル

パラメーター ファイルでは次の形式を使用します。

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

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

using ステートメントは、Bicep ファイル、ARM JSON テンプレート、Bicep モジュール、テンプレート スペックと共に使用できます。 次に例を示します。

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

詳細については、「using ステートメント」を参照してください。

既定値を指定した式を使用できます。 次に例を示します。

using 'main.bicep'

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

環境変数はパラメーター値として参照できます。 次に例を示します。

using './main.bicep'

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

変数を定義して使用できます。 .bicepparam ファイルで変数を使用するためには、Bicep CLI バージョン 0.21.X 以降が必要です。 次に例をいくつか示します。

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
}

パラメーター ファイルはパラメーター値をプレーン テキストとして保存することに注意することは重要です。 セキュリティ上の理由から、この方法はパスワードなどの機密性の高い値には、推奨されません。 機密性の高い値を含むパラメーターを渡す必要がある場合は、値をキー コンテナーに保持してください。 機密性の高い値は、パラメーター ファイルに追加するのではなく、getSecret 関数を使用して取得します。 詳細については、「Bicep デプロイ時に Azure Key Vault を使用して、セキュリティで保護されたパラメーター値を渡す」を参照してください。

パラメーターの型の形式

次の例は、さまざまなパラメーターの型 (文字列、整数、ブール値、配列、およびオブジェクト) の形式を示しています。

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

Bicep 構文を使用して、オブジェクトと配列を宣言します。

ファイル名

Bicep パラメーター ファイルのファイル拡張子は .bicepparam です。

さまざまな環境にデプロイするには、複数のパラメーター ファイルを作成します。 パラメーター ファイルに名前を付けるときは、開発や運用など、その用途を明確にします。 たとえば、main.dev.bicepparam と main.prod.bicepparam を使用してリソースをデプロイします。

パラメーター値を定義する

パラメーターの名前と値を定義する方法を決定するには、Bicep ファイルを開きます。 Bicep ファイルのパラメーター セクションを確認します。 次の例は、main.bicep という名前の Bicep ファイルのパラメーターを示しています。

@maxLength(11)
param storagePrefix string

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

パラメーター ファイルで最初に注目するべき詳細は、各パラメーターの名前です。 パラメーター ファイル内のパラメーター名は、Bicep ファイル内のパラメーター名と一致する必要があります。

using 'main.bicep'

param storagePrefix
param storageAccountType

using ステートメントは、Bicep パラメーター ファイルを Bicep ファイルに結びつけます。 詳細については、「using ステートメント」を参照してください。

Visual Studio Code でキーワード param を入力すると、次のように、リンクされた Bicep ファイルから使用可能なパラメーターとその説明が候補表示されます。

使用可能なパラメーターの候補表示のスクリーンショット。

パラメーター名の上にホバーすると、パラメーターのデータ型と説明を確認できます。

パラメーターのデータ型と説明のスクリーンショット。

パラメーターの型に注目します。 パラメーター ファイル内のパラメーターの型は、Bicep ファイルと同じ型を使用する必要があります。 この例では、両方のパラメーターの型が文字列です。

using 'main.bicep'

param storagePrefix = ''
param storageAccountType = ''

Bicep ファイルで既定値が設定されているパラメーターを調べます。 パラメーターに既定値がある場合は、パラメーター ファイルで値を指定できますが、必須ではありません。 パラメーター ファイルの値によって、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.

Bicep の許可されている値と、最大長などの制限を確認します。 これらの値は、パラメーターに指定できる値の範囲を規定します。 この例では、storagePrefix は最大 11 文字を指定でき、storageAccountType には許可される値を指定する必要があります。

using 'main.bicep'

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

パラメーター ファイルの生成

パラメーター ファイルを生成するには、Visual Studio Code 経由または Bicep CLI を使用するという 2 つの選択肢があります。 どちらの方法でも、Bicep ファイルからパラメーター ファイルを派生させることができます。 Visual Studio Code の「パラメーター ファイルの生成」を参照してください。 Bicep CLI の「パラメーター ファイルの生成」を参照してください。

Bicep パラメーター ファイルのビルド

Bicep CLI から、Bicep パラメーター ファイルを JSON パラメーター ファイルにビルドできます。 詳細については、「パラメーター ファイルの構築」を参照してください。

パラメーター ファイルを使用して Bicep ファイルをデプロイする

Azure CLI

Azure CLI から、Bicep ファイル デプロイでパラメーター ファイルを渡すことができます。

Azure CLI バージョン 2.53.0 以降と Bicep CLI バージョン 0.22.X 以降では、Bicep パラメーター ファイルを使用して Bicep ファイルをデプロイできます。 Bicep パラメーター ファイル内の using ステートメントを使用すると、--parameters スイッチの Bicep パラメーター ファイルを指定するときに --template-file スイッチを指定する必要はありません。

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

同じデプロイ操作で、インライン パラメータと場所パラメータ ファイルを使用できます。 次に例を示します。

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

詳細については、「Bicep と Azure CLI を使用してリソースをデプロイする」を参照してください。

Azure PowerShell

Azure PowerShell からは、TemplateParameterFile パラメーターを使用してローカル パラメーター ファイルを渡します。

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

同じデプロイ操作で、インライン パラメータと場所パラメータ ファイルを使用できます。 次に例を示します。

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

詳細については、「Bicep と Azure PowerShell を使用してリソースをデプロイする」を参照してください。 .bicep ファイルをデプロイするには、Azure PowerShell バージョン 5.6.0 以降が必要です。

パラメーターの優先順位

同じデプロイ操作で、インライン パラメーターとローカル パラメーター ファイルを使用できます。 たとえば、ローカル パラメーター ファイル内の一部の値を指定し、その他の値をデプロイ中にインラインで追加できます。 ローカル パラメーター ファイルとインラインの両方でパラメーターの値を指定すると、インラインの値が優先されます。

ファイルへの URI を指定することで、外部 JSON パラメータ ファイルを使用できます。 外部 Bicep パラメータ ファイルは現在サポートされていません。 外部パラメーター ファイルを使用する場合、他の値をインラインまたはローカル ファイルから渡すことはできません。 すべてのインライン パラメーターは無視されます。 すべてのパラメーター値を外部ファイル内で指定します。

パラメーター名の競合

PowerShell コマンドのパラメーターのいずれかと同じ名前のパラメーターが Bicep ファイルに含まれている場合、PowerShell では Bicep ファイル内のパラメーター名の後ろに FromTemplate という文字を付加します。 たとえば、Bicep ファイル内の ResourceGroupName という名前のパラメーターは、New-AzResourceGroupDeployment コマンドレットの ResourceGroupName パラメーターと競合します。 ResourceGroupNameFromTemplate の値を指定するように求められます。 この混乱を回避するには、デプロイ コマンドに使用されていないパラメーター名を使用してください。

次のステップ