Рефакторизовать файл Bicep

  • 5 мин

После этапов преобразования и переноса вашего шаблона в Bicep необходимо улучшить файл. Этот процесс называется рефакторинг. Третий этап рекомендуемого рабочего процесса для переноса шаблона JSON ARM и ресурсов Azure в Bicep — это этап рефакторинга:

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

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

Этап рефакторинга состоит из восьми шагов, которые можно выполнить в любом порядке:

  • Просмотрите версии API ресурсов.
  • Просмотрите рекомендации линтера в новом файле Bicep.
  • Изменение параметров, переменных и символьных имен.
  • Упрощение выражений.
  • Просмотрите дочерние и расширенные ресурсы.
  • Модульная структура.
  • Добавьте примечания.
  • Следуйте рекомендациям Bicep.

В следующем примере показаны выходные данные из команды Bicep decompile шаблона JSON, создающего план службы приложений:

@description('Location for resources.')
param location string = resourceGroup().location

@allowed([
  'prod'
  'dev'
  'test'
])
@description('The list of allowed environment names.')
param environment string = 'prod'

@allowed([
  'P1v3'
  'P2v3'
  'P3v3'
])
@description('The list of allowed App Service Plan SKUs.')
param appServicePlanSku string = 'P1v3'

@minValue(1)
@maxValue(10)
@description('The number of allowed App Service Plan instances.')
param appServicePlanInstanceCount int = 1

var appServicePlanName_var = 'plan-${environment}-001'

resource appServicePlanName 'Microsoft.Web/serverfarms@2024-04-01' = {
  name: appServicePlanName_var
  location: location
  sku: {
    name: appServicePlanSku
    capacity: appServicePlanInstanceCount
  }
  kind: 'app'
  properties: {}
}

output appServicePlanId string = appServicePlanName.id

При развертывании этого шаблона Bicep as-isоно завершится успешно, но вы можете улучшить шаблон, чтобы привести его в соответствие с вашими стандартами шаблонов.

Проверка версий API ресурсов

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

Справочник по шаблону Azure ARM может помочь вам проверить соответствующие версии API и свойства ресурсов для вашего шаблона.

Просмотрите рекомендации линтера в вашем новом файле Bicep

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

Изменение параметров, переменных и символьных имен

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

Имена параметров, переменных и символьных имен, созданных декомпилером, могут не соответствовать стандартному соглашению об именовании. Просмотрите созданные имена и внесите необходимые изменения.

В следующем примере переменная с именем appServicePlanName_var_var добавлена в конец исходного имени переменной:

@minValue(1)
@maxValue(10)
@description('The number of allowed App Service Plan instances.')
param appServicePlanInstanceCount int = 1

var appServicePlanName_var = 'plan-${environment}-001'

resource appServicePlanName 'Microsoft.Web/serverfarms@2024-04-01' = {

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

Кончик

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

Visual Studio Code предлагает удобный способ переименовать символы: выберите идентификатор, который вы хотите переименовать, выберите F2, введите новое имя, а затем выберите ВВОД:

снимок экрана из Visual Studio Code, в котором показано, как переименовать символ.

Эти действия переименуют идентификатор и автоматически обновляют все ссылки на него.

Упрощение выражений

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

Просмотр дочерних и дополнительных ресурсов

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

Рассмотрите возможность проверки этих ресурсов после декомпиляции, чтобы убедиться, что структура соответствует вашим стандартам. Например, убедитесь, что вы не используете объединение строк для создания имен дочерних ресурсов. Вместо этого используйте свойство parent или вложенный ресурс. Аналогичным образом можно ссылаться на подсети как свойства виртуальной сети, так и как отдельные ресурсы.

Модульная структура

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

Заметка

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

Добавление комментариев и описаний

Хороший код Bicep — это самодокументирование. В Bicep можно добавить комментарии и описания в код для документирования инфраструктуры. Примечания и описания могут помочь коллегам понять код и повысить достоверность при внесении изменений. Примечания и описания отображаются при работе с Bicep-файлом в Visual Studio Code, например при необходимости указывать значение параметра для модуля. Но при развертывании Bicep-файла в Azure комментарии игнорируются.

С помощью последовательности символов // можно добавить однострочные примечания. Для многостроковых комментариев начните с /* и закончите */. Вы можете добавить комментарии, применимые к определенным строкам в коде или к разделам кода.

В начале файла можно добавить многострочный комментарий:

/*
  This Bicep file was developed by the web team.
  It deploys the resources we need for our toy company's website.
*/

Чтобы описать код, можно добавить однострочные примечания в виде заголовков для разделов кода или отдельных строк:

// Resource - App Service plan
@description('The App Service plan resource name.')
resource appServicePlan 'Microsoft.Web/serverfarms@2022-03-01' = {
  name: appServicePlanName
  location: location
  sku: {
    name: appServicePlanSku // Specifies the SKU of the App Service plan.
    capacity: appServicePlanInstanceCount
  }
  kind: 'app' // Specifies a Windows App Service plan.
}

// Outputs
@description('The resource ID of the App Service plan.')
output appServicePlanId string = appServicePlan.id // Resource ID of the App Service plan.

Bicep предоставляет декоратор @description, который можно использовать для документирования цели ваших параметров, переменных, ресурсов, модулей и выходов. Вы можете добавить описание в строку над элементом, который вы описываете:

@description('The name of the App Service plan.')
var appServicePlanName = 'plan-${environment}-001'

Следуйте рекомендациям Bicep

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

Преобразованный шаблон

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

/*
  This Bicep file was developed by the web team.
  It deploys the resources we need for our toy company's website.
*/

// Parameters
@description('Location for all resources.')
param location string = resourceGroup().location

@allowed([
  'prod' // Production environment
  'dev' // Development environment
  'test' // Test environment
])
@description('The list of allowed environment names.')
param environment string = 'prod'

@allowed([
  'P1v3'
  'P2v3'
  'P3v3'
])
@description('The list of allowed App Service plan SKUs.')
param appServicePlanSku string = 'P1v3'

@minValue(1)
@maxValue(10)
@description('The number of allowed App Service plan instances.')
param appServicePlanInstanceCount int = 1

// Variables
@description('The name of the App Service plan.')
var appServicePlanName = 'plan-${environment}-001'

// Resource - App Service plan
@description('The App Service plan resource name.')
resource appServicePlan 'Microsoft.Web/serverfarms@2022-03-01' = {
  name: appServicePlanName
  location: location
  sku: {
    name: appServicePlanSku // Specifies the SKU of the App Service plan.
    capacity: appServicePlanInstanceCount
  }
  kind: 'app' // Specifies a Windows App Service plan.
}

// Outputs
@description('The resource ID of the App Service plan.')
output appServicePlanId string = appServicePlan.id // Resource ID of the App Service plan.