Планирование структуры файла Bicep

  • 7 мин

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

Какой порядок должен соблюдаться в коде Bicep?

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

Есть два основных подхода к порядку элементов в коде.

  • Группирование элементов по типам
  • Группирование элементов по ресурсам

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

Группирование элементов по типам

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

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

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

Совет

Если вы выбрали это соглашение, рекомендуем поместить targetScope в начало файла.

Такой порядок имеет смысл, если вы привыкли к другим языкам инфраструктуры как кода (например, к языку в шаблонах Azure Resource Manager). Кроме того, вы можете легко понять шаблон, так как понятно, где искать определенные типы элементов. Однако в более длинных шаблонах перемещаться между элементами может быть непросто.

И вам все равно нужно выбирать порядок элементов в этих категориях. Лучше всего связанные параметры группировать вместе. Например, стоит объединить все параметры учетной записи хранения, а внутри этих параметров — параметры SKU учетной записи хранения.

Таким же образом можно сгруппировать связанные ресурсы. Это помогает всем, кто использует шаблон, быстро перемещаться по нему и понимать важные части шаблона.

Иногда создается шаблон, который развертывает первичный ресурс с несколькими дополнительными вспомогательными ресурсами. Например, можно создать шаблон для развертывания веб-сайта, размещенного в службе приложений Azure. Основным ресурсом является приложение Службы приложений. Вторичные ресурсы в том же шаблоне могут включать план Службы приложений, учетную запись хранения, экземпляр Application Insights и другие. При наличии такого шаблона рекомендуется поместить основной ресурс или ресурсы в верхней части раздела ресурсов шаблона, чтобы любой пользователь, открывший шаблон, мог быстро определить назначение шаблона и найти важные ресурсы.

Группирование элементов по ресурсам

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

Схема, на которой показаны элементы, сгруппированные по ресурсам. Элементы учетной записи хранения сгруппированы, а за ними идут элементы базы данных Azure SQL

Группирование по ресурсам упрощает чтение шаблона, поскольку все элементы, необходимые для конкретного ресурса, находятся в одном месте. Однако это затрудняет быстрое определение того, как объявляются определенные типы элементов, например, при просмотре всех параметров.

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

Совет

Подумайте, не будет ли больше смысла в том, чтобы создать модули для групп связанных ресурсов и использовать для объединения модулей более простой шаблон. Более подробно мы будем рассматривать модули Bicep в схемах обучения по Bicep.

Каким образом пробелы помогают создавать структуру?

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

Как определить сразу несколько схожих ресурсов?

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

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

var cosmosDBContainerDefinitions = [
  {
    name: 'customers'
    partitionKey: '/customerId'
  }
  {
    name: 'orders'
    partitionKey: '/orderId'
  }
  {
    name: 'products'
    partitionKey: '/productId'
  }
]

resource cosmosDBContainers 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers@2024-05-15' = [for cosmosDBContainerDefinition in cosmosDBContainerDefinitions: {
  parent: cosmosDBDatabase
  name: cosmosDBContainerDefinition.name
  properties: {
    resource: {
      id: cosmosDBContainerDefinition.name
      partitionKey: {
        kind: 'Hash'
        paths: [
          cosmosDBContainerDefinition.partitionKey
        ]
      }
    }
    options: {}
  }
}]

Как развертывать ресурсы только в определенных средах?

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

var environmentConfigurationMap = {
  Production: {
    enableLogging: true
  }
  Test: {
    enableLogging: false
  }
}

resource logAnalyticsWorkspace 'Microsoft.OperationalInsights/workspaces@2023-09-01' = if (environmentConfigurationMap[environmentType].enableLogging) {
  name: logAnalyticsWorkspaceName
  location: location
}

resource cosmosDBAccountDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = if (environmentConfigurationMap[environmentType].enableLogging) {
  scope: cosmosDBAccount
  name: cosmosDBAccountDiagnosticSettingsName
  properties: {
    workspaceId: logAnalyticsWorkspace.id
    // ...
  }
}

Как выражать зависимости между ресурсами?

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

Bicep позволяет вам явно указать зависимость с помощью свойства dependsOn. Однако в большинстве случаев можно разрешить Bicep обнаруживать зависимости автоматически. При использовании символьного имени одного ресурса в свойстве другого Bicep обнаруживает связь. Лучше всего по возможности поручить это Bicep. В этом случае при изменении шаблона Bicep будет гарантировать правильность всех зависимостей и вы не добавите ненужный код, из-за которого шаблон станет более громоздким и трудным для чтения.

Как выражать связи между родительскими и дочерними объектами?

В Azure Resource Manager и Bicep есть концепция дочерних ресурсов, что имеет смысл только в том случае, если они развернуты в контексте родительского объекта. Например, база данных Azure SQL является дочерним объектом экземпляра сервера SQL. Дочерние ресурсы можно определять по-разному, но в большинстве случаев рекомендуется использовать свойство parent. Это помогает Bicep понять связь, чтобы обеспечить проверку в Visual Studio Code, и это делает связь ясной для всех пользователей, которые считывают шаблон.

Как задавать свойства ресурсов?

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

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

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

Совет

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

Например, если вам нужно отобразить URL-адрес приложения Службы приложений, избегайте создавать URL-адрес.

output hostname string = '${app.name}.azurewebsites.net'

Предыдущий подход прерывается, если Служба приложений изменяет способ назначения имен узлов приложениям или при развертывании в средах Azure, использующих разные URL-адреса.

Вместо этого используйте свойство defaultHostname ресурса приложения.

output hostname string = app.properties.defaultHostname

Как эффективно использовать систему управления версиями?

Системы управления версиями, такие как Git, могут упростить работу при рефакторинге кода.

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

Управление версиями также помогает удалять старый код из файлов Bicep. Что делать, если в коде Bicep есть определение ресурса, которое больше не требуется? Возможно, что когда-нибудь оно потребуется снова, и кажется логичным просто оставить его в файле, добавив комментарий. На самом деле такой подход лишь засоряет файл Bicep и не дает другим пользователям понять, почему в нем остались закомментированные ресурсы.

Кроме того, всегда есть вероятность, что какой-нибудь пользователь случайно раскомментирует определение, и это приведет к непредсказуемым или потенциально неблагоприятным результатам. При использовании системы управления версиями можно просто удалить старое определение ресурса. Если это определение потребуется снова, его можно будет извлечь из истории файла.