Улучшение параметров и имен
Параметры — это самый распространенный способ взаимодействия ваших коллег с шаблоном. При развертывании шаблона им нужно указывать значения для параметров. Созданное имя ресурса сразу сообщает о его назначении всем, кто попадает в вашу среду Azure.
В этом уроке вы узнаете о некоторых ключевых соображениях при планировании параметров для файлов Bicep и именах, которые вы предоставляете вашим ресурсам.
Насколько параметры понятны?
Параметры помогают сделать файлы Bicep гибкими и пригодными для многократного использования. Важно, чтобы назначение каждого параметра было понятно любому, кто его использует. Когда коллеги работают с вашим шаблоном, они используют параметры для настройки поведения своего развертывания.
Допустим, например, что вам нужно развернуть учетную запись хранения, используя файл Bicep. Одним из обязательных свойств учетной записи хранения является единица складского учета (Stock Keeping Unit, SKU), которая определяет уровень избыточности данных. SKU имеет несколько свойств, наиболее важным из которых является name. При создании параметра для указания значения SKU учетной записи хранения используйте четко сформулированное имя, например storageAccountSkuName. Использование этого значения вместо универсального имени, такого как sku или skuName, поможет другим понять назначение параметра и результат установки его значения.
Значения по умолчанию — важный способ сделать шаблон удобным для других пользователей. Важно использовать значения по умолчанию там, где это уместно. Они помогают пользователям шаблона сразу с двух сторон.
- Значения по умолчанию упрощают процесс развертывания вашего шаблона. Если ваши параметры имеют хорошие значения по умолчанию, подходящие большинству пользователей шаблона, пользователи смогут опускать значения параметров вместо того, чтобы указывать их при каждом развертывании шаблона.
- Значения по умолчанию служат примером того, как должно выглядеть значение параметра. Если пользователям шаблона нужно выбрать другое значение, значение по умолчанию может подсказать, как оно должно выглядеть.
Bicep также может помочь проверить данные, указанные пользователями, используя декораторы параметров. Декораторы позволяют указать описания параметров или допустимые типы значений. Bicep позволяет использовать несколько типов декораторов параметров.
Описания содержат понятную пользователю информацию о назначении параметра и результат установки его значения.
Ограничения значений накладывают ограничения на то, что пользователи могут вводить в качестве значения параметра. Список конкретных разрешенных значений можно указать с помощью декоратора
@allowed(). Вы можете использовать@minValue()и@maxValue()декораторы для применения минимальных и максимальных значений для числовых параметров, а также для применения@minLength()@maxLength()длины параметров строки и массива.Совет
Будьте внимательны при использовании декоратора параметров
@allowed()для указания номеров SKU. Службы Azure часто добавляют новые SKU, и вам не нужно, чтобы шаблон без нужды запрещал их использовать. Для принудительного использования определенных SKU можно использовать политику Azure, а декоратор@allowed()использовать с SKU только при наличии функциональных причин, по которым пользователи шаблона не должны выбирать определенный SKU, например если в этом SKU могут быть недоступны компоненты, необходимые для работы с шаблоном. Объясните это с помощью декоратора@description()или оставьте комментарий, который сделает причины понятными для всех.Метаданные не используются постоянно, но могут применяться для указания дополнительных пользовательских метаданных параметра.
Насколько гибким должен быть файл Bicep?
Одна из целей определения инфраструктуры как кода состоит в том, чтобы сделать шаблоны гибкими и пригодными для многократного использования. Не стоит создавать одноразовые шаблоны с жестко прописанной конфигурацией. С другой стороны, не имеет смысла предоставлять в качестве параметров все свойства ресурсов. Создавайте шаблоны, которые подходят для конкретной бизнес-задачи или решения, а не универсальные шаблоны, которые должны работать в любой ситуации. Вы также не хотите иметь так много параметров, что требуется много времени для ввода значений, прежде чем можно развернуть шаблон. Это особенно важно при настройке количества SKU и экземпляров ресурсов.
При планировании шаблона старайтесь найти баланс между гибкостью и простотой. Есть два стандартных способа предоставления параметров в шаблонах:
- Предоставление параметров конфигурации в свободной форме
- Использование предопределенных наборов конфигурации
Рассмотрим оба подхода, взяв для примера файла Bicep, который развертывает учетную запись хранения и план службы приложений Azure.
Предоставление параметров конфигурации в свободной форме
Как план службы приложений, так и учетная запись хранения требуют указания SKU. Вы можете создать набор параметров для управления количествами SKU и экземпляров для ресурсов:
Вот как это выглядит в Bicep.
param appServicePlanSkuName string
param appServicePlanSkuCapacity int
param storageAccountSkuName string
resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
name: appServicePlanName
location: location
sku: {
name: appServicePlanSkuName
capacity: appServicePlanSkuCapacity
}
}
resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = {
name: storageAccountSkuName
location: location
sku: {
name: storageAccountSkuName
}
}
Этот формат обеспечивает наибольшую гибкость, так как любой, кто использует шаблон, может указать любое сочетание значений параметров. Однако при добавлении дополнительных ресурсов нужны дополнительные параметры. В результате ваш шаблон усложняется. Кроме того, возможно, вам придется либо ограничить определенные сочетания параметров, либо убедиться в том, что при развертывании определенного ресурса с помощью одного SKU другой ресурс необходимо развертывать, используя другой номер SKU. Когда отдельных параметров слишком много, применять эти правила сложно.
Совет
Подумайте о тех, кто будет работать с вашим шаблоном. От просмотра десятков параметров они могут потерять терпение и отказаться от использования вашего шаблона.
Вы можете уменьшить количество параметров, сгруппировав связанные параметры как объект параметров следующим образом.
param appServicePlanSku object = {
name: 'S1'
capacity: 2
}
Однако это может ограничить вашу способность проверки значений параметров, а пользователи шаблона не всегда легко могут понять, как определить объект.
Использование предопределенных наборов конфигурации
Другой вариант — это предоставить набор конфигурации, т. е. один параметр, значение которого представляет собой ограниченный список допустимых значений, например список типов среды. При развертывании вашего шаблона пользователь должен будет выбрать значение только для этого параметра. Когда выбирается значение такого параметра, развертывание автоматически наследует набор конфигурации:
Определение параметра выглядит следующим образом.
@allowed([
'Production'
'Test'
])
param environmentType string = 'Test'
Наборы конфигураций обеспечивают более низкую гибкость, так как пользователи, которые развертывают шаблон, не могут указывать размеры отдельных ресурсов, но вы можете проверить каждый набор конфигураций и убедиться, что они соответствуют вашим требованиям. Благодаря наборам конфигурации пользователям не нужно понимать все множество различных параметров, доступных для каждого ресурса, а поддерживать шаблоны, тестировать их и устранять неполадки становится проще.
При работе с наборами конфигурации создается переменная map, определяющая конкретные свойства, которые нужно задавать для различных ресурсов в зависимости от значения параметра.
var environmentConfigurationMap = {
Production: {
appServicePlan: {
sku: {
name: 'P2V3'
capacity: 3
}
}
storageAccount: {
sku: {
name: 'ZRS'
}
}
}
Test: {
appServicePlan: {
sku: {
name: 'S2'
capacity: 1
}
}
storageAccount: {
sku: {
name: 'LRS'
}
}
}
}
Затем ваши определения ресурсов используют схему конфигурации для определения свойств ресурсов.
resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
name: appServicePlanName
location: location
sku: environmentConfigurationMap[environmentType].appServicePlan.sku
}
Наборы конфигурации позволяют упростить работу со сложным шаблонами. Кроме того, они могут помочь вам обеспечить применение ваших собственных правил и использование проверенных значений конфигурации.
Примечание.
Этот подход похож на выбор футболки. Когда вы покупаете футболку, вам не предлагают много вариантов длины, ширины, рукавов и т. д. Вы просто выбираете маленький, средний или большой размер, параметры которого уже заранее выбрал дизайнер футболок.
Как называются ваши ресурсы?
В Bicep важно давать ресурсам понятные имена. Ресурсы в Bicep имеют по два имени.
Символьные имена используются только в файле Bicep и не отображаются в ресурсах Azure. Символьные имена помогают пользователям, которые читают или изменяют ваш шаблон, понимать назначение параметров, переменных или определений ресурсов, а также принимать осознанные решения о том, стоит ли им изменять шаблон.
Имена ресурсов — это имена, создаваемые для ресурсов в Azure. Многие ресурсы имеют ограничения для имен, а многие требуют, чтобы их имена были уникальными.
Символьные имена
Обращайте внимание на символьные имена, которые вы применяете к своим ресурсам. Представьте, что вашим коллегам нужно будет изменить шаблон. Будет ли им понятно, для чего предназначен каждый ресурс?
Допустим, например, что вы хотите определить учетную запись хранения, которая будет содержать руководства по продукту для скачивания с веб-сайта. Вы можете дать ресурсу символическое имя (например, например), storageAccountно если он находится в Bicep-файле, который содержит много других ресурсов, и, возможно, даже другие учетные записи хранения, это имя недостаточно описательно. Вместо этого можно присвоить ему символическое имя, включающее некоторые сведения о его назначении, например productManualStorageAccount.
В Bicep для имен параметров, переменных и символьных имен ресурсов обычно используется верблюжий стиль. Это означает, что первое слово начинается со строчной буквы, а все последующие — с заглавной (как в приведенном выше примере, productManualStorageAccount). Вам необязательно использовать верблюжий стиль. Если вы решили использовать другой стиль, договоритесь со своей командой о едином стандарте и соблюдайте его постоянно.
Имена ресурсов
Имя есть у каждого ресурса Azure. Имена — это часть идентификатора ресурса. Во многих случаях они также представлены как имена узлов, которые используются для доступа к ресурсу. Например, при создании приложения Службы приложений с именем myapp имя узла, которое вы используете для доступа к приложению, будет иметь значение myapp.azurewebsites.net. Вы не можете переименовать ресурсы после их развертывания.
Выбирайте имена для ресурсов Azure внимательно. Многие организации определяют собственное соглашение об именовании ресурсов. Cloud Adoption Framework для Azure включает определенные рекомендации, которые могут вам пригодиться. Соглашение об именовании ресурсов нужно для того, чтобы всем в организации было понятно, для чего предназначен каждый ресурс.
Кроме того, определенные правила и ограничения по выбору имен есть у каждого ресурса Azure. Например, существуют ограничения на длину имен, символы, которые они могут содержать, и то, должно ли имя быть глобально уникальным или уникальным в пределах группы ресурсов.
Соблюдать все принятые в вашей организации соглашения об именовании и требования к выбору имен в Azure может быть непросто. Хорошо написанный шаблон Bicep должен скрывать эту сложность от пользователей и задавать имена для ресурсов автоматически. Ниже приведен один из примеров подхода, который следует выполнить.
Добавление параметра, который будет использоваться для создания суффикса уникальности. Это позволит обеспечить уникальные имена для ваших ресурсов. Для формирования значения по умолчанию можно использовать функцию
uniqueString(). Пользователи, которые развертывают ваш шаблон, могут заменить его определенным значением, если захотят выбрать понятное имя. Использование декоратора@maxLength()для ограничения длины этого суффикса, чтобы имена ресурсов не были длиннее максимальных значений.Совет
Лучше использовать не префиксы, а суффиксы уникальности. Такой подход упрощает сортировку и ускоряет сканирование имен ресурсов. Кроме того, некоторые ресурсы Azure ограничивают выбор первого символа в имени, а имена, создаваемые случайным образом, могут нарушать эти ограничения.
Используйте переменные для динамического формирования имен ресурсов. Код Bicep может гарантировать, что создаваемые имена будут соответствовать соглашению об именовании, принятому в вашей организации, а также требованиям Azure. Включите суффикс уникальности в имя ресурса.
Примечание.
Не каждый ресурс требует глобально уникального имени. Рассмотрим, включают ли вы суффикс уникальности в имена каждого ресурса или только те, которые нуждаются в нем.