Skip to content

feat(clickhouse): GCS backups + clickhouse-backup engine with keyless auth#1

Merged
polera merged 1 commit into
mainfrom
feat/clickhouse-backup-engine
Jun 24, 2026
Merged

feat(clickhouse): GCS backups + clickhouse-backup engine with keyless auth#1
polera merged 1 commit into
mainfrom
feat/clickhouse-backup-engine

Conversation

@polera

@polera polera commented Jun 24, 2026

Copy link
Copy Markdown
Owner

Summary

Extends the chart's backup support in two ways:

  • GCS as a native destination (backup.destination.type=gcs) — uses ClickHouse's BACKUP … TO S3() against the GCS S3-interop endpoint with HMAC credentials.
  • Opt-in Altinity clickhouse-backup engine (backup.engine=clickhouse-backup) — runs as a sidecar in the server pods (it needs file access to /var/lib/clickhouse) and is triggered over its REST API by a CronJob.

The native engine remains the default; existing values are unchanged. Chart version 0.1.00.3.0.

Why the new engine

The native engine's object-store auth is HMAC-only. For GCS that means the S3-interop endpoint, which cannot use GKE Workload Identity. The clickhouse-backup engine speaks native cloud SDKs, enabling keyless auth:

Remote Keyless mode How
S3 EKS IRSA s3.auth=iam + serviceAccount.annotations role-arn
GCS GKE Workload Identity gcs.auth=workloadIdentity + saEmail + SA annotation

Static keys are still supported (s3.auth=keys / gcs.auth=key, inline or via existingSecret).

Behavior

  • Sidecar runs clickhouse-backup server (REST API on :7171, basic-auth reusing the admin credential).
  • CronJob on backup.schedule calls create_remote against each shard's lead replica (full multi-shard), plus optional schema-only on the other replicas (schemaOnlyOtherReplicas). It polls /backup/status and fails the Job on error.
  • Sidecar image pinned to altinity/clickhouse-backup:2.7.2-fips (overridable).
  • Restore is documented (manual via the sidecar API/exec) — not automated in this PR.

Files

  • values.yaml / values.schema.jsonbackup.engine + backup.clickhouseBackup config block.
  • templates/_helpers.tplchbEnabled, chbSecretName, shared chbEnv.
  • templates/statefulset-server.yaml — sidecar container.
  • templates/service.yaml — API port on the headless service.
  • templates/cronjob-backup-chb.yaml (new) — trigger CronJob.
  • templates/cronjob-backup.yaml / secret-backup.yaml — guarded/branched by engine.
  • README.md, Chart.yaml.

Testing

  • helm lint passes.
  • Native engine renders unchanged — no sidecar, no chb CronJob (regression clean).
  • All five engine/auth permutations render correctly (keys vs keyless emit the right env and secret-or-none).
  • Multi-shard 2×N targets the correct pod ordinals (data on leads, schema-only on others).
  • Rendered manifests validated as YAML across cases.

🤖 Generated with Claude Code

…less auth

Adds two backup capabilities to the chart:

- GCS as a native backup destination (backup.destination.type=gcs), using
  ClickHouse's BACKUP ... TO S3() against the GCS S3-interop endpoint with
  HMAC credentials.

- An opt-in Altinity clickhouse-backup engine (backup.engine=clickhouse-backup)
  that runs as a sidecar in the server pods and is driven over its REST API by
  a CronJob. Unlike the native engine it supports keyless cloud auth — EKS IRSA
  for S3 and GKE Workload Identity for GCS (the only way to reach GCS keyless,
  since the native S3-interop path is HMAC-only) — plus static keys. Full
  multi-shard coverage: data backup from each shard's lead replica, optional
  schema-only on the others. Image pinned to altinity/clickhouse-backup:2.7.2-fips.

The native engine remains the default; existing values are unchanged.
Bumps chart version 0.1.0 -> 0.3.0.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
@polera polera merged commit d714e32 into main Jun 24, 2026
1 check passed
@polera polera deleted the feat/clickhouse-backup-engine branch June 24, 2026 02:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant