Files

T

ddadmin 688c46c68b feat(module-1): доработаны материалы модуля 1 и удалён legacy-ноутбук

- Зачем:
  - нужен воспроизводимый вход в курс и единое место хранения планов по модулям.
- Что:
  - добавлены `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`.

2026-03-07 00:24:40 +03:00

4.7 KiB

Raw Blame History

Модуль 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.

План работ

Создать каталог plans/ и зафиксировать в нём правила хранения и индекс.
Подготовить START_HERE.md с prerequisites, запуском, проверкой сервисов, входом в Jupyter и reset/restart шагами.
Расширить src/spark/cluster_smoke.py до reusable helper с функцией run_cluster_smoke(spark) -> dict и CLI main().
Собрать notebooks/01_environment_and_smoke_test.ipynb по схеме объяснение -> демонстрация -> самостоятельное повторение -> checkpoint.
Перенести полезное содержимое из старого spark-basic-test.ipynb в новый ноутбук и убрать старый артефакт из активного маршрута.
Обновить README.md и AGENTS.md, чтобы новый вход и новый ноутбук стали каноническими.
Прогнать валидацию: 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.

4.7 KiB Raw Blame History Unescape Escape