Добавление параметров и выходных данных в модули

  • 7 мин

Каждый создаваемый модуль должен иметь четкое назначение. Рассматривайте модуль как заключение контракта. Он принимает набор параметров, создает набор ресурсов и может предоставлять некоторые выходные данные обратно в родительский шаблон. Пользователь, который использует модуль, не должен беспокоиться о его работе. Ему просто нужно, чтобы шаблон выполнял свою задачу так, как ожидается.

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

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

Параметры модулей

Подумайте о параметрах, принимаемых модулем, а также о том, должен ли каждый параметр быть обязательным или необязательным.

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

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

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

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

Какие бы параметры вы ни включали в модуль, убедитесь, что вы добавили значимое описание с помощью атрибута @description:

@description('The name of the storage account to deploy.')
param storageAccountName string

Условия использования

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

Предположим, вы создаете модуль, который развертывает учетную запись Azure Cosmos DB. При развертывании в рабочей среде необходимо настроить учетную запись для отправки журналов в рабочую область Log Analytics. Чтобы настроить отправку журналов в Log Analytics, необходимо определить ресурс diagnosticSettings.

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

param logAnalyticsWorkspaceId string = ''

resource cosmosDBAccount 'Microsoft.DocumentDB/databaseAccounts@2022-08-15' = {
  // ...
}

resource cosmosDBAccountDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' =  if (logAnalyticsWorkspaceId != '') {
  scope: cosmosDBAccount
  name: 'route-logs-to-log-analytics'
  properties: {
    workspaceId: logAnalyticsWorkspaceId
    logs: [
      {
        category: 'DataPlaneRequests'
        enabled: true
      }
    ]
  }
}

Включая этот модуль в шаблон Bicep, вы можете легко настроить его для отправки журналов учетных записей Azure Cosmos DB в Log Analytics путем задания идентификатора рабочей области. Или, если вам не нужны журналы для развернутой среды, опустите параметр. Он использует значение по умолчанию. Модуль инкапсулирует логику, которая необходима для соблюдения требований.

Совет

Не забудьте проверить, является ли шаблон допустимым для обоих сценариев, когда инструкция if вычисляется как true или false.

Выходные данные модуля:

Модули могут определять выходы. Рекомендуется создавать выходные данные для сведений, которые, возможно, потребуется использовать в родительском шаблоне. Например, если модуль определяет учетную запись хранения, рассмотрите возможность создания выходных данных для имени учетной записи хранения, чтобы родительский шаблон мог получить к нему доступ.

Предупреждение

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

  • Используйте выходные данные, чтобы указать имя ресурса. Затем родительский шаблон может создать ресурс existing с этим именем, который может динамически выполнять поиск безопасного значения.
  • Запишите значение в секрет Azure Key Vault. Настройте для родительского шаблона чтение секрета из хранилища, если это необходимо.

Родительский шаблон может использовать выходные данные модуля в переменных, использовать свойства для других определений ресурсов или предоставлять переменные и свойства в качестве выходных данных. Предоставляя и используя выходные данные в файлах Bicep, можно создавать многократно используемые наборы модулей Bicep, которые вы можете использовать вместе с коллегами и многократно использовать в нескольких развертываниях. Также рекомендуется добавить понятное описание к выходным данным с помощью атрибута @description.

@description('The fully qualified Azure resource ID of the blob container within the storage account.')
output blobContainerResourceId string = storageAccount::blobService::container.id

Совет

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

Объединение модулей в цепочку

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

@description('Username for the virtual machine.')
param adminUsername string

@description('Password for the virtual machine.')
@minLength(12)
@secure()
param adminPassword string

module virtualNetwork 'modules/vnet.bicep' = {
  name: 'virtual-network'
}

module virtualMachine 'modules/vm.bicep' = {
  name: 'virtual-machine'
  params: {
    adminUsername: adminUsername
    adminPassword: adminPassword
    subnetResourceId: virtualNetwork.outputs.subnetResourceId
  }
}

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

Так как Bicep определяет наличие зависимости, развертывание модулей выполняется последовательно.

  1. Bicep развертывает все компоненты в модуле virtualNetwork.
  2. Если это развертывание выполнено успешно, Bicep обращается к выходному значению subnetResourceId и передает его в модуль virtualMachine как параметр.
  3. Bicep развертывает все компоненты в модуле virtualMachine.

Примечание.

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