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

Рекомендации по Bicep

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

Обучающие материалы

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

Параметры

  • Используйте хорошее именование для объявлений параметров. Хорошие имена упрощают чтение и понимание шаблонов. Убедитесь, что вы используете четкие, описательные имена и соблюдаете последовательность в именовании.

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

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

  • Однако декоратор @allowed нужно использовать относительно редко. Если вы используете этот декоратор чрезмерно, вы можете заблокировать допустимые развертывания. Так как службы Azure добавляют SKU и размеры, список разрешенных может быть не обновлен. Например, разрешение использования только SKU "Премиум" v3 может иметь смысл в производственной среде, но это мешает использовать тот же шаблон в непроизводственной среде.

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

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

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

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

Дополнительные сведения о параметрах 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 свойство или вложение.

Выходы

  • Пометьте конфиденциальные данные в выходных данных с помощью декоратора @secure(), что предотвращает ведение журнала или отображение конфиденциальных выходных данных. В противном случае выходные значения могут быть доступны любому, у кого есть доступ к журналу развертывания.

  • Вместо передачи значений свойств через выходные данные используйте существующее ключевое слово для поиска свойств ресурсов, которые уже существуют. Рекомендуется искать ключи из других ресурсов таким образом, а не передавать их через выходные данные. Вы всегда получите самые актуальные данные up-to.

Дополнительные сведения о выходных данных Bicep см. в разделе «Выходные данные в Bicep».

Области арендатора

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

Дальнейшие шаги

  • Last updated on