Установка

Состав поставки:

docker image + helm чарт axiom - все компоненты области Application разворачиваются из него, отличается только команда, которой запускается компонент
docker image + helm чарт axiom-web - web интерфейс

Зависимые компоненты типа Redis, PostgreSQL и прочее не являются частью приложения и разворачиваются из публичных образов, например bitnami. В поставляемом helm чарте этих зависимостей нет.

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

TL;DR

helm install metastore oci://registry-1.docker.io/bitnamicharts/postgresql
helm install broker oci://registry-1.docker.io/bitnamicharts/rabbitmq
helm install my-release oci://harbor.k8s.datasapience.ru/datasapience-charts/axiom

Команды выше установят последний релиз приложения со всеми зависимыми компонентами:

my-release - API
my-release-executor - worker, scheduler, monitor
broker - брокер RabbitMQ (user:password)
metastore - СУБД PostgreSQL под метаданные и под данные (postgres:postgres)

Такая инсталляция не зависит от внешних компонент и предоставляет достаточно адекватную конфигурацию для dev среды.

Архитектура

Metastore - база данных PostgreSQL, где приложение хранит свои метаданные, необходимые для работы
Datastore - одна из поддерживаемых СУБД для обработки бизнес-данных
File Storage - S3 хранилище для обмена файлами с пользователем системы
Broker - очередь сообщений на базе RabbitMQ или Redis
Application - само приложение. Cостоит из нескольких компонентов, общающихся между собой через broker:
- API - FastAPI приложение. Предоставляет доступ к функциям системы через REST API
- worker - Обработчик заданий на базе Celery. Управляет трансформациями, спускаемыми в Datastore
- scheduler (опционально) - планировщик задач на расписании на базе Celery Beat
- monitor (опционально) - система мониторинга Celery на базе Flower
Web UI - web-интерфейс приложения на базе React. Работает с приложением через REST API
Python SDK - python библиотека-wrapper для API приложения

Подготовка среды

k8s кластер.
утилита helm версии 3 или выше.
PostgreSQL под Metastore. Для работы приложению необходима СУБД PostgreSQL 12+ под метаданные. Развернуть ее можно любым удобным способом, например, воспользовавшись опциями от bitnami. В Metastore должна быть предварительно создана схема под метаданные. Учетная запись для доступа к базе данных должна иметь достаточные права для создания и удаления любых объектов в этой схеме.
Одна из поддерживаемых СУБД для Datastore. В Datastore должны быть предварительно созданы 3 схемы: под выходные датасеты, под загрузчики и под временные объекты трансформаций. Учетная запись для доступа к базе данных должна иметь достаточные права для создания и удаления любых объектов в этих схемах.

Установка Axiom API

Скопировать чарт и values.yaml

helm pull oci://harbor.k8s.datasapience.ru/datasapience-charts/axiom

helm show values axiom-*.tgz > values.yaml

ls
  axiom-X.Y.Z.tgz   values.yaml

Настройки приложения прописаны в формате кросс-ссылок по service name и хранятся в следующих конфигмапах и секретах:

{{ .Release.Name }}-configmap - Основные несекретные настройки приложения
{{ .Release.Name }}-secret - Настройки подключений к базам данных, minio и прочие параметры, которые могут содержать пароли

Отредактировать файл values.yaml:

Указать корректные значения для образа приложения

# values.yaml

global:
  image:
    repository: harbor.k8s.datasapience.ru/datasapience-registry/kolmogorov/axiom/axiom
    tag: latest  # версия образа из harbor
                 # соответствует номеру релиза приложения

Указать коррекные значения для переменных:
- META__URL: строка подключения к Metastore в формате postgresql://<user>:<pass>@<db-host>:<db-port>/<database>
- META__SCHEMA (default "meta"): схема в БД под метаданные приложения.
(optional) Если указать также следующие переменные, то при старте приложения в метаданных автоматически зарегистрируется источник данных по-умолчанию:
- DB__URL: строка подключения к Datastore в корректном формате
- DB__CONN_OPTIONS: дополнительные настройки
- DB__WORK_SCHEMA: схема в БД под временные объекты трансформаций
- DB__STORE_SCHEMA: схема в БД под основную витрину с данными
- DB__DATASET_SCHEMA (default "dataset"): схема в БД под выходные датасеты
Указать прочие желаемые переменые приложения

Выполнить установку приложения командой:

helm upgrade my-release axiom-*.tgz --install --dependency-update --atomic \
     --debug \
     --namespace ${NAMESPACE} \
     --values values.yaml

Доступ к API извне кластера через ingress

Для включения ингрессов необходимо в файле values.yaml изменить следующие значения:

# values.yaml

global:
  # домен на котором будет работать ingress
  baseDomain: example.com

service:
  ingress:
    enabled: true
    # Корректно заполнять annotations и tls для работы по HTTPS
    annotations:
      cert-manager.io/cluster-issuer: ...
    tls:
      secretName: ...

# опционально 
# для доступа к интефейсу Flower
executor:
  ingress:
    enabled: true
    annotations:
      cert-manager.io/cluster-issuer: ...
    tls:
      secretName: ...

Аутентификация через Keycloak

По-умолчанию аутентификация в приложении отключена. Для ее включения необходим сервис аутентификации и авторизации Keycloak. Развернуть его можно любым удобным способом, например, воспользовавшись опциями от bitnami. Ниже описана минимальная настройка интеграции с keycloak, но есть и другие опции.

В values.yaml указать следующие переменные внутри {{ .Release.Name }}-secret:

KEYCLOAK__AUTH_REQUIRED: установить true
KEYCLOAK__URL: адрес реалма Keycloak
KEYCLOAK__CLIENT_ID: имя приватного клиента, в котором заведeны роли доступа
KEYCLOAK__CLIENT_SECRET: секрет для доступа к клиенту

Файловое хранилище S3

По-умолчанию функционал загрузки файлов приложениe не включен. Для его включения необходимо S3-совместимое хранилище. Развернуть его можно любым удобным способом, например, воспользовавшись опциями от bitnami.

Затем указать следующие переменные внутри {{ .Release.Name }}-secret:

S3__ENABLED: Установить true
S3__URL: адрес API хранилища
S3__BUCKET: имя бакета в S3 хранилище
S3__ACCESS_KEY: S3 access key
S3__SECRET_ACCESS_KEY: S3 secret access key

Сбор телеметрии по стандарту OpenTelemetry

Если системе развернут сборщик телеметрии, например Jaeger приложение может отправлять телеметрию в него по протоколу OTLP/HTTP. Для этого необходимо установить:

переменную приложения TRACING__ENABLED=true
прочие стандартные OTEL_* переменные для OTLP/HTTP экспортера.

Для минимальной конфигурации экспортера необходимо установить переменную OTEL_EXPORTER_OTLP_ENDPOINT=http://<jaeger-host>:4318. Протокол OTLP/gPRC не поддерживается, только OTLP/HTTP.

Альтернативные конфигурации брокера сообщений

Кроме RabbitMQ в качестве брокера можно использовать Redis или Redis Sentinel, примеры заполнения URL приведены в values.yaml в поставляемом чарте.

Приложение тестировалось только с RabbitMQ и Redis, но должно работать с любой amqp совместимой очередью сообщений.

Чтобы подключить приложение к внешнему брокеру необходимо отредактировать values.yaml и указать следующие переменные внутри {{ .Release.Name }}-secret:

EXECUTOR__BROKER_URL: адрес брокера в формате redis://... если redis или amqp://... если rabbitmq

Хранилище секретов Vault

Чтобы не указывать значения секретов напрямую в чарте можно воспользоваться хранилищем секретов Vault. Пример создания секретов с использованием Vault можно посмотреть в chart/values.vault.yaml.

Масштабирование

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

API запускае количество тредов, равное $WEB_CONCURRENCY
worker запускает количество тредов, равное количеству cpu контейнера
scheduler запускается в единственном экземпляре
monitor запускается в единственном экземпляре

Для небольшой инсталляции такой конфигурации должно быть достаточно, но если есть желание запускать компоненты системы в несколько реплик, то необходимо подправить values.yaml, подправив значения replicas или hpa в секциях service и executor

Для брокера RabbitMQ есть родная инструкция для настройки конфигурации Disaster Recovery и High Availability.

Установка из whl-пакетов

Получить доступ к pypi репозиторию (например на базе nexus) в который выгружены whl-пакеты:
- axiom: основной пакет, содержащий логику api/worker/scheduler/monitor
- fs-core (зависимость): бизнес-логика
- fs-alchemy (зависимость): кодогенерация SQL
Запомнить или экспортировать переменные:
- NEXUS_USER: имя пользователя или __token__
- NEXUS_PASS: пароль или токен
- NEXUS_REPO: адрес репозитория без ведущего https:// в формате .../pypi/simple например git.angara.cloud/api/v4/projects/535/packages/pypi/simple

Установить основной пакет приложения командой:

export AXIOM_VERSION=... # устанавливаемая версия, например 0.16.0
python -m pip install -U axiom==$AXIOM_VERSION \ 
       --index-url https://${NEXUS_USER}:${NEXUS_PASS}@${NEXUS_REPO} \
       --extra-index-url https://${NEXUS_USER}:${NEXUS_PASS}@${NEXUS_REPO}

Запуск приложения осуществляется командой (с точностью до запускаемых компонент):

axiom start api worker scheduler monitor --run-migrations

Доступные опции запуска можно посмотреть командой:

axiom --help

Axiom Web

Скопировать чарт и values.yaml

helm pull oci://harbor.k8s.datasapience.ru/datasapience-charts/axiom-web

helm show values axiom-*.tgz > values.web.yaml

ls
  axiom-web-X.Y.Z.tgz   values.web.yaml

Отредакировать в values.yaml:

Указать настройки образа и ingress

service:
  image:
    repository: harbor.k8s.datasapience.ru/datasapience-registry/kolmogorov/axiom/web
    tag: latest  # версия образа из harbor
                 # соответствует номеру релиза приложения
  ingress:
    baseDomain: example.com
    host: "{{ .Release.Name }}"  # можно указать в явном виде
  extra_vars:
    - name: FS_API
      value: /api  # Если API на том же хосте. Полный путь если на другом

Указать прочие желаемые переменные окружения

Выполнить деплой приложения командой:

helm upgrade my-release-web axiom-web*.tgz --install --dependency-update --atomic \
     --debug \
     --namespace ${NAMESPACE} \
     --values values.web.yaml

Использование суффикса

При необходимости использования суффикса к домену WEB интерфейса нужно внести изменения в values.yaml на примере суффикса axiom-web:

uriPrefix в ingress: /axiom-web
value для ROOT_PATH_PREFIX: "/axiom-web"

Добавить перед /index.html в livenessProbe и readinessProbe

livenessProbe:
  httpGet:
    path: /axiom-web/index.html
...

readinessProbe:
  httpGet:
    path: /axiom-web/index.html