ddadmin
688c46c68b
- Зачем: - нужен воспроизводимый вход в курс и единое место хранения планов по модулям. - Что: - добавлены `plans/README.md`, living plan Модуля 1, `START_HERE.md` и канонический ноутбук `01_environment_and_smoke_test.ipynb`, а `cluster_smoke.py` расширен до reusable helper и CLI smoke test. - уточнены onboarding-материалы и окружение: добавлены Spark UI в `README.md`, ресурсы хоста и креды MinIO в `START_HERE.md`, использован `NB_GID` в `jupyter/Dockerfile`, в ноутбуке усилены самостоятельные задания и добавлены `cell id`, а пояснения в `cluster_smoke.py` переведены на русский для студентов. - обновлены `README.md`, `AGENTS.md` и archive howto, удалены устаревшие `spark-basic-test.ipynb` и `03_partitioning_and_schema_evolution.ipynb`. - Проверка: - `python3 -m py_compile src/spark/cluster_smoke.py src/spark/__init__.py`. - `docker compose build spark-master` и `docker compose build jupyter`. - `docker compose up -d`, `docker compose exec jupyter python3 -c "from spark.cluster_smoke import create_spark_session, run_cluster_smoke; spark=create_spark_session(app_name='module-01-validation'); print(run_cluster_smoke(spark)); spark.stop()"` и `docker compose exec jupyter jupyter nbconvert --to notebook --execute /opt/work/01_environment_and_smoke_test.ipynb --output-dir /tmp --output module1-validation-2.ipynb`.
68 lines
4.7 KiB
Markdown
68 lines
4.7 KiB
Markdown
# Модуль 1. Вход в стенд и базовая диагностика
|
||
|
||
**Статус:** `Ready for validation`
|
||
**Последнее обновление:** `2026-03-06`
|
||
|
||
## Цель
|
||
|
||
Дать студенту безопасный и воспроизводимый вход в курс: он должен сам поднять локальный стенд, открыть основные веб-интерфейсы, выполнить Spark smoke test и понять первый маршрут диагностики проблем.
|
||
|
||
## Результат для студента
|
||
|
||
После прохождения модуля студент:
|
||
|
||
- поднимает стенд командами `docker compose build` и `docker compose up -d`;
|
||
- проверяет состояние контейнеров через `docker compose ps`;
|
||
- открывает `Spark UI`, `MinIO Console`, `Trino UI` и `JupyterLab`;
|
||
- запускает smoke test Spark-кластера и понимает, что именно он проверяет;
|
||
- знает, куда смотреть при первичной диагностике через логи и UI.
|
||
|
||
## Deliverables
|
||
|
||
- `plans/README.md` как индекс всех рабочих планов;
|
||
- `START_HERE.md` как канонический вход в курс до первого ноутбука;
|
||
- `notebooks/01_environment_and_smoke_test.ipynb` как канонический ноутбук Модуля 1;
|
||
- `src/spark/cluster_smoke.py` как общий helper и CLI smoke test;
|
||
- обновлённые ссылки и инструкции в `README.md` и `AGENTS.md`.
|
||
|
||
## План работ
|
||
|
||
1. Создать каталог `plans/` и зафиксировать в нём правила хранения и индекс.
|
||
2. Подготовить `START_HERE.md` с prerequisites, запуском, проверкой сервисов, входом в Jupyter и reset/restart шагами.
|
||
3. Расширить `src/spark/cluster_smoke.py` до reusable helper с функцией `run_cluster_smoke(spark) -> dict` и CLI `main()`.
|
||
4. Собрать `notebooks/01_environment_and_smoke_test.ipynb` по схеме `объяснение -> демонстрация -> самостоятельное повторение -> checkpoint`.
|
||
5. Перенести полезное содержимое из старого `spark-basic-test.ipynb` в новый ноутбук и убрать старый артефакт из активного маршрута.
|
||
6. Обновить `README.md` и `AGENTS.md`, чтобы новый вход и новый ноутбук стали каноническими.
|
||
7. Прогнать валидацию: smoke script должен проходить синтаксическую проверку, а ноутбук должен быть валидным `ipynb`.
|
||
|
||
## Checkpoint
|
||
|
||
Студент должен уметь:
|
||
|
||
- показать результат `docker compose ps`;
|
||
- открыть `Spark UI`, `MinIO Console`, `Trino UI` и `JupyterLab`;
|
||
- выполнить smoke test и объяснить, что он подтвердил;
|
||
- назвать роли `MinIO`, `PostgreSQL`, `Spark`, `Trino` и `Jupyter`;
|
||
- описать первый шаг диагностики, если не поднимается `trino` или `spark-master`.
|
||
|
||
## Acceptance Criteria
|
||
|
||
- `START_HERE.md` позволяет поднять стенд с нуля без обращения к `docs/archive/legacy_howto.md`;
|
||
- `notebooks/01_environment_and_smoke_test.ipynb` можно выполнить сверху вниз в поднятом Jupyter-окружении;
|
||
- один и тот же smoke helper используется из CLI и из ноутбука;
|
||
- в репозитории остаётся один канонический вход в Модуль 1;
|
||
- `plans/README.md` позволяет быстро найти модульный план и понять его статус.
|
||
|
||
## Риски
|
||
|
||
- Старые ссылки на `spark-basic-test.ipynb` могут остаться в инструкциях и создавать путаницу.
|
||
- Если smoke test будет слишком сложным, он перестанет быть быстрым диагностическим шагом.
|
||
- Если в ноутбуке окажутся host-level команды, студент может ошибочно пытаться запускать `docker compose` внутри Jupyter.
|
||
|
||
## Out of Scope
|
||
|
||
- загрузка raw-данных;
|
||
- разбор internals `Iceberg`;
|
||
- запросы к `Trino` как отдельная практика;
|
||
- `schema evolution`, `time travel`, `compaction`, `vacuum`.
|