Управляемый сервис ClickHouse

ClickHouse — высокопроизводительная колоночная система управления базами данных (СУБД) с открытым исходным кодом и поддержкой SQL. Она используется для оперативной аналитической обработки (OLAP).

Оркестрация резервного копирования

Чарт поддерживает два варианта резервного копирования; для каждого Helm-релиза выберите один из них.

Рекомендуемый вариант: BackupClass + Plan со стратегией Altinity

Стратегия Altinity уровня кластера (strategy.backups.cozystack.io/v1alpha1) запускает утилиту Altinity clickhouse-backup в отдельном разовом задании batch/v1.Job для каждого BackupJob / RestoreJob. Она учитывает особенности движка (FREEZE + выгрузка), поддерживает как восстановление на месте, так и восстановление в копию с targetApplicationRef, и не требует встроенного в чарт CronJob.

Настройка каждого Helm-релиза:

  1. Задайте backup.enabled: true, а также поля s3* (или s3CredentialsSecret.name) в значениях чарта. Чарт создает Secret с именем <release>-backup-s3, содержащий параметры подключения к бакету и учетные данные. Этот Secret используется создаваемым чартом sidecar-контейнером clickhouse-backup (он добавляется в под ClickHouseInstallation с помощью templates/clickhouse.yaml); сам под стратегии представляет собой клиент curl/jq, который обращается к HTTP API sidecar-контейнера на порту 7171 и никогда не считывает Secret напрямую.
  2. Администратор кластера однократно устанавливает стратегию Altinity и BackupClass, который связывает apps.cozystack.io/ClickHouse с этой стратегией (см. examples/backups/clickhouse/01-create-strategy.sh и 02-create-backupclass.sh).
  3. Tenant создает Plan (расписание cron) или отправляет разовый BackupJob, ссылающийся на BackupClass. Восстановление выполняется с помощью RestoreJob, который ссылается на полученный Backup: не задавайте targetApplicationRef при восстановлении на месте, а для восстановления в копию укажите в нем ссылку на второй экземпляр ClickHouse.

Использование собственного Secret с учетными данными S3

Если задать backup.s3CredentialsSecret.name, чарт не создает <release>-backup-s3, а sidecar-контейнер вместо него использует указанный Secret. Secret должен содержать пять полей S3 в виде отдельных строковых ключей, а не JSON-объекта; по умолчанию используются имена bucketName / endpoint / region / accessKey / secretKey, которые можно переопределить с помощью backup.s3CredentialsSecret.{bucketKey,endpointKey,…}.

Пример:

apiVersion: v1
kind: Secret
metadata:
  name: my-s3-creds
  namespace: tenant-test
type: Opaque
stringData:
  bucketName: my-clickhouse-archive
  endpoint:   https://s3.example.org
  region:     us-east-1
  accessKey:  AKIAIOSFODNN7EXAMPLE
  secretKey:  wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
---
# В values.yaml ClickHouse:
backup:
  enabled: true
  s3CredentialsSecret:
    name: my-s3-creds

Secret приложения Cozystack Bucket (bucket-<name>-<user>) с единственным ключом BucketInfo, содержащим JSON-объект, нельзя напрямую использовать как s3CredentialsSecret. Либо передайте чарту исходные значения через backup.s3* (как это сделано в examples/backups/clickhouse/03-create-bucket.sh: извлеките параметры подключения из BucketInfo и передайте их в значения чарта), либо создайте промежуточный Secret с пятью указанными выше строковыми ключами.

Устаревший вариант: Restic CronJob, создаваемый чартом

Чарт по-прежнему включает CronJob, который для каждой таблицы потоково передает результаты SHOW CREATE TABLE

  • SELECT * FORMAT TabSeparated в репозиторий Restic. Этот вариант сохранен для обратной совместимости; в новых установках используйте описанный выше сценарий с BackupClass.

Чтобы включить этот вариант:

  1. Задайте backup.enabled: true, backup.schedule: "0 2 * * *" (или другое непустое расписание cron), backup.s3* и backup.resticPassword.

  2. Чтобы восстановить данные вручную:

    restic -r s3:s3.example.org/clickhouse-backups/table_name snapshots
    restic -r s3:s3.example.org/clickhouse-backups/table_name restore latest --target /tmp/
    

    Подробнее см. в статье Restic: эффективное резервное копирование из stdin.

Прежние значения backup.schedule, backup.cleanupStrategy и backup.resticPassword объявлены устаревшими и будут удалены после того, как стратегия Altinity станет вариантом по умолчанию во всех эталонных развертываниях. Создаваемый чартом CronJob формируется только при непустом значении backup.schedule.

Параметр storageClass помечен в схеме чарта как неизменяемый. Описание контракта и список компонентов, обеспечивающих его соблюдение, приведены в docs/storage-immutability.md.

Параметры

Общие параметры

ИмяОписаниеТипЗначение
replicasКоличество реплик ClickHouse.int2
shardsКоличество шардов ClickHouse.int1
resourcesЯвная конфигурация CPU и памяти для каждой реплики ClickHouse. Если параметр не задан, применяется пресет, указанный в resourcesPreset.object{}
resources.cpuCPU, доступный каждой реплике.quantity""
resources.memoryПамять (RAM), доступная каждой реплике.quantity""
resourcesPresetПресет ресурсов по умолчанию, используемый, если параметр resources не задан.stringt1.small
sizeРазмер PVC для данных приложения.quantity10Gi
storageClassStorageClass для хранения данных.string""
versionВерсия ClickHouse (major.minor), которую нужно развернуть. Применяется как к образу ClickHouse server, так и к образу ClickHouse Keeper. Понижение версии до более старой мажорной версии небезопасно (ClickHouse не может читать данные, записанные более новым сервером, а снапшоты Keeper несовместимы в обратную сторону) — это значение можно только увеличивать.stringv24.9

Параметры приложения

ИмяОписаниеТипЗначение
logStorageSizeРазмер постоянного тома для журналов.quantity2Gi
logTTLTTL (срок хранения) для query_log и query_thread_log.int15
usersКарта конфигурации пользователей.map[string]object{}
users[name].passwordПароль пользователя.string""
users[name].readonlyДоступ пользователя только для чтения (по умолчанию: false).boolfalse

Параметры резервного копирования

NameDescriptionTypeValue
backupBackup configuration.object{}
backup.enabledEnable backup integration. Materialises the chart-emitted <release>-backup-s3 Secret consumed by the Altinity backup strategy and, when schedule is non-empty, also renders the legacy chart-managed CronJob.boolfalse
backup.useSystemBucketOpt-in: when true, the chart-emitted <release>-backup-s3 Secret is skipped and the clickhouse-backup sidecar reads bucket coordinates + S3 credentials from the platform-projected cozy-backups-creds Secret. S3_PATH is set to <namespace>/<release> for cross-tenant isolation. Use together with the platform cozy-default BackupClass — tenants do not need to fill any s3* field below.boolfalse
backup.s3RegionDEPRECATED. Per-tenant S3 configuration is being phased out in favour of the platform-managed cozy-default BackupClass. Optional now so tenants on useSystemBucket: true can omit it.stringus-east-1
backup.s3BucketDEPRECATED. Optional; see s3Region.strings3.example.org/clickhouse-backups
backup.endpointDEPRECATED. S3 endpoint URL for the legacy chart-emitted sidecar.string""
backup.s3PathOverrideDEPRECATED. Object-key prefix inside the legacy s3Bucket; the new platform flow scopes by namespace automatically.string""
backup.scheduleLegacy. Cron schedule for the chart-emitted CronJob that runs the dump+restic backup. Empty (default) skips the legacy CronJob; recommended when a BackupClass + Plan from backups.cozystack.io already drives backup orchestration via the Altinity strategy.string""
backup.cleanupStrategyLegacy. Restic retention policy passed to the legacy CronJob (restic forget …). Unused by the Altinity strategy.string--keep-last=3 --keep-daily=3 --keep-within-weekly=1m
backup.s3AccessKeyDEPRECATED. Tenants no longer supply S3 keys; the platform-managed Bucket Secret is the source of truth. Optional now so useSystemBucket: true tenants can omit it.string<your-access-key>
backup.s3SecretKeyDEPRECATED. Optional; see s3AccessKey.string<your-secret-key>
backup.resticPasswordLegacy. Password for Restic backup encryption used by the legacy CronJob. Unused by the Altinity strategy.string<password>
backup.s3CredentialsSecretDEPRECATED. Pre-existing Secret reference for the legacy chart-emitted sidecar. The platform flow projects cozy-backups-creds instead.object{}
backup.s3CredentialsSecret.nameName of the Secret in the application namespace. Empty means the chart materialises <release>-backup-s3 from the legacy s3* fields.string""
backup.s3CredentialsSecret.bucketKeyKey in the Secret holding the bucket name. Defaults to bucketName.string""
backup.s3CredentialsSecret.endpointKeyKey in the Secret holding the S3 endpoint URL. Defaults to endpoint.string""
backup.s3CredentialsSecret.regionKeyKey in the Secret holding the S3 region. Defaults to region.string""
backup.s3CredentialsSecret.accessKeyIDKeyKey in the Secret holding the access key ID. Defaults to accessKey.string""
backup.s3CredentialsSecret.secretAccessKeyKeyKey in the Secret holding the secret access key. Defaults to secretKey.string""
backup.endpointCACA bundle the sidecar trusts when the S3 endpoint’s certificate is signed by a private CA (e.g. Cozystack’s in-cluster SeaweedFS). Applies to both the per-tenant and the useSystemBucket flow, and to the clickhouse-backup sidecar only — the legacy schedule CronJob writes to S3 through restic and does not consume it, so a private-CA endpoint combined with schedule still fails TLS. Use the BackupClass flow for such an endpoint.object{}
backup.endpointCA.nameName of the Secret in the application namespace. Empty (default) mounts nothing and leaves the sidecar on the system trust store only.string""
backup.endpointCA.keyKey inside the Secret holding the PEM CA bundle. Defaults to ca.crt.stringca.crt

ClickHouse Keeper parameters

NameDescriptionTypeValue
clickhouseKeeperКонфигурация ClickHouse Keeper.object{}
clickhouseKeeper.enabledРазвернуть ClickHouse Keeper для координации кластера.booltrue
clickhouseKeeper.sizeРазмер PVC для данных приложения.quantity1Gi
clickhouseKeeper.resourcesPresetПресет размера по умолчанию.stringt1.micro
clickhouseKeeper.replicasКоличество реплик Keeper.int3

Примеры параметров и справочник

resources и resourcesPreset

resources sets explicit CPU and memory configurations for each replica. Every resource it leaves unset is taken from the preset defined in resourcesPreset.

resources:
  cpu: 4000m
  memory: 4Gi

resourcesPreset задает именованную конфигурацию ресурсов CPU и памяти для каждой реплики. Этот параметр игнорируется, если задано соответствующее значение resources.

Имя пресетаCPUпамять
nano250m128Mi
micro500m256Mi
small1512Mi
medium11Gi
large22Gi
xlarge44Gi
2xlarge88Gi
Last modified 2026-11-03: translate 1.7 (726310fa)