From 0dcc874419771d044c248e86f7236c172653d430 Mon Sep 17 00:00:00 2001 From: Dmitry Dementiev Date: Thu, 20 Aug 2026 15:10:13 +0300 Subject: [PATCH] =?UTF-8?q?docs(clickhouse):=20=D1=83=D1=82=D0=BE=D1=87?= =?UTF-8?q?=D0=BD=D0=B5=D0=BD=D0=BE=20=D0=BF=D1=80=D0=B8=D0=BC=D0=B5=D0=BD?= =?UTF-8?q?=D0=B5=D0=BD=D0=B8=D0=B5=20=D0=BD=D0=B0=D1=81=D1=82=D1=80=D0=BE?= =?UTF-8?q?=D0=B5=D0=BA=20=D0=BD=D0=BE=D0=B4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зачем: - перезапуск мог оставить прежнее окружение и старый inode файла, а документы обещали неподдерживаемое живое применение. - Что: - в README записано пересоздание нод с ожиданием их здоровья. - ADR 0007 отделяет решение от процедуры и очищен от устаревших обещаний. - Проверка: - make config-test. - git diff --cached --check. --- README.md | 19 ++++++++++++++----- docs/adr/0007-clickhouse-access.md | 25 ++++++++++++------------- 2 files changed, 26 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 68f5f1d..9bf157d 100644 --- a/README.md +++ b/README.md @@ -291,12 +291,25 @@ uv run --project generator python -m clickstream_generator batch \ - `default` остаётся служебным: им ходят проверки здоровья и скрипты внутри контейнеров, но не приложения. -Решение и его доводы — в [ADR 0007](docs/adr/0007-clickhouse-access.md). +Почему пользователи объявлены файлом, а ноды доверяют общему секрету, — в +[ADR 0007](docs/adr/0007-clickhouse-access.md). Пользователи и роли объявлены в `infra/clickhouse/users.d/access.xml`. Пароли и общий секрет нод живут в `.env` и передаются в конфигурацию через окружение; Superset получает пароль `bi` тем же путём через штатную функцию настройки. Значения для локального стенда есть в `.env.example`. +Изменения значений ClickHouse в `.env` и файлов настройки серверов в +`infra/clickhouse/config.d/` и `infra/clickhouse/users.d/` применяются +пересозданием нод: + +```bash +docker compose up --force-recreate --wait clickhouse-01 clickhouse-02 +``` + +Команда возвращает управление, когда обе ноды снова здоровы; именованные тома +при этом сохраняются. `docker compose restart` оставит прежнее окружение и +может оставить старую версию отдельно смонтированного файла. + Пароли ClickHouse и интерфейсов, пароли Postgres, ключи Airflow и Superset, отсутствие проверки доступа у Kafka и Prometheus — намеренно простые и явно ненастоящие настройки локального учебного стенда. Это не пример настройки @@ -328,10 +341,6 @@ Superset получает пароль `bi` тем же путём через ш [официальным описанием автоматической настройки](https://grafana.com/docs/grafana/latest/administration/provisioning/). Prometheus собирает только встроенные метрики двух серверов и keeper; внешних сборщиков, панелей и правил оповещения пока нет. -После изменения `infra/clickhouse/config.d/prometheus.xml` выполните -`docker compose restart clickhouse-01 clickhouse-02`: обычный `make up` не -перезапускает уже созданные серверы и они продолжают работать со старой -конфигурацией. Airflow закреплён на 3.3.0. Состав обязательных процессов, LocalExecutor, публичный `airflow.sdk`, API здоровья и SimpleAuthManager сверены с diff --git a/docs/adr/0007-clickhouse-access.md b/docs/adr/0007-clickhouse-access.md index f38c67f..337ee60 100644 --- a/docs/adr/0007-clickhouse-access.md +++ b/docs/adr/0007-clickhouse-access.md @@ -1,6 +1,6 @@ # ADR 0007. Доступ к ClickHouse: пользователи файлом, доверие нод секретом -Дата: 9 августа 2026 года. Статус: принято. Реализация — отдельным тикетом. +Дата: 9 августа 2026 года. Статус: принято. ## Решение @@ -21,8 +21,7 @@ Роль здесь шире прав на слои: образ ClickHouse требует отдельного разрешения на запросы `ON CLUSTER`, на чтение системных таблиц и на каждый движок внешнего источника. Без права на системные таблицы клиент вовсе не открывает -соединение. Состав прав каждой роли — работа тикета -реализации. +соединение. Пользователи, роли и права объявлены файлами настройки сервера, а не запросами SQL. Файл монтируется на обе ноды и лежит в git. Пароли живут @@ -79,14 +78,16 @@ DDS под ними, потому что так чаще всего и быва в разделе «Что проверено». **Файлы, а не SQL.** Объявленное файлом не оставляет состояния в томах: -повторный `make up` на живом стенде ничего не сдвигает, правка пароля -применяется перезапуском, источник истины — файл в git. Оба варианта с SQL — -локальное хранилище доступа с `ON CLUSTER` и реплицированное в keeper — -делают пользователей состоянием тома: `.env` на них больше не влияет, и -появляется расхождение того же сорта, которое README уже описывает для -Postgres и Grafana. Цена выбора известна: объявленных файлом пользователей -нельзя менять запросами. Она принята как упрощение — сломать модель случайно -труднее. +источник истины — файл в git. Стенд считает `access.xml` и переданные через +`.env` значения настройкой при создании контейнера; отдельного способа +применять их на живом стенде нет, потому что уроки не меняют базовую модель +доступа. Порядок применения изменений — в разделе README «Состав и доступ». +Оба варианта с SQL — локальное хранилище доступа с `ON CLUSTER` и +реплицированное в keeper — делают пользователей состоянием тома: `.env` на +них больше не влияет, и появляется расхождение того же сорта, которое README +уже описывает для Postgres и Grafana. Цена выбора известна: объявленных файлом +пользователей нельзя менять запросами. Она принята как упрощение — сломать +модель случайно труднее. **Что ещё отвергнуто.** Оставить всё на беспарольном `default` — цена нулевая, но и рассказать по итогам нечего. Раздать всем пароль без @@ -136,8 +137,6 @@ Postgres и Grafana. Цена выбора известна: объявленн такого пользователя запросом даёт `ACCESS_STORAGE_READONLY`. - Роль, созданную через SQL, разрешено выдавать пользователю из файла — отдельное улучшение ClickHouse 2025 года, в 26.3 оно есть. -- Настройку пользователей можно перечитать на живом стенде, в том числе на - всём кластере сразу. - Подстановка значений из переменных окружения — общий механизм файлов настройки ClickHouse. - Весь DDL репозитория идёт через `IF NOT EXISTS` (файлы `sql/ddl/`).