Изучение и редактирование файлов шаблонов Azure Developer CLI

Шаблон интерфейса командной строкиazd разработчика Azure — это стандартный репозиторий с ресурсами конфигурации и инфраструктуры, которые позволяют azd подготавливать и развертывать проект. Независимо от того, создаете ли вы новый шаблон или начинаете с существующего, вы несете ответственность за просмотр и обслуживание своих файлов по мере развития проекта.

В этой статье объясняется, как проверить и изменить основные файлы шаблонов. Описание полной структуры на концептуальном уровне см. в шаблонах Azure Developer CLI.

В этой статье используется шаблон hello-azd в качестве стандартного примера, чтобы увидеть, что делает каждый файл в реальном проекте. Те же понятия применяются к шаблонам, которые создаются для собственных приложений. Чтобы продолжить, инициализировать шаблон в пустом каталоге:

azd init --template hello-azd

Шаблон hello-azd развертывает контейнерное приложение C# для Контейнеры приложений Azure и подготавливает вспомогательные ресурсы Azure через Bicep. В нем используется структура папок, например следующая, где каждый основной ресурс сопоставляется с разделом в этой статье:

.
├── azure.yaml                # Project configuration (Explore azure.yaml)
├── infra/                    # Infrastructure as code (Infrastructure files)
│   ├── main.bicep            # Deployment entry point
│   ├── main.parameters.json  # Parameter values that azd supplies
│   ├── abbreviations.json    # Resource name abbreviations
│   ├── app/                  # Application-specific modules
│   └── core/                 # Reusable resource modules
├── src/                      # Application source code (Source code)
│   └── Dockerfile            # Container image build for the app
├── .azure/                   # Environment configuration
└── README.md

Точная структура зависит от проекта, а azure.yaml определяет пути, которые использует azd. В следующих разделах описывается изменение каждого ресурса.

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

Исследовать azure.yaml

Файл azure.yaml определяет проект и указывает azd, как подготавливать инфраструктуру, упаковывать код приложения и развертывать каждую службу. Он позволяет определять службы, параметры инфраструктуры, хуки, рабочие потоки и другие аспекты поведения проекта.

Шаблон hello-azd определяет одну службу с именем aca:

name: azd-starter
metadata:
  template: hello-azd-dotnet
services:
  aca:
    project: ./src
    language: csharp
    host: containerapp
    docker:
      path: ./Dockerfile
      remoteBuild: true

Каждое свойство указывает azd, как обрабатывать службу:

• aca — имя службы. azdиспользует его для сопоставления службы с ресурсом Azure, на котором он размещен. Дополнительные сведения см. в разделе "Настройка обнаружения служб".
• project: ./src указывает на исходный код приложения, который azd упаковывает и развертывает.
• language: csharp определяет язык приложения.
• host: containerapp указывает azd развернуть сервис в Контейнеры приложений Azure.
• docker собирает образ контейнера из Dockerfile в каталоге src.
• remoteBuild сообщает azd использовать Реестр контейнеров Azure (ACR) для сборки образа контейнера.

Добавление определения службы

Добавьте запись под services для каждого дополнительного приложения, которое azd должно развернуть. Определение службы указывает исходный каталог, язык и Azure целевой объект размещения. Например, чтобы описать новый проект API:

services:
  api:
    project: ./src/api
    language: csharp
    host: appservice

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

Все доступные свойства и поддерживаемые значения см. в схемеazure.yaml.

Исходный код

Источник приложения является необязательным. Шаблоны с развертываемыми приложениями часто упорядочивают исходный код в каталоге src , но вам не нужно использовать определенное имя папки или макет. Свойство project каждой службы в azure.yaml сообщает azd, где находится её исходный код.

В hello-azd служба aca задаёт project: ./src, поэтому azd упаковывает приложение C# в каталоге src и развертывает его в Контейнеры приложений Azure. Поскольку служба также задаёт конфигурацию docker, azd собирает образ контейнера из Dockerfile в каталоге src перед развертыванием.

azd поддерживает Node.js, Python, .NET, Java и Go на поддерживаемых узлах Azure. Шаблон также может развертывать контейнеры. Сведения о текущих сочетаниях языков, платформ и узлов см. в разделе "Поддерживаемые языки и среды".

Измените исходный код так же, как и в любом репозитории приложений. При добавлении службы или перемещении исходного каталога обновите его azure.yaml определение службы. Если приложению требуется новый ресурс Azure, обновите инфраструктуру и передайте требуемое имя конечной точки или ресурса в приложение через конфигурацию.

Изменение исходного каталога службы

Например, если вы переместите приложение hello-azd из aca в src, обновите значение src/app службы project:

services:
  aca:
    project: ./src/app
    language: csharp
    host: containerapp
    docker:
      path: ./Dockerfile
      remoteBuild: true

Файлы инфраструктуры

Каталог infra содержит файлы Bicep или Terraform, определяющие Azure ресурсы для шаблона. В каталоге infra в hello-azd используется язык Bicep и включены следующие ключевые ресурсы:

• main.bicep — это стандартная точка входа для развертывания, которую azd запускает для подготовки ресурсов.
• main.parameters.json предоставляет значения параметров для main.bicep.
• app содержит модули, относящиеся к приложению.
• core содержит многократно используемые модули для общих ресурсов, таких как хранилище и размещение.

Как main.bicep работает во время azd up

При запуске azd upэтап подготовки развертывается infra/main.bicep. В hello-azdmain.bicep нацеливается на область действия подписки, создает группу ресурсов, а затем вызывает модули для развертывания ресурсов, необходимых приложению:

targetScope = 'subscription'

// Create a storage account
module storage './core/storage/storage-account.bicep' = {
  name: 'storage'
  scope: rg
  params: {
    name: !empty(storageAccountName) ? storageAccountName : '${abbrs.storageStorageAccounts}${resourceToken}'
    location: location
    tags: tags
    allowSharedKeyAccess: false
    containers: [ { name: 'attachments' } ]
    tables: [ { name: 'tickets' } ]
  }
}

// Container app for the 'aca' service
module web 'app/app.bicep' = {
  name: serviceName
  scope: rg
  params: {
    // ...
    serviceName: serviceName
  }
}

Файл main.bicep подготавливает управляемое удостоверение, назначаемое пользователем, учетную запись служба хранилища Azure, среду Контейнеры приложений Azure и реестр, а также приложение контейнера, на котором размещена aca служба. Он также назначает роли, позволяющие управляемому удостоверению получать доступ к хранилищу. Модули сохраняют каждый ресурс в собственном файле, чтобы main.bicep оставаться удобочитаемым.

Добавить ресурс в main.bicep

Добавьте объявления ресурсов непосредственно в infra/main.bicep для простых или разовых ресурсов. Выносите ресурсы в отдельные модули Bicep, если вы используете их повторно, если для ресурса требуется несколько связанных ресурсов или если вы хотите сохранить удобочитаемость main.bicep. Как и в hello-azd, многие шаблоны группируют повторно используемые модули в infra/core.

Для распространённых ресурсов Azure предпочитайте Azure Verified Module вместо создания модуля с нуля. Проверенные модули поддерживаются Microsoft, соблюдают рекомендации по обеспечению безопасности и надежности и сокращают объем кода инфраструктуры, который вы поддерживаете в шаблоне.

Полное пошаговое руководство по добавлению нового ресурса в hello-azd см. в разделе Расширение шаблона.

Файл main.parameters.json сопоставляет значения, поддерживаемые azd, с параметрами Bicep. Шаблон hello-azd использует следующие параметры:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "environmentName": { "value": "${AZURE_ENV_NAME}" },
    "location": { "value": "${AZURE_LOCATION}" },
    "principalId": { "value": "${AZURE_PRINCIPAL_ID}" },
    "principalType": { "value": "${AZURE_PRINCIPAL_TYPE=User}" }
  }
}

Каждая запись привязывает параметр Bicep к значению, которое azd хранится в среде, например имя среды, расположение и субъект, выполняющий развертывание. Используйте main.parameters.json для значений, которые зависят от среды или развертывания, таких как имя среды, местоположение или имена ресурсов, создаваемых azd. Оставляйте постоянные значения, которые не меняются в разных средах, как значения параметров по умолчанию или литералы в main.bicep. Этот подход позволяет повторно использовать один и тот же шаблон Bicep в разных средах, не изменяя его для каждого развертывания.

При добавлении или изменении инфраструктуры:

• Сохраняйте конфигурацию ресурсов независимой от среды. Используйте параметры и azd значения переменных среды вместо встраивания идентификаторов подписок, имен ресурсов, регионов или учетных данных.
• Используйте защищённые выходные значения для чувствительных значений и не раскрывайте секреты в выходных данных развертывания в открытом виде.
• Применение назначений ролей с наименьшими привилегиями к управляемым удостоверениям.
• Сохраняйте определения служб в azure.yaml соответствии с целевыми ресурсами.
• Просмотрите эффекты уровней служб, ограничения масштабирования, избыточности и параметров хранения по затратам.

Рекомендации по языку Bicep и модулям см. в документации по Bicep. Сведения о шаблонах на основе Terraform см. в разделе Использование Terraform с Azure Developer CLI.

Настройте обнаружение служб

По умолчанию azd обнаруживает ресурс Azure для службы, находя ресурс, тег azd-service-name которого соответствует имени службы в azure.yaml. При переименовании службы обновите соответствующий тег ресурса или явно настройте имя ресурса в azure.yaml.

Например, в hello-azd имя службы aca совпадает с тегом azd-service-name в ресурсе приложения-контейнера. Определение azure.yaml службы задает имя:

services:
  aca:
    project: ./src
    language: csharp
    host: containerapp

Модуль контейнерного приложения в infra/app/app.bicep применяет соответствующий тег:

tags: union(tags, { 'azd-service-name': serviceName })

Настройка нестандартного пути инфраструктуры

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

infra:
  provider: bicep
  path: infra
  module: main

Конфигурация среды

Каталог .azure содержит состояние и значения локальной среды, которые azd создают, такие как выбранная подписка, расположение, имена ресурсов и выходные данные развертывания. Для этого каталога следует рассматривать как локальное состояние, а не повторно используемый ресурс шаблона. Не коммитьте файлы окружения, содержащие секреты или значения, зависящие от окружения.

Добавить выходные параметры инфраструктуры

При запуске azd provision для развертывания Bicep он сохраняет выходные данные из точки входа инфраструктуры как значения среды azd. Добавьте выходные параметры для конечных точек ресурсов, имен ресурсов и идентификаторов клиентов управляемых удостоверений, которые требуются службам приложений или хукам. Например, hello-azd выводит данные о реестре контейнеров и управляемом идентификаторе из main.bicep:

output AZURE_CONTAINER_REGISTRY_ENDPOINT string = containerAppsEnv.outputs.registryLoginServer
output AZURE_CONTAINER_REGISTRY_NAME string = containerAppsEnv.outputs.registryName
output AZURE_USER_ASSIGNED_IDENTITY_NAME string = identity.outputs.name

Не раскрывайте секреты, если доступ вместо этого можно получить с помощью управляемой идентификации или ссылки на Key Vault. После подготовки проверьте захваченные значения, выполнив команду azd env get-values.

Дополнительные сведения см. в разделе "Управление переменными среды".

Проверьте изменения

Запустите azd up , чтобы подготовить инфраструктуру и развернуть все службы приложений:

azd up

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

Связанные материалы

• Обзор разработки шаблонов
• Начните с нового шаблона
• Начало работы с существующего шаблона
• Расширение шаблона
• azd up Изучение рабочего процесса

Запрос помощи

Чтобы получить информацию о том, как сообщить об ошибке, запросить помощь или предложить новую функцию для интерфейса командной строки разработчика Azure (CLI), перейдите на страницу устранения неполадок и поддержки.