From a5244f8a0bbcf3b41ecc302f52816a87a2e76d76 Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Tue, 15 Sep 2026 08:36:34 -0400 Subject: [PATCH] docs(spark): simplify session setup explanations --- README.md | 5 ++--- START_HERE.md | 8 ++++++-- docs/stack_reference.md | 13 ++++++++++--- plans/course-roadmap.md | 15 ++++++++++----- spark/spark-defaults.conf | 2 +- src/spark/cluster_smoke.py | 3 +-- 6 files changed, 30 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index b8f4acd..166b9c9 100755 --- a/README.md +++ b/README.md @@ -56,9 +56,8 @@ graph TB | `Trino` | Compute — ad hoc SQL, чтение тех же таблиц | | `JupyterLab` | Точка входа — практические ноутбуки курса | -Ноутбуки создают `SparkSession` с именем приложения, а подключение к -`spark://spark-master:7077` и общие настройки Iceberg/MinIO получают из -`spark/spark-defaults.conf`. +Ноутбуки подключаются к Spark-кластеру с +[готовыми настройками стенда](./docs/stack_reference.md#spark). ## С чего начать diff --git a/START_HERE.md b/START_HERE.md index caf9b21..f4ad300 100644 --- a/START_HERE.md +++ b/START_HERE.md @@ -108,11 +108,15 @@ notebooks/01_environment_and_smoke_test.ipynb - `./src` смонтирован read-only как `/opt/src`; - `./data` смонтирован read-only как `/opt/data`; - `PYTHONPATH=/opt/src`, поэтому helper-скрипты из `src/` доступны для импорта в ноутбуках; -- новое ядро Jupyter читает `spark/spark-defaults.conf`: из него `SparkSession` получает адрес кластера `spark://spark-master:7077` и настройки Iceberg/MinIO; -- повторный запуск ячейки с `getOrCreate()` в том же ядре возвращает существующую сессию; чтобы заново применить стартовые настройки, перезапусти ядро; - первый ноутбук курса: `01_environment_and_smoke_test.ipynb`; - локальный учебный data bundle для Модуля 3 должен быть доступен внутри Jupyter по пути `/opt/data/nyc_taxi`. +Ноутбуки берут адрес кластера из +[`spark/spark-defaults.conf`](./spark/spark-defaults.conf). Если изменил его, +перезапусти ядро и заново создай Spark-сессию. Повторный запуск ячейки с +`getOrCreate()` использует текущую сессию. При перезапуске ядра переменные Python +сбрасываются, а учебные таблицы и файлы сохраняются. + ## Базовая диагностика ### Посмотреть список контейнеров diff --git a/docs/stack_reference.md b/docs/stack_reference.md index c207c7b..a4e8b3a 100644 --- a/docs/stack_reference.md +++ b/docs/stack_reference.md @@ -53,9 +53,16 @@ docker compose down -v - Master UI: `http://localhost:8080` - Worker UI: `http://localhost:8081` и `http://localhost:8082` -- Spark master endpoint внутри сети compose: `spark://spark-master:7077` -- `spark/spark-defaults.conf` задаёт этот endpoint как `spark.master`; новое ядро Jupyter применяет настройку при создании первой `SparkSession`. -- `SparkSession.builder.getOrCreate()` в уже работающем ядре возвращает существующую сессию. Для повторного чтения стартовых настроек нужно перезапустить ядро. +- Адрес Spark master внутри сети Docker Compose: `spark://spark-master:7077` + +Адрес кластера (`spark.master`) и настройки доступа к Iceberg и MinIO заданы в +[`spark/spark-defaults.conf`](../spark/spark-defaults.conf). Docker подключает этот +файл к контейнеру Jupyter как `/opt/spark/conf/spark-defaults.conf`. + +При первом вызове `getOrCreate()` Spark читает настройки и создает сессию. +Повторный вызов использует уже работающую сессию. Если изменил адрес кластера +или настройки в файле, перезапусти ядро ноутбука и снова выполни ячейки +с импортами и созданием сессии. Пример запуска smoke-скрипта: diff --git a/plans/course-roadmap.md b/plans/course-roadmap.md index 47d3e49..2a43ed3 100644 --- a/plans/course-roadmap.md +++ b/plans/course-roadmap.md @@ -1,11 +1,11 @@ # План развития курса «Lakehouse без магии» -Статус: ближайшие доработки определены, реализация впереди. +Статус: исправление подключения Spark готово к проверке; остальные работы запланированы. Последнее обновление: 2026-09-15. Здесь собираем отзывы студентов, выбираем следующие улучшения и объясняем их порядок. Подробные задания, критерии приёмки и актуальный статус исполнения хранятся в [Gitea Issues](https://git.dementev.space/ddmitry/mini-lakehouse-lab/issues). -Текущие рамки курса задаёт [PRD](../docs/course_prd.md), а состав уроков — [программа](../docs/course_program.md). Запись в этом плане означает будущую работу. При реализации изменения сначала обновляем соответствующий канонический документ, затем учебные материалы и ссылки на них. +Текущие рамки курса задаёт [PRD](../docs/course_prd.md), а состав уроков — [программа](../docs/course_program.md). Статус каждой работы указан ниже. При реализации изменения сначала обновляем соответствующий канонический документ, затем учебные материалы и ссылки на них. ## Обратная связь @@ -22,13 +22,18 @@ ### 1. Проверить и исправить создание Spark-сессий -**Статус:** выполнено в задаче #1. +**Статус:** исправление проверено в ветке `1-spark-session-master`, ожидает слияния. **Задача:** [#1 — подключение Spark-сессий в новом ядре](https://git.dementev.space/ddmitry/mini-lakehouse-lab/issues/1). -Проверка в отдельных процессах показала: модуль 1 подключался к кластеру, а модули 2–8 без `spark.master` запускали Spark в `local[*]`. Теперь общий `spark-defaults.conf` задаёт `spark://spark-master:7077`, а helper модуля 1 и остальные ноутбуки используют этот единый источник. +В новых процессах модуль 1 подключался к кластеру, а модули 2–8 запускали Spark +локально (`local[*]`). В исправлении все восемь ноутбуков берут адрес кластера +из `spark/spark-defaults.conf`. -**Результат:** каждый ноутбук подключается к ожидаемому Spark-кластеру после перезапуска ядра. Повторный `getOrCreate()` в том же ядре возвращает существующую сессию; это поведение и источник настроек объяснены в onboarding и техническом reference. Подробные проверки сохранены в задаче #1. +**Проверено:** инициализация каждого ноутбука в отдельном процессе, +вычисление на кластере, повторный `getOrCreate()`, запись и чтение тестовой +Iceberg-таблицы. Перед закрытием #1 нужно опубликовать в задаче результаты +проверок и их ограничения. ### 2. Добавить практику «Как настроен Spark в нашем стенде» diff --git a/spark/spark-defaults.conf b/spark/spark-defaults.conf index da57172..27daf2c 100755 --- a/spark/spark-defaults.conf +++ b/spark/spark-defaults.conf @@ -1,6 +1,6 @@ # spark/spark-defaults.conf -# Все SparkSession из Jupyter подключаются к кластеру по умолчанию +# Адрес Spark-кластера для новых сессий spark.master spark://spark-master:7077 # Включаем Iceberg extensions diff --git a/src/spark/cluster_smoke.py b/src/spark/cluster_smoke.py index 67aa8e5..46a6b4e 100755 --- a/src/spark/cluster_smoke.py +++ b/src/spark/cluster_smoke.py @@ -12,8 +12,7 @@ def create_spark_session( ) -> SparkSession: """Создать SparkSession для проверок окружения в Модуле 1. - Функция специально остаётся минимальной и опирается на смонтированный - в контейнер `spark-defaults.conf` для Spark/Iceberg-конфигурации. + Адрес кластера и настройки Iceberg и MinIO заданы в spark-defaults.conf. """ return SparkSession.builder.appName(app_name).getOrCreate()