Общие сведения о шаблонах ИНТЕРФЕЙСА командной строки разработчика Azure

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

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

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

В этой статье объясняются структура шаблона и то, как команды azd используют его файлы.

Зачем использовать шаблон?

Шаблон записывает решения, необходимые для запуска проекта на Azure. В зависимости от проекта он может определить следующее:

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

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

Как azd использует шаблон

Файлы в шаблоне поддерживают различные этапы azd рабочего процесса:

  • azd init инициализирует проект и создает azd среду. Он также может использовать GitHub Copilot для создания первоначального шаблона или копирования существующего шаблона.
  • azd provisionвычисляет определения инфраструктуры и создает или обновляет ресурсы Azure.
  • azd package подготавливает сервисы приложений, готовые к развертыванию, в соответствии с azure.yaml.
  • azd deployсвязывает каждую службу со своим узлом Azure и развертывает пакет приложения.
  • azd up выполняет этапы подготовки, упаковки и развертывания в виде объединенного рабочего процесса.

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

Изучение структуры шаблона Azure Developer CLI

azd шаблоны — это стандартные репозитории кода с дополнительными ресурсами конфигурации и инфраструктуры. Большинство шаблонов используют следующую структуру:

  • azure.yaml file — определяет проект и сопоставляет развертываемые исходные каталоги с Azure ресурсами.
  • infra папка — содержит файлы инфраструктуры как кода Bicep или Terraform, которые создают ресурсы Azure.
  • src папка — обычно содержит развернутый исходный код приложения. Шаблоны, доступные только для инфраструктуры, могут опустить источник приложения, а шаблоны приложений могут использовать другие имена исходных каталогов.
  • .azure папка — содержит локальные среды и значения, созданные с помощью azd. Эта папка содержит локальное состояние проекта и обычно не включается в состав шаблона для повторного использования.

Например, общий azd шаблон может соответствовать следующей структуре папок:

contoso-project/
├── azure.yaml                 # azd project and service configuration
├── infra/
│   ├── main.bicep            # Infrastructure entry point
│   └── main.parameters.json  # Maps azd values to Bicep parameters
├── src/                      # Optional application source
│   ├── api/
│   └── web/
├── .github/workflows/        # Optional GitHub Actions pipelines
└── .azure/                   # Local environment state; don't distribute

azd шаблоны также необязательно включают одну или несколько следующих папок:

  • .github папка — содержит файлы рабочего процесса CI/CD для GitHub Actions.
  • .azdo папка. Если вы решили использовать Azure Pipelines для CI/CD, определите файлы конфигурации рабочего процесса в этой папке.
  • .devcontainer папка — определяет среду контейнера разработки для проекта.

На следующей схеме показано, как работают основные ресурсы шаблонов:

flowchart LR
AZ[azure.yaml] -->|Defines services| SRC[Application source]
AZ -->|Selects provider and path| INFRA[Infrastructure as code]
INFRA -->|Provisions| RES[Azure resources]
INFRA -->|Exports values| ENV[azd environment]
ENV -->|Configures| SRC
AZ -->|Maps services to| RES

Обязательные и необязательные ресурсы

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

azure.yaml

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

Для службы приложения azure.yaml обычно обозначает:

  • Путь к источнику приложения.
  • Язык программирования или стратегия упаковки.
  • Служба Azure, на котором размещено приложение.
  • Параметры сборки, развертывания, контейнера или Kubernetes.

Шаблоны, доступные только для инфраструктуры, могут опустить службы приложений. Полные модели конфигурации см. в схемеazure.yaml.

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

name: store
services:
  api:
    project: ./src/api
    language: js
    host: containerapp
  web:
    project: ./src/web
    language: js
    host: staticwebapp

Инфраструктура как код

Большинство шаблонов содержат infra каталог с Bicep или файлами Terraform. Эти файлы определяют Azure ресурсы, назначения ролей, сети, параметры приложения и выходные данные развертывания, необходимые для проекта.

Для поставщика Bicep, используемого по умолчанию, azd обычно использует infra/main.bicep в качестве точки входа для развертывания и infra/main.parameters.json для сопоставления значений среды azd с параметрами Bicep. Шаблоны Terraform обычно используют infra/main.tf и связанные файлы Terraform.

Например, файл параметров Bicep может передать в развертывание инфраструктуры значения, выбранные с помощью azd:

{
  "parameters": {
    "environmentName": { "value": "${AZURE_ENV_NAME}" },
    "location": { "value": "${AZURE_LOCATION}" }
  }
}

После завершения развертывания Bicep azd сохраняет выходные значения из точки входа как значения среды. Сервисы приложения и хуки могут использовать эти значения для конечных точек, имён и других параметров конфигурации во время выполнения.

output API_ENDPOINT string = api.outputs.uri

Источник приложения

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

Имя папки не имеет значения. Значение, указанное project в azure.yaml определении того, где azd находит каждую службу.

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

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

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

Вспомогательные ресурсы

Шаблоны также могут содержать:

  • определения GitHub Actions или Azure Pipelines.
  • Файлы Docker и конфигурации контейнеров.
  • Конфигурация контейнера разработки.
  • Хуки команд и сервисов.
  • Тесты, скрипты и документация по проекту.

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

Сопоставление службы и ресурса

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

Например, служба с именем api сопоставляется с ресурсом, помеченным тегом azd-service-name: api. Вместо этого можно использовать resourceName свойство службы для явного определения целевого объекта развертывания.

Следующее Bicep выражение добавляет тег обнаружения к существующим тегам ресурса:

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

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

Создание или адаптация шаблона

Рекомендуемый способ работы — запустить azd init и выбрать Настроить с помощью GitHub Copilot (предварительная версия). Выделенный сеанс агента Copilot может анализировать существующие файлы, помогать планировать новый проект, создавать шаблонные ресурсы и проверять результат. Сведения об этом рабочем процессе и других методах разработки см. в статье "Начало работы с новым шаблоном".

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

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

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

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

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

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

Дальнейшие действия

Обзор разработки шаблонов

  • Last updated on