diff --git a/doc/progress.md b/doc/progress.md index b7f8ce0..341d4a1 100644 --- a/doc/progress.md +++ b/doc/progress.md @@ -4,6 +4,103 @@ --- +## 2026-03-28 — Handoff: функции-джобы для установки ПО в ВМ (курс на PostgreSQL) + +### Контекст и цель + +- Пример [examples/VM](examples/VM) рассматривается как пользовательский Terraform-шаблон. +- Пользовательский сценарий: скачать шаблон, подставить токены/ключи, выбрать нужные пакеты, выполнить `terraform apply`. +- Целевое поведение: один apply поднимает `vApp + VM` и запускает автоматическую установку ПО в VM. +- Vault в облаке пока недоступен, но архитектура должна быть ready для последующего перехода на Vault без переписывания логики функций. + +### Что выяснили по текущей платформе (sless) + +- Для one-shot действий в sless уже есть подходящая сущность: `sless_job`. +- Модель запуска: +1. Создаётся job-ресурс. +2. Загружается исходник функции (`/upload`). +3. Оператор собирает образ (kaniko). +4. Job запускается в k8s, статус виден как `Pending/Building/Running/Succeeded/Failed`. +- Передача входных параметров: +1. `event_json` -> payload в `handle(event)`. +2. `env_vars` -> переменные окружения внутри контейнера. +- Ошибки установки отслеживаются на нескольких уровнях: +1. Terraform apply (resource fail). +2. Статус job (`Phase`, `Message`). +3. Логи пода/контейнера (детали SSH/apt/команд). + +### Архитектурное решение на сейчас + +- Не делать отдельный новый Terraform resource под установку пакетов на текущем этапе. +- Использовать `sless_job` как основной механизм выполнения. +- Причина: установка ПО по SSH в VM - это execution-задача (one-shot), а не устойчивый ресурс со сложной моделью state/drift. +- Отдельный resource рассматривать позже, когда стабилизируется контракт (semantics ensure-present/absent/version + read/drift). + +### Принятый целевой дизайн (этап 1) + +1. Универсальная функция-джоб `install-packages`. +2. Отдельные специализированные функции-джобы: `install-docker`, `install-git`, далее по необходимости. +3. В Terraform-шаблоне флаги/переменные включают нужные джобы. +4. Общая схема параметров: +: `event_json` для бизнес-параметров (список пакетов, режимы). +: `env_vars` для подключения к VM (`VM_IP`, `SSH_USER`, `SSH_KEY`). + +### План по PostgreSQL-направлению (что делать дальше) + +#### Этап A: Базовый VM bootstrap + +1. Реализовать `install-packages` (apt update/install, идемпотентность, явные коды ошибок). +2. Реализовать `install-git` как отдельный job-шаблон. +3. Реализовать `install-docker` как отдельный job-шаблон (репозиторий/GPG, проверка `docker --version`). + +#### Этап B: PostgreSQL-specific функции + +1. Добавить `install-postgres` job: +: установка `postgresql`, `postgresql-contrib`, `postgresql-client`. +: проверка статуса `systemctl is-active postgresql`. +2. Добавить `configure-postgres` job: +: создание БД/пользователя. +: настройка доступа (минимально безопасная, через параметры). +: проверка подключения `psql`. +3. Добавить `seed-postgres` job (опционально): +: создание таблиц/базовых данных для демо. + +#### Этап C: Terraform UX для пользователя шаблона + +1. Вынести управляемые параметры в `terraform.tfvars`: +: `install_packages`, `install_docker`, `install_git`, `install_postgres`. +: `postgres_db`, `postgres_user` и др. параметры. +2. Обеспечить зависимости: +: VM должна быть готова до старта job. +: Postgres-конфиг запускается после установки postgres. +3. Добавить outputs с итоговым статусом job-ов для быстрого контроля. + +#### Этап D: Переход на Vault (когда сервис появится) + +1. Не менять код функций. +2. Заменить только источник секретов в Terraform (`env_vars` заполняются из Vault data source). +3. Сохранить обратную совместимость с текущим режимом (секрет в tfvars) для dev/demo. + +### Риски и ограничения, зафиксированные заранее + +1. SSH/apt операции подвержены временным сетевым сбоям и lock-файлам apt -> нужны retries и читаемые сообщения об ошибках. +2. Job-модель не равна полноценному stateful resource: drift пакетов в VM не отслеживается автоматически Terraform-ом. +3. Для production-пути позже потребуется отдельный контракт безопасности по секретам и ротации ключей. + +### Что уже сделано в этой ветке перед handoff + +1. Обновлён пример VM по nubes provider `5.0.49`. +2. Переименованы имена VM/vApp ресурсов в более короткий формат (`vm-sless`, `vapp-sless`). +3. Изменения закоммичены и отправлены в ветку `examples/dev-from-ground`. + +### Рекомендация для нового чата + +1. Стартовать реализацию с `install-packages` + Terraform wiring в [examples/VM](examples/VM). +2. После успешного E2E добавить `install-postgres` и `configure-postgres`. +3. Держать код максимально идемпотентным, чтобы повторный apply не ломал VM. + +--- + ## 2026-03-23 — Сессия 11: Баги cache-тест, fix оператора v0.1.62, fix провайдера ### Что сделано