exordos build

Обзор#

exordos build компилирует и упаковывает ваш Exordos элемент в распространяемые артефакты — образы, манифесты и любые другие ресурсы, необходимые для развёртывания.

Команда читает файл exordos/exordos.yaml — основной конфигурационный файл, который превращает ваше приложение в элемент платформы. Этот файл содержит секцию build, описывающую:

Зависимости — файлы, директории или внешние бинарные артефакты, необходимые для сборки
Элементы — один проект может производить несколько элементов на выходе (например, отдельные сервисы API и worker)
Артефакты — образы, бинарные файлы или другие результаты сборки

Выполнение команды выполняет следующие шаги:

Разрешение зависимостей — загружает зависимости, указанные в exordos.yaml.
Обработка манифестов — рендерит файлы манифестов (поддерживаются raw YAML или шаблоны Jinja2 со встроенными переменными).
Сборка артефактов — создаёт образы и другие результаты сборки на основе секции build в exordos.yaml.

exordos build [OPTIONS] PROJECT_DIR

Ключевые опции:

Опция	Описание
`-c, --exordos-cfg-file TEXT`	Имя файла конфигурации проекта (по умолчанию: `exordos.yaml`)
`--build-dir TEXT`	Директория для временных артефактов сборки
`--output-dir TEXT`	Директория, где хранятся финальные артефакты
`--deps-dir TEXT`	Директория, куда загружаются зависимости
`-i, --developer-key-path TEXT`	Путь к публичному ключу разработчика. Ключ встраивается в собранные образы для подписи и аутентификации
`-f, --force`	Пересобрать, даже если результат уже существует

Требования#

Перед сборкой убедитесь, что у вас установлены следующие инструменты:

packer
qemu

Используйте Packer версии 1.9.2 или ранее из-за ограничений лицензирования.

Linux (Ubuntu)#

Установка пакетов

sudo apt update
sudo apt install qemu-kvm mkisofs

Добавление пользователя в группу

sudo adduser $USER kvm

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

Начало работы#

Базовая сборка#

Из директории вашего проекта:

exordos build .

Пересборка с force#

Если вам нужно пересобрать, даже когда артефакты уже существуют:

exordos build --force .

Сборка с пользовательскими переменными#

Передайте дополнительные переменные в шаблоны манифестов:

exordos build --manifest-var commit_hash=$(git rev-parse --short HEAD) .

Сборка только образов#

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

exordos build --only-images .

Процесс сборки#

Процесс сборки создаёт образы VM дисков, которые запускаются на платформе Exordos Core. Packer запускает виртуальную машину из базового образа ОС, копирует все разрешённые зависимости в неё и выполняет скрипт подготовки, указанный в exordos.yaml. Этот скрипт обычно является Bash-скриптом, который устанавливает пакеты, настраивает сервисы и подготавливает образ. После завершения подготовки VM выключается, и полученный образ диска упаковывается для развёртывания. Этот процесс настраивается через секцию elements в exordos.yaml, где вы определяете базовый профиль, скрипт подготовки, формат вывода и любые переопределения сборки.

Разрешение зависимостей#

Перед сборкой exordos build разрешает все зависимости, объявленные в секции build.deps файла exordos.yaml. Каждая зависимость указывает путь назначения (dst) и источник. Зависимости могут быть локальными директориями, удалёнными артефактами или опциональными ресурсами для разработки.

Локальная директория проекта#

Включите другой локальный проект или директорию в вашу сборку. Путь источника относителен к расположению файла exordos.yaml.

deps:
  - dst: /opt/exordos_core
    path:
      src: ../../exordos_core
    exclude:
      - .venv
      - .tox
      - build
      - output

Это копирует проект exordos_core в /opt/exordos_core во время сборки, исключая директории разработки.

Внешние бинарные артефакты#

Получите удалённые ресурсы через HTTP/HTTPS. Это полезно для образов ядра, загрузчиков или предварительно скомпилированных бинарных файлов.

deps:
  - dst: /opt/exordos_core/artifacts/vmlinuz
    http:
      src: https://repository.exordos.com/seed_os/1.1.0/vmlinuz

Образ ядра vmlinuz загружается и помещается по указанному пути назначения перед продолжением сборки.

Опциональные зависимости#

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

deps:
  - dst: /opt/gcl_sdk
    optional: true
    path:
      env: LOCAL_GENESIS_SDK_PATH

Здесь SDK включается только если установлена переменная окружения LOCAL_GENESIS_SDK_PATH. Если она не задана, сборка продолжается без этой зависимости.

Конфигурация сборки образов VM#

Каждый элемент в списке elements файла exordos.yaml определяет, как собираются его образы VM. Элемент может производить несколько образов (например, разные форматы или варианты). Следующие параметры управляют процессом создания образа:

Параметр	Описание
`name`	Имя выходного образа. Используется для идентификации образа в результатах сборки и реестре.
`format`	Формат образа диска. Поддерживаемые форматы: `raw`, `qcow2`, `gz`. Формат `gz` — это сжатый `raw` образ. Также может ссылаться на переменную окружения, например `GEN_IMG_FORMAT_CORE=qcow2`.
`profile`	Профиль базового образа ОС, используемый как отправная точка (например, `exordos_base`). Определяет начальную операционную систему и предустановленные пакеты.
`script`	Путь к скрипту подготовки, выполняемому внутри VM. Этот скрипт выполняет всю специфичную для приложения настройку: установку зависимостей, копирование файлов, настройку сервисов.
`override`	Переопределения параметров сборки, передаваемые в базовый инструмент (например, Packer). Типичные использования включают увеличение `disk_size`, `cpus` или `memory` для VM сборки. При использовании профиля `exordos_custom` укажите здесь `base_image_url` и `base_image_checksum` для использования любого произвольного образа как базового.
`envs`	Список переменных окружения для передачи в процесс сборки. Они становятся доступными для скрипта подготовки и инструментов сборки.

Использование переменных окружения#

Определите переменные в exordos.yaml:

elements:
  - manifest: manifests/core.yaml.j2
    images:
      - name: my-app
        format: qcow2
        profile: exordos_base
        script: install.sh
        envs:
          - APP_PORT=8080
          - LOG_LEVEL=info
          - DATABASE_URL

Используйте их в вашем скрипте подготовки:

#!/bin/bash
# install.sh

echo "Starting application on port $APP_PORT"
echo "Log level set to: $LOG_LEVEL"

# DATABASE_URL будет передана, если установлена в окружении
if [ -n "$DATABASE_URL" ]; then
    echo "Database configured: $DATABASE_URL"
fi

Обработка манифестов#

Манифест в вашем проекте может быть:

Raw YAML — используется как есть во время сборки
Шаблон Jinja2 — динамически рендерится со встроенными переменными

Для шаблонов Jinja2 по умолчанию доступны следующие переменные:

Переменная	Описание
`{{ version }}`	Версия собираемого элемента
`{{ name }}`	Имя элемента
`{{ images }}`	Список собранных образов для этого элемента
`{{ manifests }}`	Список файлов манифестов

Дополнительные переменные можно передать с помощью --manifest-var key=value:

exordos build --manifest-var environment=production --manifest-var region=europe-east .

Полный справочник по манифестам →

Выходные артефакты#

После успешной сборки в --output-dir (по умолчанию: output/ проекта) создаются следующие артефакты:

output/
├── inventory.json          # Манифест сборки, перечисляющий все созданные артефакты
├── images/                 # Собранные образы VM дисков
│   └── <element-name>.<format>
└── manifests/              # Скомпилированные манифесты для каждого элемента
    └── <element-name>.yaml

Файл inventory.json предоставляет полный индекс результатов сборки, отображая каждый элемент на его артефакты:

Поле	Описание
`name`	Имя элемента
`version`	Полная строка версии с меткой времени и git хешем
`images`	Список путей к собранным образам VM дисков
`manifests`	Список путей к скомпилированным манифестам
`artifacts`	Дополнительные артефакты сборки (если есть)
`configs`	Конфигурационные файлы (если есть)
`templates`	Файлы шаблонов, использованные при сборке (если есть)

Точное содержимое зависит от типа вашего проекта и конфигурации exordos.yaml.

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

После успешной сборки ваши элементы готовы для:

exordos push — публикация в реестр экосистемы
exordos deploy — развёртывание в установку Exordos

Устранение неполадок#

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