Разработка спутника¶

Спутник это отраслевой пакет контента, который ставится поверх платформы Орбиты: описания данных и отчёты, при необходимости данные для аналитического хранилища, надстройка единого входа, дополнительные параметры окружения, собственные настройки и произвольные шаги установки. Порядок установки готового Спутника администратором описан в разделе Спутники: установка и управление.

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

Структура пакета¶

Исходник Спутника это каталог satellites/<name>/:

satellites/<name>/
  satellite.json          манифест (обязателен)
  domains/*.yaml          описания данных отрасли
  reports/*.yaml          преднастроенные отчёты
  datasets/catalog.yaml   фрагмент каталога датасетов
  seed/*.{sql,parquet}    данные и схемы для аналитического хранилища
  keycloak/               надстройка единого входа
  env                     дополнительные параметры окружения
  tasks/main.yml          шаги установки
  tasks/uninstall.yml     шаги удаления

Обязателен только satellite.json. Остальные части опциональны: Спутник объявляет, что несёт, флагами contents в манифесте.

Манифест satellite.json¶

Поле	Тип	Назначение
`satellite_format`	число	Версия формата пакета. Сейчас `1`.
`name`	строка	Идентификатор (слаг: `[a-z0-9_-]`). Используется в путях и для хранения настроек.
`display_name`	строка	Человекочитаемое имя.
`version`	строка	Версия Спутника. Входит в имя собираемого пакета.
`min_orbita_version`	строка	Минимальная версия Орбиты, на которой Спутник работает. Сверяется при установке.
`max_orbita_version`	строка, опционально	Верхняя граница совместимости.
`requires`	список имён, опционально	Другие Спутники, которые должны быть установлены.
`contents`	объект	Флаги наличия частей: `domains`, `reports`, `seed`, `keycloak`, `env`, `ansible`.
`settings`	список, опционально	Собственные настройки установки (см. ниже).

Пример манифеста: satellites/example/satellite.json.

Описания данных (domains)¶

Отраслевая модель данных. Формат совпадает с платформенными описаниями данных: те же ключи верхнего уровня (name, display_name, description, schema и другие). Описания хранятся в базе метаданных, YAML это формат импорта. При установке Спутника описания импортируются в базу метаданных с обновлением по имени. Про сам формат см. Подключение данных.

Отчёты (reports)¶

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

Каталог датасетов (datasets/catalog.yaml)¶

Фрагмент каталога, описывающий датасеты Спутника:

default_enabled: all
datasets:
  <dataset>:
    description: ...
    domain: <domain-file>.yaml
    seed: []           # список seed-файлов в порядке загрузки

При установке платформа объединяет каталог базы с каталогами активных Спутников. Конфликт по имени датасета разрешается в пользу более позднего слоя. Активный набор датасетов это объединение по слоям: каждый слой включает то, что объявил.

Данные (seed)¶

Схемы (*_schema.sql) и данные (*.parquet) для аналитического хранилища. При установке Спутника с флагом contents.seed они загружаются автоматически: сначала схемы, затем данные (имя parquet-файла соответствует имени целевой таблицы). Для внешнего аналитического хранилища этот шаг пропускается: загрузку выполняйте своими средствами или шагами установки Спутника.

Надстройка единого входа (keycloak)¶

Провайдеры и темы копируются на сервер при установке в общий каталог сервиса аутентификации, после чего он перезапускается. При удалении Спутника эти файлы вычищаются по списку из его пакета.
Надстройка realm (дополнительные области доступа, преобразователи, роли, внешние поставщики входа) применяется файлом keycloak/realm-overlay.json. Для повторяемости включите в него признак перезаписи существующих объектов. Требует работающего сервиса аутентификации, поэтому проверяется на стенде.

Учтите: объекты realm, добавленные надстройкой, при удалении Спутника автоматически не снимаются, в отличие от файлов провайдеров и тем. Обратной операции у сервиса аутентификации нет.

Дополнительные параметры (env)¶

Файл вида КЛЮЧ=ЗНАЧЕНИЕ, по одной паре на строку (пустые строки и строки с # игнорируются). При установке эти параметры дописываются к параметрам окружения сервера отдельным помеченным блоком.

Настройки Спутника (settings)¶

Значения, которые свои на каждую установку: ключ доступа к источнику, признак включения функции и подобное. Их нельзя зашивать в пакет, потому что пакет один на все установки. Поэтому Спутник объявляет схему настроек, а значения задаются на конкретное окружение и хранятся в хранилище секретов.

Схема в satellite.json:

"settings": [
  {"key": "SAT_API_KEY", "label": "Ключ API", "secret": true, "default": "", "description": "..."}
]

Значения задаются на окружение (свои для каждого Спутника). Администратор правит их в меню «Настройки», пункт «Настройки спутников»; секретные значения маскируются.
Незаданные значения берутся из default манифеста.
При установке значения доходят до Спутника двумя путями: как параметры окружения приложения и как переменные для шагов установки (доступны как satellite_config).

Произвольные шаги установки¶

Для гибкости Спутник может нести произвольные шаги установки: то, что не покрывается декларативными частями (установка дополнительного пакета, регламентное задание, специфичная настройка).

tasks/main.yml это шаги установки. Выполняются на сервере после применения декларативного содержимого Спутника.
tasks/uninstall.yml это шаги удаления. Выполняются при удалении перед снятием пакета. Произвольные шаги нельзя откатить автоматически, поэтому удаление пишет сам автор.
Флаг contents.ansible включает эти шаги.

Внутри шагов доступны:

satellite_dir: каталог Спутника на управляющей машине (для ссылок на свои файлы);
satellite_config: настройки Спутника;
orbita_config_dir, orbita_base_dir, orbita_data_dir: пути установки на сервере.

Требование к шагам: повторный запуск безопасен (идемпотентность).

Доверие к пакету

Произвольные шаги установки это выполнение кода с максимальными правами на сервере. По уровню доверия Спутник равен поставке платформы. Устанавливать Спутники из непроверенных источников без разбора содержимого нельзя. Модель рассчитана на Спутники от доверенного поставщика.

Совместимость¶

min_orbita_version Спутника сверяется с установленной версией платформы. При несовместимости средство установки выводит предупреждение.
requires перечисляет другие Спутники, которые должны присутствовать.

Сборка пакета¶

Из каталога deploy_cli/:

make satellite NAME=<name>
# результат: deploy_cli/dist/orbita-satellite-<name>-<version>.tar.gz

Версия берётся из satellite.json. Пакет самодостаточен, не зависит от операционной системы и распространяется как один архив без докачки из интернета.

Проверка при разработке¶

Проверка описаний данных и отчётов без записи в базу:

python -m orbita_api.manage import-satellite <dir> --dry-run
python -m orbita_api.manage uninstall-satellite <dir> --dry-run

Рекомендуемый сквозной прогон на тестовом стенде: развернуть платформу без наполнения, установить example, проверить, что описания данных и отчёты появились и каталог датасетов объединён, затем удалить и убедиться, что описания и отчёты сняты, а загруженные данные остались нетронутыми.