Рекомендации по использованию Bicep

Статья
07/11/2024

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

Учебные ресурсы

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

Параметры

Используйте понятные имена для объявления параметров. Так шаблоны будет проще читать и распознавать. Убедитесь, что вы используете понятные описательные и согласованные имена.
Тщательно продумайте параметры, используемые в шаблоне. Попробуйте использовать параметры для настройки значений, которые меняются между развертываниями. Переменные и прописанные в коде значения могут использоваться для параметров, которые не меняются между развертываниями.
Помните о значениях по умолчанию, которые вы используете. Убедитесь, что значения по умолчанию являются надежными для любого развертывания. Например, рекомендуется использовать недорогие ценовые категории и номера SKU, чтобы с пользователя, развертывающего шаблон в тестовой среде, не взималась большая сумма.
Однако декоратор @allowed нужно использовать относительно редко. Поскольку, используя декоратор слишком часто, можно заблокировать допустимые развертывания. Так как службы Azure добавляют номера SKU и размеры, ваш список разрешенных может быть неактуальным. Например, в рабочей среде могут иметь смысл только номера SKU "Премиум" версии 3, но в этом случае невозможно использовать один и тот же шаблон в нерабочих средах.
Предоставлять описания параметров — хорошее решение. Постарайтесь сделать описания полезными и предоставить все важные сведения о том, какие значения параметров необходимо задавать для шаблона.

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

Дополнительные сведения об использовании параметров Bicep см. в этой статье.

Переменные

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

Дополнительные сведения об использовании переменных Bicep см. в этой статье.

Имена

Используйте "верблюжий" стиль для имен переменных, например myVariableName или myResource.
Функция uniqueString() удобна при создании уникальных имен ресурсов. При указании одних и тех же параметров каждый раз возвращается одна и та же строка. Передача идентификатора группы ресурсов означает, что строка одинакова при каждом развертывании в той же группе ресурсов, но отличается при развертывании в разных группах ресурсов или подписках.
Рекомендуется использовать выражения шаблонов для создания имен ресурсов, как показано в следующем примере:
```
param shortAppName string = 'toy'
param shortEnvironmentName string = 'prod'
param appServiceAppName string = '${shortAppName}-${shortEnvironmentName}-${uniqueString(resourceGroup().id)}'
```
Использование выражений шаблонов для создания имен ресурсов дает ряд преимуществ:
- Строки, созданные uniqueString() не являются значимыми. Рекомендуется использовать выражение шаблона для создания имени, включающего значимые сведения, такие как короткий дескриптор имени проекта или среды, а также случайный компонент, который повысит вероятность того, что имя будет уникальным.
- Функция uniqueString() не гарантирует глобально уникальных имен. Добавляя дополнительный текст к именам ресурсов, вы снижаете вероятность повторного использования существующего имени ресурса.
- Иногда функция uniqueString() создает строки, которые начинаются с числа. Для некоторых ресурсов Azure, например учетных записей хранения, имена не могут начинаться с цифр. Это требование означает, что для создания имен ресурсов рекомендуется использовать интерполяцию строк. В уникальную строку можно добавить префикс.
- Многие типы ресурсов Azure имеют правила о разрешенных символах и длине их имен. Внедрение создания имен ресурсов в шаблон означает, что любой, кто использует шаблон, не должен помнить о том, что сам следует этим правилам.
Избегайте использования name в символическом имени. Символическое имя представляет ресурс, а не имя ресурса. Например, вместо следующего синтаксиса:
```
resource cosmosDBAccountName 'Microsoft.DocumentDB/databaseAccounts@2023-11-15' = {
```
Используйте следующую команду:
```
resource cosmosDBAccount 'Microsoft.DocumentDB/databaseAccounts@2023-11-15' = {
```
Избегайте дифференциации переменных и параметров с помощью суффиксов.

Определения ресурсов

Вместо того чтобы внедрять сложные выражения непосредственно в свойства ресурсов, используйте переменные для хранения выражений. Такой подход упрощает чтение и понимание файла Bicep. Это позволяет избежать засорения определений ресурсов логикой.
Старайтесь использовать свойства ресурса в качестве выходных данных, а не делать предположения о том, как будут вести себя ресурсы. Например, если вам нужно вывести URL-адрес в приложение Службы приложений, используйте свойство defaultHostname приложения вместо создания строки для URL-адреса самостоятельно. Иногда эти предположения неверны в разных средах или ресурсы меняют способ работы. Поэтому безопаснее, чтобы ресурс сообщал вам свои собственные свойства.
Рекомендуется использовать последнюю версию API для каждого ресурса. Новые функции служб Azure иногда доступны только в более новых версиях API.
По возможности избегайте использования функций reference и resourceId в файле Bicep. Вы можете получить доступ к любому ресурсу в Bicep, используя символическое имя. Например, если определить учетную запись хранения с помощью символического имени toyDesignDocumentsStorageAccount, можно получить доступ к ее ИД ресурса, используя выражение toyDesignDocumentsStorageAccount.id. Используя символическое имя, можно создать неявную зависимость между ресурсами.
Рекомендуется использовать неявные зависимости вместо явных. Хотя свойство ресурса dependsOn позволяет вам объявить явную зависимость между ресурсами, обычно можно использовать свойства другого ресурса, используя его символическое имя. Этот подход создает неявную зависимость между двумя ресурсами и позволяет Bicep самостоятельно управлять связями.
Если ресурс не развернут в файле Bicep, вы по-прежнему можете получить символическую ссылку на ресурс с помощью ключевого слова existing.

Дочерние ресурсы

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

Выходные данные

Убедитесь, что при работе с конфиденциальными данными не создаются выходные данные. Доступ к выходным значениям может получить любой пользователь, имеющий доступ к журналу развертываний. Поэтому они не подходят для обработки секретов.
Вместо того чтобы передавать значения свойств через выходные данные, используйте существующее ключевое слово для поиска свойств уже существующих ресурсов. Рекомендуется получать ключи из других ресурсов именно таким образом, а не передавать их через выходные данные. Это позволит получать самые актуальные данные.

Дополнительные сведения о выходных данных Bicep см. в этой статье.

Области клиента

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

Следующие шаги

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

Поделиться через