Модули Bicep

Bicep позволяет упорядочивать развертывания по модулям. Модуль — это Bicep-файл (или шаблон JSON Azure Resource Manager), развернутый из другого файла Bicep. Модули позволяют повысить удобочитаемость файлов Bicep за счет инкапсуляции сложных сведений о развертывании. Кроме того, модули можно многократно использовать для разных развертываний.

Чтобы предоставить общий доступ к модулям другим пользователям в организации, создайте спецификацию шаблона или частный реестр. Спецификации шаблонов и модули в реестре доступны только пользователям с правильными разрешениями.

Совет

Выбор между реестром модулей и спецификациями шаблонов определяется в основном личными предпочтениями. Но при выборе между этими двумя вариантами следует учитывать ряд моментов.

• Реестр модулей поддерживается только для Bicep. Если вы пока не используете Bicep, выбирайте спецификации шаблонов.
• Содержимое в реестре модулей Bicep можно развернуть только из другого файла Bicep. Спецификации шаблонов можно развертывать непосредственно из API, Azure PowerShell, Azure CLI или на портале Azure. Вы даже можете использовать UiFormDefinition для настройки интерфейса развертывания на портале.
• Bicep предоставляет ограниченную поддержку для внедрения других артефактов проекта, включая файлы, отличные от Bicep, и файлы, отличные от файлов шаблонов ARM (например, скрипты PowerShell, скрипты CLI и другие двоичные файлы), с помощью функций loadTextContent и loadFileAsBase64. Спецификации шаблонов не умеют упаковывать такие артефакты.

Модули Bicep преобразуются в один шаблон Resource Manager со вложенными шаблонами. Дополнительные сведения о том, как Bicep разрешает файлы конфигурации и как Bicep объединяет определяемый пользователем файл конфигурации с файлом конфигурации по умолчанию, см. в разделе "Процесс разрешения файлов конфигурации" и процесс слияния файлов конфигурации.

Обучающие материалы

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

Определение модулей

Базовая структура синтаксиса для определения модуля:

@<decorator>(<argument>)
module <symbolic-name> '<path-to-file>' = {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
}

Итак, простой реальный пример выглядит следующим образом:

module stgModule '../storageAccount.bicep' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

В качестве модуля также можно использовать JSON-шаблон ARM:

module stgModule '../storageAccount.json' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

Используйте символьное имя для ссылки на модуль в другой части файла Bicep. Например, символьное имя можно использовать для получения результатов из модуля. Символьное имя может содержать a-z, A-Z, 0-9 и подчеркивание (_). Имя не должно начинаться с цифры. Имя модуля не может совпадать с именем параметра, переменной или ресурса.

В качестве пути можно использовать локальный файл или файл в реестре. Локальный файл может быть Bicep-файлом или JSON-шаблоном ARM. Дополнительные сведения см. в статье Путь к модулю.

Свойство Имя является обязательным. Оно становится именем ресурса вложенного развертывания в шаблоне.

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

В следующем примере имя развертывания объединяется с именем модуля. Если вы укажете уникальное имя для развертывания, имя модуля также будет уникальным.

module stgModule 'storageAccount.bicep' = {
  name: '${deployment().name}-storageDeploy'
  scope: resourceGroup('demoRG')
}

Если вам нужно указать область, отличную от области основного файла, добавьте свойство "Область действия". Дополнительные сведения см. в разделе Задание области модуля.

// deploy to different scope
module <symbolic-name> '<path-to-file>' = {
  name: '<linked-deployment-name>'
  scope: <scope-object>
  params: {
    <parameter-names-and-values>
  }
}

Чтобы условно развернуть модуль, добавьте выражение if. Использование аналогично условному развертыванию ресурса.

// conditional deployment
module <symbolic-name> '<path-to-file>' = if (<condition-to-deploy>) {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
}

Чтобы развернуть более одного экземпляра модуля, добавьте выражение for. Можно указать, следует ли развертывать экземпляры последовательно или параллельно, с помощью декоратора batchSize. Дополнительные сведения о циклах см. в статье Интерактивные циклы в Bicep.

// iterative deployment
@batchSize(int) // optional decorator for serial deployment
module <symbolic-name> '<path-to-file>' = [for <item> in <collection>: {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
}]

Как и ресурсы, модули развертываются параллельно, если только они не зависят от других модулей или ресурсов. Как правило, задавать зависимости не нужно, так как они определяются неявным образом. Если нужно задать явную зависимость, можно добавить dependsOn в определение модуля. Дополнительные сведения о зависимостях см. в статье Зависимости ресурсов.

module <symbolic-name> '<path-to-file>' = {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
  dependsOn: [
    <symbolic-names-to-deploy-before-this-item>
  ]
}

Путь к модулю

Файл для модуля может быть локальным или внешним. Внешний файл может содержаться в спецификации шаблона или в реестре модуля Bicep.

Локальный файл

Если модуль представляет собой локальный файл, укажите относительный путь к этому файлу. Все пути в Bicep должны быть указаны с помощью разделителя каталогов косой черты (/), чтобы обеспечить согласованную компиляцию на разных платформах. Символ обратной косой черты Windows (\) не поддерживается. Пути могут содержать пробелы.

Например, чтобы развернуть файл в каталоге на уровень выше основного файла, используйте:

module stgModule '../storageAccount.bicep' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

Файл в реестре

Общедоступный реестр модулей

Примечание.

Модули, отличные от AVM (проверенные модули Azure), удаляются из общедоступного реестра модулей.

Проверенные модули Azure предварительно создаются, предварительно проверенные и предварительно подготовленные модули для развертывания ресурсов в Azure. Созданные и принадлежащие сотрудникам Майкрософт модули предназначены для упрощения и ускорения процесса развертывания общих ресурсов и конфигураций Azure, а также соответствия рекомендациям; например, хорошо спроектированная платформа.

Перейдите к индексу Bicep для проверенных модулей Azure, чтобы просмотреть список доступных модулей, выберите выделенные числа на следующем снимке экрана, чтобы перейти непосредственно в это отфильтрованное представление.

В списке модулей отображается последняя версия. Выберите номер версии, чтобы просмотреть список доступных версий:

Чтобы связаться с общедоступным модулем, укажите путь модуля со следующим синтаксисом:

module <symbolic-name> 'br/public:<file-path>:<tag>' = {}

• br/public — это псевдоним для общедоступных модулей. Этот псевдоним можно настроить в файле конфигурации Bicep.
• путь к файлу может содержать сегменты, разделенные символом /.
• Тег используется для указания версии модуля.

Рассмотрим пример.

module storage 'br/public:avm/res/storage/storage-account:0.9.0' = {
  name: 'myStorage'
  params: {
    name: 'store${resourceGroup().name}'
  }
}

Примечание.

br/public — это псевдоним для общедоступных модулей. Его также можно написать следующим образом:

module <symbolic-name> 'br:mcr.microsoft.com/bicep/<file-path>:<tag>' = {}

Частный реестр модулей

Если вы опубликовали модуль в реестре, можно создать ссылку на этот модуль. Укажите имя реестра контейнеров Azure и путь к модулю. Укажите путь к модулю с помощью следующей структуры синтаксиса.

module <symbolic-name> 'br:<registry-name>.azurecr.io/<file-path>:<tag>' = {

• br — имя схемы для реестра Bicep.
• Путь к файлу в реестре контейнеров Azure называется repository. Путь к файлу может содержать сегменты, разделенных символом /.
• Тег используется для указания версии модуля.

Например:

module stgModule 'br:exampleregistry.azurecr.io/bicep/modules/storage:v1' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

При ссылке на модуль в реестре расширение Bicep в Visual Studio Code автоматически вызывает восстановление Bicep для копирования внешнего модуля в локальный кэш. Восстановление внешнего модуля занимает несколько секунд. Если технология IntelliSense для модуля срабатывает не сразу, дождитесь завершения восстановления.

Полный путь к модулю в реестре может быть длинным. Вместо того чтобы указывать полный путь каждый раз при использовании модуля, можно настроить псевдонимы в файле bicepconfig.json. Псевдонимы упрощают обращение к модулю. Например, с помощью псевдонима можно сократить путь до следующего вида:

module stgModule 'br/ContosoModules:storage:v1' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

Псевдоним для общедоступного реестра модулей задан заранее:

module storage 'br/public:avm/res/storage/storage-account:0.9.0' = {
  name: 'myStorage'
  params: {
    name: 'store${resourceGroup().name}'
  }
}

Вы можете переопределить общедоступный псевдоним в файле bicepconfig.json.

Файл в спецификации шаблона

После создания спецификации шаблона можно создать ссылку на спецификацию шаблона в модуле. Укажите спецификацию шаблона в следующем формате:

module <symbolic-name> 'ts:<sub-id>/<rg-name>/<template-spec-name>:<version>' = {

Однако можно упростить файл Bicep, создав псевдоним для группы ресурсов, которая содержит спецификации шаблонов. При использовании псевдонима синтаксис будет выглядеть так:

module <symbolic-name> 'ts/<alias>:<template-spec-name>:<version>' = {

Следующий модуль развертывает спецификацию шаблона для создания учетной записи хранения. Подписка и группа ресурсов для спецификации шаблона определяются в псевдониме ContosoSpecs.

module stgModule 'ts/ContosoSpecs:storageSpec:2.0' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

Использование декораторов

Декораторы записываются в формате @expression и помещаются над объявлениями модуля. В следующей таблице показаны доступные декораторы для модулей.

Декоратор	Аргумент	Description
batchSize	ничего	Настройте экземпляры для последовательного развертывания.
описание	строка	Укажите описания модуля.

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

BatchSize

Можно применить @batchSize() только к определению ресурса или модуля, использующего for выражение.

По умолчанию модули развертываются параллельно. При добавлении декоратора @batchSize(int) экземпляры развертываются последовательно.

@batchSize(3)
module storage 'br/public:avm/res/storage/storage-account:0.11.1' = [for storageName in storageAccounts: {
  name: 'myStorage'
  params: {
    name: 'store${resourceGroup().name}'
  }
}]

Дополнительные сведения см. в статье Развертывание в пакетах.

Description

Чтобы добавить объяснение, добавьте описание в объявления модуля. Например:

@description('Create storage accounts referencing an AVM.')
module storage 'br/public:avm/res/storage/storage-account:0.9.0' = {
  name: 'myStorage'
  params: {
    name: 'store${resourceGroup().name}'
  }
}

Текст в формате Markdown можно использовать для текста описания.

Параметры

Параметры, указанные в определении модуля, соответствуют параметрам в файле Bicep.

В следующем примере Bicep имеется три параметра: storagePrefix, storageSKU и location. Параметр storageSKU имеет значение по умолчанию, поэтому в ходе развертывания вам не нужно будет указывать значение этого параметра.

@minLength(3)
@maxLength(11)
param storagePrefix string

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_RAGRS'
  'Standard_ZRS'
  'Premium_LRS'
  'Premium_ZRS'
  'Standard_GZRS'
  'Standard_RAGZRS'
])
param storageSKU string = 'Standard_LRS'

param location string

var uniqueStorageName = '${storagePrefix}${uniqueString(resourceGroup().id)}'

resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

output storageEndpoint object = stg.properties.primaryEndpoints

Чтобы использовать предыдущий пример в качестве модуля, укажите значения для этих параметров.

targetScope = 'subscription'

@minLength(3)
@maxLength(11)
param namePrefix string

resource demoRG 'Microsoft.Resources/resourceGroups@2024-03-01' existing = {
  name: 'demogroup1'
}

module stgModule '../create-storage-account/main.bicep' = {
  name: 'storageDeploy'
  scope: demoRG
  params: {
    storagePrefix: namePrefix
    location: demoRG.location
  }
}

output storageEndpoint object = stgModule.outputs.storageEndpoint

Задание области действия модуля

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

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

// set the target scope for this file
targetScope = 'subscription'

@minLength(3)
@maxLength(11)
param namePrefix string

param location string = deployment().location

var resourceGroupName = '${namePrefix}rg'

resource newRG 'Microsoft.Resources/resourceGroups@2024-03-01' = {
  name: resourceGroupName
  location: location
}

module stgModule '../create-storage-account/main.bicep' = {
  name: 'storageDeploy'
  scope: newRG
  params: {
    storagePrefix: namePrefix
    location: location
  }
}

output storageEndpoint object = stgModule.outputs.storageEndpoint

В следующем примере учетные записи хранения развертываются в двух разных группах ресурсов. Обе эти группы ресурсов уже должны существовать.

targetScope = 'subscription'

resource firstRG 'Microsoft.Resources/resourceGroups@2024-03-01' existing = {
  name: 'demogroup1'
}

resource secondRG 'Microsoft.Resources/resourceGroups@2024-03-01' existing = {
  name: 'demogroup2'
}

module storage1 '../create-storage-account/main.bicep' = {
  name: 'westusdeploy'
  scope: firstRG
  params: {
    storagePrefix: 'stg1'
    location: 'westus'
  }
}

module storage2 '../create-storage-account/main.bicep' = {
  name: 'eastusdeploy'
  scope: secondRG
  params: {
    storagePrefix: 'stg2'
    location: 'eastus'
  }
}

Задайте для свойства scope допустимый объект области. Если файл Bicep развертывает группу ресурсов, подписку или группу управления, можно задать в качестве области модуля символьное имя этого ресурса. Для получения допустимой области можно также использовать функции области.

Такими функциями являются:

• resourceGroup
• subscription
• managementGroup
• tenant

В следующем примере для задания области используется функция managementGroup.

param managementGroupName string

module mgDeploy 'main.bicep' = {
  name: 'deployToMG'
  scope: managementGroup(managementGroupName)
}

Выходные данные

Можно получить значения от модуля и использовать их в основном файле Bicep. Чтобы получить выходное значение от модуля, используйте свойство outputs в объекте модуля.

В первом примере создается учетная запись хранения и возвращаются основные конечные точки.

@minLength(3)
@maxLength(11)
param storagePrefix string

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_RAGRS'
  'Standard_ZRS'
  'Premium_LRS'
  'Premium_ZRS'
  'Standard_GZRS'
  'Standard_RAGZRS'
])
param storageSKU string = 'Standard_LRS'

param location string

var uniqueStorageName = '${storagePrefix}${uniqueString(resourceGroup().id)}'

resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

output storageEndpoint object = stg.properties.primaryEndpoints

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

targetScope = 'subscription'

@minLength(3)
@maxLength(11)
param namePrefix string

resource demoRG 'Microsoft.Resources/resourceGroups@2024-03-01' existing = {
  name: 'demogroup1'
}

module stgModule '../create-storage-account/main.bicep' = {
  name: 'storageDeploy'
  scope: demoRG
  params: {
    storagePrefix: namePrefix
    location: demoRG.location
  }
}

output storageEndpoint object = stgModule.outputs.storageEndpoint

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

• Руководство см. в статье Развертывание ресурсов Azure с помощью шаблонов Bicep.
• Чтобы передать в модуль конфиденциальное значение, используйте функцию getSecret.