Перейти к основному содержимому

Virtual Environment Services (VES) Workflow

Этот гайд описывает работу с изолированными сервисами в HSM через рантайм uv.

1. Концепция VES​

Virtual Environment Services (VES) — это механизм HSM, позволяющий запускать сервисы в полностью изолированных Python-окружениях (venv) с собственными pyproject.toml и uv.lock.

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

2. Создание нового сервиса​

Для создания изолированного сервиса используйте команду hsm service init:

hsm service init my-worker --runtime uv

Что произойдет:

  1. В папке services/my-worker будет создан новый проект (uv init --no-workspace).
  2. Сервис будет автоматически зарегистрирован в локальном реестре hsm-registry/services/my-worker.yaml.
  3. Сервис будет добавлен в ваш hsm.yaml.

3. Управление зависимостями сервиса​

Зависимости изолированного сервиса описываются в его собственном манифесте в реестре.

Добавление зависимости через CLI:​

hsm registry service add my-worker --dependency my-shared-lib

При выполнении hsm sync, HSM:

  1. Обнаружит, что my-worker требует my-shared-lib.
  2. Найдет my-shared-lib в реестре.
  3. Инжектирует правильный путь (локальный или git) в services/my-worker/pyproject.toml.
  4. Выполнит uv sync внутри директории сервиса.

4. Проброс контекста (ENV) через Implies​

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

Пример: библиотека db-client подразумевает настройку сервиса my-worker:

# hsm-registry/libraries/db-client.yaml
name: db-client
implies:
  service:my-worker:
    params:
      DB_URL: "postgres://localhost:5432/mydb"

При синхронизации HSM пробросит DB_URL в переменные окружения при запуске команд внутри my-worker.

5. Синхронизация и проверка​

Команда hsm sync автоматически обрабатывает все VES сервисы:

hsm sync

Для проверки того, что сервис действительно изолирован и использует правильные версии пакетов, HSM использует EnvironmentInspector. Вы можете увидеть отчет о верификации сразу после синхронизации.

6. Режимы Dev и Prod​

  • Dev: Сервис использует локальный исходный код (если указан dev source).
  • Prod: HSM автоматически клонирует репозиторий сервиса из Git в папку services/ и собирает окружение на основе uv.lock из репозитория.