Создание файлов параметров для развертывания Bicep

Статья
06/28/2024

Вместо передачи параметров в виде встроенных значений в скрипте можно использовать файл параметров Bicep с .bicepparam расширением файла или файлом параметров JSON, который содержит значения параметров. В этой статье показано, как создать файлы параметров.

Примечание.

Файл параметров Bicep поддерживается только в Bicep CLI версии 0.18.4 или более поздней версии, Azure CLI версии 2.47.0 или более поздней, а azure PowerShell версии 9.7.1 или более поздней версии.

С одним файлом Bicep может быть связано несколько файлов параметров Bicep. Однако каждый файл параметров Bicep предназначен для одного конкретного файла Bicep. Эта связь устанавливается с помощью инструкции using в файле параметров Bicep.

Файлы параметров Bicep можно компилировать в файлы параметров JSON для развертывания с помощью Bicep-файла. См . раздел "Сборка-парамс". Вы также можете декомпилировать файл параметров JSON в файл параметров Bicep. См . раздел decompile-params.

Файл параметров

Файл параметров использует следующий формат:

Файл параметров Bicep
ФАЙЛ параметров JSON

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

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

Инструкцию using можно использовать с Bicep-файлом, шаблонами JSON ARM, модулями Bicep и спецификациями шаблонов. Например:

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

Дополнительные сведения см. в инструкции using.

Выражения можно использовать со значением по умолчанию. Например:

using 'main.bicep'

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

Вы можете ссылаться на переменные среды в качестве значений параметров. Например:

using './main.bicep'

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

Можно определить и использовать переменные. Для использования переменных в Bicep CLI версии 0.21.X или более поздней версии требуется использование переменных в файле Bicepparam. Далее приводятся некоторые примеры.

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
}

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "<first-parameter-name>": {
      "value": "<first-value>"
    },
    "<second-parameter-name>": {
      "value": "<second-value>"
    }
  }
}

Следует отметить, что файл параметров сохраняет значения параметров в виде обычного текста. По соображениям безопасности этот подход не рекомендуется использовать для конфиденциальных значений, таких как пароли. Если необходимо передать параметр с конфиденциальным значением, сохраните значение в хранилище ключей. Вместо добавления конфиденциального значения в файл параметров используйте функцию getSecret, чтобы получить ее. Дополнительные сведения см. в статье Использование Azure Key Vault для передачи защищенного значения параметра во время развертывания Bicep.

Форматы типов параметров

В следующем примере показаны форматы различных типов параметров: строка, целое число, логическое значение, массив и объект.

Файл параметров Bicep
ФАЙЛ параметров JSON

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 для объявления объектов и массивов.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "exampleString": {
      "value": "test string"
    },
    "exampleInt": {
      "value": 4
    },
    "exampleBool": {
      "value": true
    },
    "exampleArray": {
      "value": [
        "value 1",
        "value 2"
      ]
    },
    "exampleObject": {
      "value": {
        "property1": "value1",
        "property2": "value2"
      }
    }
  }
}

Файл параметров Bicep имеет расширение .bicepparamфайла.

Чтобы развернуть в разных средах, создайте несколько файлов параметров. При имени файлов параметров определите их использование, например разработку и рабочую среду. Например, используйте main.dev.bicepparam и main.prod.bicepparam для развертывания ресурсов.

Определение значений параметров

Чтобы понять, как определить имена и значения параметров, откройте файл Bicep. Взгляните на раздел параметров файла Bicep. В следующих примерах показаны параметры из вызываемого main.bicepBicep-файла.

@maxLength(11)
param storagePrefix string

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

В файле параметров в первую очередь следует заметить имя каждого параметра. Имена параметров в файле параметров должны совпадать с именами параметров в файле Bicep.

Файл параметров Bicep
ФАЙЛ параметров JSON

using 'main.bicep'

param storagePrefix
param storageAccountType

Инструкция using связывает файл параметров Bicep с файлом Bicep. Дополнительные сведения см . в инструкции using.

После ввода ключевое слово param в Visual Studio Code появится запрос доступных параметров и их описания из связанного файла Bicep:

Снимок экрана: запрос доступных параметров.

При наведении указателя мыши на имя param можно просмотреть тип и описание параметров.

Снимок экрана: тип данных параметра и описание.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
    },
    "storageAccountType": {
    }
  }
}

Обратите внимание на тип параметра. Типы параметров в файле параметров должны использовать те же типы, что и файл Bicep. В этом примере оба типа параметров являются строками.

Файл параметров Bicep
ФАЙЛ параметров JSON

using 'main.bicep'

param storagePrefix = ''
param storageAccountType = ''

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
      "value": ""
    },
    "storageAccountType": {
      "value": ""
    }
  }
}

Проверьте файл Bicep на наличие параметров со значением по умолчанию. Если параметр имеет значение по умолчанию, можно указать значение в файле параметров, но это не обязательно. Значение файла параметров переопределяет значение по умолчанию файла Bicep.

Файл параметров Bicep
ФАЙЛ параметров JSON

using 'main.bicep'

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

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
      "value": "" // This value must be provided.
    },
    "storageAccountType": {
      "value": "" // This value is optional. Bicep will use default value if not provided.
    }
  }
}

Примечание.

Для встроенных комментариев можно использовать символы // или /* ... */. В Visual Studio Code сохраните файлы параметров с типом файла JSONC , в противном случае вы получите сообщение об ошибке с сообщением "Комментарии не разрешены в ФОРМАТЕ JSON".

Проверьте допустимые значения в Bicep и все ограничения, такие как максимальная длина. Эти значения задают диапазон значений, которые можно указать для параметра. В этом примере длина storagePrefix не должна превышать 11 символов, а storageAccountType должен указывать допустимое значение.

Файл параметров Bicep
ФАЙЛ параметров JSON

using 'main.bicep'

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

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
      "value": "storage"
    },
    "storageAccountType": {
      "value": "Standard_ZRS"
    }
  }
}

Примечание.

Файл параметров может содержать только значения для параметров, определенных в файле Bicep. Если файл параметров содержит дополнительные параметры, которые не соответствуют параметрам Bicep-файла, вы получите сообщение об ошибке.

Создание файла параметров

Чтобы создать файл параметров, у вас есть два варианта: через Visual Studio Code или с помощью интерфейса командной строки Bicep. Оба метода позволяют наследовать файл параметров из Bicep-файла. В Visual Studio Code см . файл параметров создания. В интерфейсе командной строки Bicep см . раздел "Создание файла параметров".

Создание файла параметров Bicep

Из интерфейса командной строки Bicep можно создать файл параметров Bicep в файл параметров JSON. Дополнительные сведения см. в файле параметров сборки.

Развертывание Bicep-файла с помощью файла параметров

Azure CLI

Из Azure CLI можно передать файл параметров с развертыванием Bicep-файла.

Файл параметров Bicep
ФАЙЛ параметров JSON

С помощью Azure CLI версии 2.53.0 или более поздней версии и Bicep CLI версии 0.22.X или более поздней можно развернуть файл Bicep, используя файл параметров Bicep. using При использовании инструкции в файле параметров Bicep не требуется предоставлять --template-file параметр при указании файла параметров Bicep для коммутатора--parameters.

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

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file storage.bicep \
  --parameters storage.parameters.json

Встроенные параметры и файл параметров расположения можно использовать в той же операции развертывания. Например:

Файл параметров Bicep
ФАЙЛ параметров JSON

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

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file storage.bicep \
  --parameters storage.parameters.json \
  --parameters storageAccountType=Standard_LRS

Дополнительные сведения см. в статье Развертывание ресурсов с помощью Bicep и Azure CLI.

Azure PowerShell

В Azure PowerShell передайте локальный файл параметров с помощью TemplateParameterFile параметра.

Файл параметров Bicep
ФАЙЛ параметров JSON

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.parameters.json

Файл параметров Bicep
ФАЙЛ параметров JSON

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

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

Дополнительные сведения см. в статье Развертывание ресурсов с помощью Bicep и Azure PowerShell. Для развертывания Bicep-файлов требуется Azure PowerShell версии 5.6.0 или более поздней.

Приоритет параметров

Встроенные параметры и локальный файл параметров можно использовать в той же операции развертывания. Например, можно указать некоторые значения в файле локальных параметров и добавить другие значения во время развертывания. Если вы предоставляете значения для параметра как в файле локальных параметров, так и во встроенном файле, то встроенное значение имеет приоритет.

Можно использовать внешний файл параметров JSON, предоставив URI файлу. В настоящее время внешний файл параметров Bicep не поддерживается. Если вы используете файл внешних параметров, вы не можете передавать другие значения либо встроенные, либо из локального файла. Все встроенные параметры игнорируются. Все значения параметров следует указать во внешнем файле.

Конфликты параметров

Если файл Bicep содержит параметр, имя которого совпадает с именем одного из параметров в команде PowerShell, параметр из файла Bicep отображается с постфиксом FromTemplate. Например, параметр с именем ResourceGroupName в файле Bicep конфликтует с параметром ResourceGroupName командлета New-AzResourceGroupDeployment. Вам будет предложено указать значение для ResourceGroupNameFromTemplate. Этой путаницы можно избежать, используя имена параметров, которые не используются для команд развертывания.

Следующие шаги

Дополнительные сведения об определении параметров в файле Bicep см. статье Параметры в Bicep.
Сведения о том, как получить конфиденциальные значения, см. в статье Использование Azure Key Vault для передачи защищенного значения параметра во время развертывания.

Поделиться через

Создание файлов параметров для развертывания Bicep

Файл параметров

Форматы типов параметров

Имя файла

Определение значений параметров

Создание файла параметров

Создание файла параметров Bicep

Развертывание Bicep-файла с помощью файла параметров

Azure CLI

Azure PowerShell

Приоритет параметров

Конфликты параметров

Следующие шаги

Обратная связь

Дополнительные ресурсы