Модули Bicep

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

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

Модули Bicep преобразуются в один единый шаблон ARM с вложенными шаблонами. Дополнительные сведения о том, как 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'
  }
}

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

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

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

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

Свойство name необязательное. Оно становится именем ресурса для вложенного развертывания в создаваемом шаблоне. Если имя не указано, идентификатор GUID будет создан в качестве имени для вложенного ресурса развертывания.

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

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

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

Отсутствие имени модуля также допустимо. Идентификатор GUID будет создан в качестве имени модуля.

module stgModule 'storageAccount.bicep' = {
  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 в определение модуля. Дополнительные сведения о зависимостях см. в разделе «Зависимости ресурсов в Bicep».

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

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

Существуют общедоступные и частные реестры модулей.

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

Проверенные модули Azure - это предварительно созданные, проверенные ранее и подготовленные модули, которые можно использовать для развертывания ресурсов в Azure. Сотрудники Майкрософт создали и владели этими модулями. Они были разработаны для упрощения и ускорения процесса развертывания для общих ресурсов и конфигураций Azure. Модули также соответствуют рекомендациям, таким как Azure Well-Architected Framework.

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

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

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

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

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

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

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

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.
• путь к файлу: это называется repository в реестре контейнеров Azure. Путь к файлу может содержать сегменты, разделенные символом /.
• тег: используется для указания версии модуля.

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

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

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

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

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

В реестре общедоступных модулей есть предопределенный псевдоним:

module storage 'br/public:avm/res/storage/storage-account:0.18.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 и располагаются над объявлениями модуля. В следующей таблице показаны доступные декораторы для модулей:

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

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.18.0' = {
  name: 'myStorage'
  params: {
    name: 'store${resourceGroup().name}'
  }
}

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

Parameters

Параметры, указанные в определении модуля, соответствуют параметрам в файле 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@2025-06-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@2025-04-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@2025-04-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@2025-04-01' existing = {
  name: 'demogroup1'
}

resource secondRG 'Microsoft.Resources/resourceGroups@2025-04-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)
}

Output

Можно получить значения от модуля и использовать их в основном файле 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@2025-06-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@2025-04-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 версии 0.35.1 и более поздних версий декоратор @secure() может применяться к выходным данным модуля, чтобы пометить их как конфиденциальные, гарантируя, что их значения не отображаются в журналах или истории развертывания. Это полезно, если модуль должен возвращать конфиденциальные данные, такие как созданный ключ или строка подключения, в родительский файл Bicep без риска раскрытия. Дополнительные сведения см. в разделе "Безопасные выходные данные".

Удостоверение модуля

Начиная с версии 0.36.1 Bicep, вы можете назначить пользовательское управляемое удостоверение модулю. Это делает удостоверение доступным в модуле, например для доступа к Key Vault. Однако эта возможность предназначена для дальнейшего использования и пока не поддерживается внутренними службами.

param identityId string

module mod './module.bicep' = {
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '${identityId}': {}
    }
  }
  name: 'mod'
  params: {
    keyVaultUri: 'keyVaultUri'
    identityId: identityId
  }
}

Связанный контент

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