clickstream-data-platform/docs/adr/0007-clickhouse-access.md

ADR 0007. Доступ к ClickHouse: пользователи файлом, доверие нод секретом

Дата: 9 августа 2026 года. Статус: принято; роль monitoring_reader и пользователь grafana добавлены 21 августа 2026 года (#114).

Решение

У кластера шесть пользователей и пять ролей.

• default — с паролем, только служебный: проверки здоровья нод и работа изнутри контейнеров. Приложения им не ходят.
• etl с ролью etl_writer — чтение и запись во всех слоях. Им ходит Airflow и применяется DDL при подъёме стенда.
• bi с ролью bi_reader — чтение витрин DM, слоя DDS и справочников dic. Им ходит Superset.
• analyst с ролью analyst_reader — чтение всех слоёв и справочников. Им человек подключается снаружи, из своего клиента.
• grafana с ролью monitoring_reader — чтение слоёв, таблиц базы dic и системных таблиц, CLUSTER и REMOTE. Им ходит Grafana, и больше никто.
• dict с ролью dict_reader — чтение одной базы dic, пароля нет. Им словарь читает свою подложку, и больше он никем не используется (ADR 0012).

Роль здесь шире прав на слои: образ ClickHouse требует отдельного разрешения на запросы ON CLUSTER, на чтение системных таблиц и на каждый движок внешнего источника. Без права на системные таблицы клиент вовсе не открывает соединение.

Пользователи, роли и права объявлены файлами настройки сервера, а не запросами SQL. Файл монтируется на обе ноды и лежит в git. Пароли живут в .env и попадают в настройку подстановкой по имени переменной; значения собраны по конвенции «слово-число-слово», потому что пароль analyst человек набирает руками.

Ноды доверяют друг другу по общему секрету, объявленному в описании кластера. Учётные данные по репликам не расписываются.

Сетевых ограничений на default нет: порты стенда и так открыты только на 127.0.0.1, а внутри сети Compose дверь заперта паролем.

Устройство модели — кто каким пользователем ходит и где живут пароли — опишет раздел README «Состав и доступ»; здесь только решение и доводы. Отдельного справочника по доступу в docs/architecture/ не заводим: своего содержания сверх этих двух документов у него сегодня нет, а дом ему понадобится, когда появятся слои DDS и DM и гранты размножатся. Абзац README «У локального учебного кластера нет пароля» этим решением отменяется.

Почему

Стенд учит не администрированию доступа, а чтению отказа в правах: человек должен узнать в бою картину, которую видел здесь, и понимать, чего просить. Отсюда критерий отбора — модель должна читаться из текста ошибки, а не из описания. Поэтому пользователей мало, имена у них говорящие, а границы проходят там, где их обычно проводят в компаниях: bi видит витрины и слой DDS под ними, потому что так чаще всего и бывает; заодно расхождение витрины со слоем ниже остаётся проверяемым одним и тем же пользователем. Справочники видны всем читателям и никому на запись: зона входит в хранилище сбоку, и её содержимым владеет файл репозитория, а не слой.

Беспарольный dict. Пароль пришлось бы вписать в текст DDL словаря, то есть положить секрет в git. Ходить этой учёткой некуда: право у неё одно — SELECT на dic, и хост источника локальный.

Своя роль дашбордам. Панели мониторинга живут не на витринах, а на system.query_log, частях MergeTree и очереди распределённых DDL — и читают их через clusterAllReplicas, потому что системные таблицы у каждой ноды свои (ADR 0002). Для этого нужны SELECT на system.* и REMOTE; контракт роли также включает CLUSTER для запросов ON CLUSTER. Такого набора не было ни у одного читателя: у обеих читающих ролей из системных таблиц только system.settings. Догрузить недостающее в analyst_reader отвергнуто: аналитик получил бы системные таблицы и REMOTE заодно, а в system.query_log запросы Grafana стали бы неотличимы от человеческих — ровно там, где дашборд «Запросы» и должен их различать. Пускать Grafana под etl отвергнуто сразу: читатель не получает права писать. Осталась своя роль по здешней общей схеме — у каждого потребителя она своя.

Секрет, а не учётные данные по репликам. У каждой реплики в описании кластера своя учётка — вписанная явно или подразумеваемая, и тогда это беспарольный default. Подключение к соседней ноде идёт от неё, а не от того, кто задал вопрос. Значит, стоит default получить пароль — и без правки описания кластера межнодовые запросы встают. Починить это можно двумя способами, и они различаются не удобством. С учётными данными по репликам вся межшардовая работа идёт от одной общей учётки: на своей ноде права применяются, на соседней — нет. Ролевая модель тогда наполовину декорация, а это хуже её отсутствия: она утверждает разграничение, которого не существует. Общий секрет передаёт на соседа личность инициатора, стоит одной строки в описании кластера и не размножает пароль по репликам. Шифрование тут ни при чём; в соседнем clickhouse-learning-cluster выбран как раз путь с учётными данными по репликам, и там пароль вписан в каждую реплику каждого из трёх кластеров.

Довод подтверждён замером 13 августа 2026 года: на соседнем шарде сохранился пользователь-инициатор, поэтому там применились его права. Результат замера — в разделе «Что проверено».

Файлы, а не SQL. Объявленное файлом не оставляет состояния в томах: источник истины — файл в git. Стенд считает access.xml и переданные через .env значения настройкой при создании контейнера; отдельного способа применять их на живом стенде нет, потому что уроки не меняют базовую модель доступа. Порядок применения изменений — в разделе README «Состав и доступ». Оба варианта с SQL — локальное хранилище доступа с ON CLUSTER и реплицированное в keeper — делают пользователей состоянием тома: .env на них больше не влияет, и появляется расхождение того же сорта, которое README уже описывает для Postgres и Grafana. Цена выбора известна: объявленных файлом пользователей нельзя менять запросами. Она принята как упрощение — сломать модель случайно труднее.

Что ещё отвергнуто. Оставить всё на беспарольном default — цена нулевая, но и рассказать по итогам нечего. Раздать всем пароль без ролей — дёшево и показывает ровно тот антипаттерн, за который ругают в бою: все под одним админом. Вынести доступ в лекцию, как репликационную эксплуатацию, — довод «отдельный операционный домен» здесь не работает: у репликации это живые процессы, учения и runbook, а тут несколько десятков строк настройки и ноль эксплуатации. Запереть default ещё и по сети — второй замок на ту же дверь.

Отложено явно: TLS и защищённые межсерверные соединения, настоящее хранилище секретов, внешние поставщики учётных записей, квоты и профили под пользователя, политики строк, аудит запросов.

Следствия

До появления слоёв DDS и DM читать bi почти нечего, и это намеренно. Дашборды рисуются поверх модели данных, а не поверх типизированных событий, поэтому доступ Superset к ODS не планировался и правами не выдаётся. Единственное, что ему доступно сегодня, — справочники: с ними зона dic пришла раньше своих потребителей.

Владелец матвью приёма определяется тем, кто применил DDL. Весь DDL стенда идёт через IF NOT EXISTS, поэтому на существующих томах три матвью сохранят нынешнего владельца, а на собранном заново стенде им станет etl. Работают оба — права есть у обоих, — но два стенда в этом расходятся.

Лаба «сломать права» вариантом с файлами не закрывается: создать через SQL новую роль и нового пользователя ничто не мешает, и новую роль разрешено выдавать даже пользователю, объявленному файлом. Недоступно обратное — править объявленных файлом. Всё, что лаба создаст, живёт в томе и убирается make clean.

Что проверено

Сверено 9 августа 2026 года по документации ClickHouse через MCP Context7 и на живом стенде 26.3.17.56.

• В system.clusters у каждой реплики своя колонка user; на стенде там default. Отсюда весь довод про общий секрет.
• Секрет кластера аутентифицирует серверы хешем от соли, нонса, секрета и запроса и позволяет назначить пользователя, от которого запрос выполняется на соседней ноде.
• Роли и права объявляются в файле настройки пользователей наравне с самими пользователями; SQL-хранилище доступа для этого не требуется.
• Хранилище пользователей из файла — только для чтения: попытка изменить такого пользователя запросом даёт ACCESS_STORAGE_READONLY.
• Роль, созданную через SQL, разрешено выдавать пользователю из файла — отдельное улучшение ClickHouse 2025 года, в 26.3 оно есть.
• Подстановка значений из переменных окружения — общий механизм файлов настройки ClickHouse.
• Весь DDL репозитория идёт через IF NOT EXISTS (файлы sql/ddl/).

Права роли monitoring_reader сверены 21 августа 2026 года по документации ClickHouse через MCP Context7 (#114).

• Системные таблицы выдаются обычным SELECT: в документации это GRANT SELECT ON system.query_log, значит SELECT ON system.* и есть «все системные таблицы». Отдельного права на них нет.
• GRANT CLUSTER ON *.* — документированная форма права на запросы ON CLUSTER; текущий запрос clusterAllReplicas его не использует.
• clusterAllReplicas документация держит в одном ряду с remote, remoteSecure и cluster: это табличная функция, которая берёт имя кластера из remote_servers и идёт на каждую его реплику. Отсюда REMOTE — без права на удалённое обращение запрос дальше своей ноды не пойдёт, а панели ADR 0002 читают system.* именно так.

Набор проверен на живом стенде 21 августа 2026 года (#114): пользователь grafana из Grafana выполнил SELECT count() AS replicas FROM clusterAllReplicas('clickstream_cluster', system.one) и получил 2 — прав хватает, чтобы прочесть системную таблицу с обеих нод.

Проверено на живом стенде 13 августа 2026 года, ClickHouse 26.3.17.56.

• Секрет кластера принимается внутри remote_servers в виде <secret from_env="CLICKHOUSE_CLUSTER_SECRET"/>. Запрос от etl через обе ноды выполнился на каждой под пользователем etl.
• from_env работает у элемента password: etl, bi и analyst вошли с паролями из окружения и получили свои роли.
• При запросе от bi через Distributed на второй ноде system.query_log показал user = bi и initial_user = bi. Значит, на соседнем шарде применяются права инициатора, а не общей учётной записи.
• Права на отсутствующие базы dds и dm приняты. До создания баз они видны в SHOW GRANTS FOR etl_writer; временная таблица в dm подтвердила право bi на чтение после появления базы.