diff --git a/content/documentation/admin/architecture/functional-architecture.ru.md b/content/documentation/admin/architecture/functional-architecture.ru.md index 07877af2..d3830e1e 100644 --- a/content/documentation/admin/architecture/functional-architecture.ru.md +++ b/content/documentation/admin/architecture/functional-architecture.ru.md @@ -39,6 +39,7 @@ DDP Backend — это серверная часть платформы, реа * Выполняет валидацию токенов доступа локально, используя кэшированные ключи подписи. * Подключается к Redis для координации очереди задач. * Подключается к PostgreSQL для хранения и управления данными. +* Подключается к ClickHouse, если он настроен, для чтения хранящихся в нём данных. ### DDP Worker @@ -56,6 +57,7 @@ DDP Worker — это компонент для выполнения фонов * Использует Redis Streams для получения задач из очередей. * Подключается к PostgreSQL для чтения и обновления данных. * Интегрируется с внешними инфраструктурными сервисами для выполнения операций. +* Переносит данные из PostgreSQL в ClickHouse, если он настроен. ### Dex @@ -104,6 +106,24 @@ PostgreSQL — это основная реляционная база данн PostgreSQL может быть установлен в составе модуля DDP для тестовых и демонстрационных целей. В промышленной эксплуатации рекомендуется использование выделенных инстансов PostgreSQL. {{< /alert >}} +### ClickHouse + +ClickHouse — это хранилище для больших объёмов данных, например истории изменений свойств сущностей. + +{{< alert level="info" >}} +ClickHouse подключается опционально: он может быть установлен в составе модуля DDP либо подключён как внешний инстанс. Без него платформа работает, но зависящие от него возможности недоступны: например, не сохраняется история изменений свойств сущностей. Подробнее — в разделе [«ClickHouse»](../../install/#clickhouse). +{{< /alert >}} + +Основные функции: + +* Хранение больших объёмов записей. +* Обслуживание запросов на выборку из этих данных. + +Технические характеристики: + +* Наполняется DDP Worker, который переносит в него данные из PostgreSQL. +* Принимает подключения DDP Backend и DDP Worker по нативному протоколу ClickHouse. + ## Описание сетевых взаимодействий ![traffic-flows](../images/functional-architecture/ddp-architecture-diagram-traffic-flows.png) @@ -121,6 +141,8 @@ PostgreSQL может быть установлен в составе модул * DDP Backend ↔ PostgreSQL (TCP/5432): Backend выполняет операции чтения и записи постоянных данных. * DDP Worker ↔ Redis (TCP/6379): Worker получает задачи из очередей Redis Streams и использует распределенные блокировки. * DDP Worker ↔ PostgreSQL (TCP/5432): Worker обновляет данные в базе после выполнения задач. +* DDP Backend ↔ ClickHouse (TCP/9000, опционально): Backend читает данные, которые хранятся в ClickHouse. +* DDP Worker ↔ ClickHouse (TCP/9000, опционально): Worker переносит в ClickHouse данные из PostgreSQL и удаляет из него данные объектов, которые в платформе уже удалены. ### Интеграция с внешними сервисами diff --git a/content/documentation/admin/architecture/workers.ru.md b/content/documentation/admin/architecture/workers.ru.md index 194240a8..484b468e 100644 --- a/content/documentation/admin/architecture/workers.ru.md +++ b/content/documentation/admin/architecture/workers.ru.md @@ -83,6 +83,19 @@ export WORKER_MAX_TASKS=15 - Возможность отслеживания прогресса выполнения. - Стабильность работы интерфейса. +## Фоновые операции с данными в ClickHouse + +Если подключён [ClickHouse](../../install/#clickhouse), воркеры дополнительно переносят в него данные из PostgreSQL и убирают лишнее. Так, например, обслуживается [история изменений свойств сущностей](../../../user/catalog/#история-свойств): + +- перенос новых записей об изменениях из PostgreSQL в ClickHouse; +- перестроение индексов очереди в PostgreSQL после переноса большого объёма изменений; +- удаление истории сущностей и свойств, которых больше нет; +- удаление истории, вышедшей за срок хранения. + +Эти операции не берутся из очереди задач: каждый воркер запускает их сам, а от одновременного выполнения в нескольких репликах они защищены распределённой блокировкой. Если ни один воркер не запущен, изменения свойств продолжают записываться в PostgreSQL и остаются видимыми в интерфейсе, но очередь на перенос не разбирается и растёт. + +Параметры переноса задаются в секции `clickhouse.replication` настроек модуля: размер и периодичность переноса, перестроение индексов. [Срок хранения истории](../../../user/catalog/#хранение-истории) и периодичность очистки — в секции `clickhouse.propertyHistory`. + ## Масштабирование При необходимости увеличения производительности системы можно: diff --git a/content/documentation/admin/install.ru.md b/content/documentation/admin/install.ru.md index 0e5f7977..70a1a027 100644 --- a/content/documentation/admin/install.ru.md +++ b/content/documentation/admin/install.ru.md @@ -5,6 +5,8 @@ weight: 11 Deckhouse Development Platform (DDP) можно установить двумя способами: с [внешними инстансами](#установка-с-внешними-инстансами) PostgreSQL и Redis (подключение к уже развёрнутым базам данных вне кластера) или с [внутренними инстансами](#установка-с-внутренними-инстансами) (развёртывание PostgreSQL и Redis внутри кластера). Внешние инстансы рекомендуются для production, внутренние подходят для тестов и пилотной эксплуатации. +Дополнительно платформа может использовать [ClickHouse](#clickhouse) — хранилище для больших объёмов данных. По умолчанию он отключён. + ## Установка с внутренними инстансами Для установки DDP включите модуль `development-platform` в вашем кластере Kubernetes под управлением Deckhouse Kubernetes Platform. Для этого можно использовать [ModuleConfig](/products/kubernetes-platform/documentation/v1/reference/api/cr.html#moduleconfig) с минимальным количеством настроек: @@ -151,3 +153,68 @@ spec: database: "0" password: secure_redis_password ``` + +## ClickHouse + +ClickHouse — хранилище для больших объёмов данных, например [истории изменений свойств сущностей](../../user/catalog/#история-свойств). По умолчанию ClickHouse не развёртывается и не подключается — платформа работает без него, но зависящие от него возможности остаются недоступными. + +ClickHouse можно развернуть внутри кластера в составе модуля либо подключить внешний инстанс. Для промышленной эксплуатации используйте внешний инстанс. + +### Внутренний инстанс ClickHouse + +Для развёртывания ClickHouse внутри кластера укажите `mode: internal` и не задавайте параметр `host`: + +```yaml +apiVersion: deckhouse.io/v1alpha1 +kind: ModuleConfig +metadata: + name: development-platform +spec: + enabled: true + version: 1 + settings: + rbac: + superAdminEmail: admin@deckhouse.io + security: + secretKey: "16charssecretkey" + clickhouse: + mode: internal + database: ddp # Название базы данных, создаётся при первом запуске сервера. + username: default # Имя пользователя для подключения. + password: clickhouse_password # Пароль, с которым создаётся сервер в кластере. + image: registry.example.com/clickhouse/clickhouse-server:24.3 # (опционально) образ из приватного registry. +``` + +В этом режиме платформа разворачивает один экземпляр ClickHouse с постоянным хранилищем (PersistentVolumeClaim размером `10Gi`) и сама создаёт базу данных при первом запуске. + +### Внешний инстанс ClickHouse + +Для использования внешнего инстанса ClickHouse укажите `mode: external` и параметры подключения: + +```yaml +apiVersion: deckhouse.io/v1alpha1 +kind: ModuleConfig +metadata: + name: development-platform +spec: + enabled: true + version: 1 + settings: + rbac: + superAdminEmail: admin@deckhouse.io + security: + secretKey: "16charssecretkey" + clickhouse: + mode: external + host: clickhouse.example.com # Имя хоста или IP-адрес сервера ClickHouse. + port: 9000 # Порт нативного протокола ClickHouse (по умолчанию 9000). + database: ddp # Название базы данных. + username: ddp_user # Имя пользователя для подключения. + password: secure_password # Пароль для подключения. +``` + +{{< alert level="warning" >}} +Создайте базу данных до подключения внешнего инстанса: платформа применяет миграции схемы, но саму базу данных не создаёт. +{{< /alert >}} + +Доставку данных из PostgreSQL в ClickHouse и последующую очистку выполняют воркеры платформы, поэтому для переноса данных нужен хотя бы один запущенный воркер. Параметры доставки задаются в секции `clickhouse.replication`, [срок хранения истории свойств](../../user/catalog/#хранение-истории) и периодичность очистки — в секции `clickhouse.propertyHistory`; значения по умолчанию подходят для большинства установок. Подробнее о воркерах — в разделе [«Воркеры»](../architecture/workers/). diff --git a/content/documentation/release-notes/v1.7.0.ru.md b/content/documentation/release-notes/v1.7.0.ru.md new file mode 100644 index 00000000..19f798b6 --- /dev/null +++ b/content/documentation/release-notes/v1.7.0.ru.md @@ -0,0 +1,15 @@ +--- +title: v1.7.0 +weight: 890 +description: Заметки о выпуске v1.7.0 — история изменений свойств сущностей и поддержка ClickHouse. +--- + +## Новые возможности + +### Каталог + +Добавлена история изменений свойств сущностей и просмотр «Свойства на момент времени». По умолчанию история хранится не менее 180 дней, срок настраивается. Подробнее — в разделе [«История свойств»](../../user/catalog/#история-свойств). + +### Установка + +Добавлена поддержка ClickHouse: он развёртывается в составе модуля или подключается как внешний инстанс и хранит большие объёмы данных, например историю изменений свойств сущностей. Подробнее — в разделе [«ClickHouse»](../../admin/install/#clickhouse). diff --git a/content/documentation/user/catalog.ru.md b/content/documentation/user/catalog.ru.md index 208b0e40..7e42779e 100644 --- a/content/documentation/user/catalog.ru.md +++ b/content/documentation/user/catalog.ru.md @@ -97,6 +97,7 @@ weight: 30 - «Запуски действий» — содержит список действий, которые запускались для данной сущности. - «Запуски процессов» — содержит список процессов, которые запускались для данной сущности. - «События» — содержит список событий, сгенерированных для данной сущности. +- «История свойств» — содержит список изменений свойств сущности. Вкладки с дашбордами из поля «Дополнительные вкладки с дашбордами» в настройках ресурса отображаются на странице сущности рядом со встроенными панелями; порядок вкладок соответствует порядку в настройках ресурса. @@ -115,6 +116,68 @@ weight: 30 Время хранения событий ограничено и может быть настроено через файл конфигурации платформы. +### История свойств + +Платформа сохраняет историю изменений свойств каждой сущности — так в истории называются [параметры](../properties/) сущности. Для каждого изменения фиксируются прежнее и новое значение, источник изменения, дата и пользователь, выполнивший изменение. В отличие от событий, история фиксирует каждое изменение отдельного свойства, а не факт изменения спецификации сущности в целом. + +{{< alert level="info" >}} +Для работы истории свойств платформе требуется ClickHouse. Если ClickHouse не подключён, история не сохраняется, а вкладка «История свойств» и диалог «Свойства на момент времени» остаются пустыми. Подробнее — в разделе [«ClickHouse»](../../admin/install/#clickhouse). +{{< /alert >}} + +Просмотр истории доступен на странице сущности: + +- Вкладка «История свойств» — полный список изменений всех свойств сущности. +- Иконка часов рядом с названием свойства в блоке «Параметры» — история изменений выбранного свойства в отдельном диалоговом окне. +- Кнопка «Свойства на момент времени» в блоке «Параметры» — значения всех свойств сущности на выбранную дату и время. + +#### Таблица истории + +В таблице истории отображаются столбцы «Свойство», «Источник», «Кем изменено» и «Дата изменения», записи отсортированы от новых к старым. Кнопка «Показать изменения» открывает сравнение прежнего и нового значения свойства в формате JSON. + +Столбец «Кем изменено» заполняется, если изменение выполнил пользователь. Для изменений, выполненных без участия пользователя (например, при синхронизации источника данных или обработке вебхука), в столбце отображается «—». + +В столбце «Источник» возможны значения: + +- «Вручную» — изменение пользователем в интерфейсе. +- «Действие» — изменение при выполнении действия. +- «Источник данных» — изменение при синхронизации источника данных. +- «Вебхук» — изменение при обработке вебхука. +- «Система» — автоматическое изменение платформой. + +На вкладке «История свойств» записи можно отфильтровать: + +- по свойству — выберите свойство в списке «Все свойства»; +- по времени изменения — задайте «Начало периода» и «Конец периода». + +Кнопка «Очистить» сбрасывает фильтры. В диалоговом окне с историей одного свойства фильтры не отображаются: записи в нём всегда относятся к выбранному свойству. + +#### Свойства на момент времени + +В диалоге «Свойства на момент времени» выберите «Дату и время» и нажмите «Показать». Таблица покажет значения всех свойств сущности на выбранный момент. + +Свойство не попадёт в таблицу, если на выбранный момент оно ещё не существовало или его значение было удалено. + +Выбрать момент в будущем нельзя. Если на выбранный момент данных нет, отображается сообщение «Нет данных на выбранный момент». + +Если выбранный момент раньше [срока хранения истории](#хранение-истории), таблица покажет состояние на начало сохранившейся истории, а над ней появится сообщение «Показано состояние на <дата>: за более ранний период история не хранится». + +#### Хранение истории + +История свойств хранится не менее 180 дней. Срок задаётся параметром модуля `clickhouse.propertyHistory.retentionDays`; значение `0` отключает удаление по сроку, и тогда история хранится бессрочно. Записи удаляются целыми календарными месяцами, поэтому фактически история хранится на срок до месяца дольше заданного. + +Если на вкладке «История свойств» в фильтре указано «Начало периода» раньше срока хранения, над таблицей появляется сообщение «История за период до <дата> не хранится»: пустой список в этом случае не означает, что свойства не менялись. + +Кроме срока хранения, история не переживает удаление объекта, к которому относится: + +- при удалении сущности удаляется вся история её свойств; +- при удалении свойства из настроек ресурса удаляется история этого свойства у всех сущностей ресурса. + +В обоих случаях историю удаляет фоновая очистка, а не само удаление объекта. + +{{< alert level="info" >}} +Для просмотра истории свойств требуется право на просмотр сущности: глобальное разрешение `read:entities`, разрешение `read:entities` для ресурса или разрешение `read:entity` для сущности. Подробнее о правах доступа — в разделе [«Ролевая модель»](../../admin/security/rbac/). +{{< /alert >}} + ### Избранное Пользователь может добавить любую сущность в избранное. Для этого на странице сущности нажмите на круглую кнопку со всплывающей подсказкой «Добавить в избранное» рядом с названием сущности. Посмотреть добавленные в избранное сущности можно в разделе каталога «Избранное».