Managed ClickHouse (Altinity Operator)

Okustera Managed ClickHouse delivers enterprise-grade, high-throughput columnar analytical OLAP (Online Analytical Processing) storage powered by ClickHouse 24.3 and orchestrated by the Altinity ClickHouse Operator (clickhouse.altinity.com/v1).

ClickHouse is a column-oriented database management system designed for real-time analytical reporting, distributed log inspection, time-series telemetry, and LLM observability tracing (such as Langfuse). By storing data by columns rather than rows and leveraging vectorized SIMD CPU execution, ClickHouse processes analytical queries up to 100x to 1,000x faster than traditional row-oriented relational databases.

In Okustera, ClickHouse clusters are provisioned natively as declarative ClickHouseInstallation (CHI) custom resources, backed by distributed Ceph RBD NVMe storage, coordinated by ClickHouse Keeper, and protected with zero-trust internal network boundaries and automated password escrow via OpenStack Barbican KMS.

Architectural Highlights

Key Capabilities

Columnar Vectorized Engine: Reads only the columns requested in the query, achieving compression ratios of $4\times$ to $10\times$ with ZSTD/LZ4 and scanning billions of rows per second per server.
Altinity Operator Orchestration: Automated lifecycle management via ClickHouseInstallation (CHI) custom resources supporting declarative shard scaling, replica provisioning, rolling configuration updates, and automated template propagation.
ClickHouse Keeper Consensus: Lightweight, embedded Raft-based coordination for table replication (ReplicatedMergeTree) and distributed DDL (ON CLUSTER), eliminating the operational complexity of external ZooKeeper clusters.
Ceph NVMe Block Persistence: Data directories (/var/lib/clickhouse) are backed by dedicated Ceph RBD block volumes (block-rbd1 or ceph-rbd), providing high-IOPS NVMe performance and snapshot crash-consistency.
Zero-Trust Private Endpoints: Cluster endpoints are exposed exclusively on private internal Kubernetes ClusterIP networks (:8123 HTTP REST, :9000 Native TCP). Public ingress is eliminated, ensuring analytical data and telemetry never traverse unencrypted public routes.
Barbican KMS Password Escrow: Administrative database passwords are automatically generated, vaulted in OpenStack Barbican KMS (omc-clickhouse-{namespace}-{name}), and synced to tenant Kubernetes Secrets (clickhouse-{name}-auth).
S3 Cold Storage Offload: Seamless integration with Ceph RADOS Gateway (RGW S3) via ClickHouse storage policies for tiered data aging, automatically archiving historical partition parts to object storage.

Provisioning via OMC Portal & REST API

Portal Cloud Console

Navigate to Database Services (DBaaS) in the Okustera Portal.
Select the 📊 ClickHouse OLAP tab or click Create Database Cluster and select ClickHouse 24.3.
Specify your cluster name, tenant namespace, node replicas, and Ceph NVMe storage allocation (default: 10 GiB).
Click Create Database Cluster. The internal HTTP endpoint (http://clickhouse-<name>.<namespace>.svc.cluster.local:8123), Native TCP endpoint (port 9000), and connection URI will be generated with one-click copy and secret visibility toggle.

REST API Example

curl -X POST "https://portal.okustera.com/api/v1/dbaas/clickhouse" \
  -H "Authorization: Bearer ${OKUSTERA_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "telemetry-analytics",
    "namespace": "production",
    "version": "24.3",
    "replicas": 1,
    "storage_size": "20Gi",
    "storage_class": "block-rbd1"
  }'

Response (201 Created):

{
  "id": "telemetry-analytics",
  "name": "telemetry-analytics",
  "namespace": "production",
  "engine": "clickhouse",
  "engine_version": "24.3",
  "status": "Creating",
  "replicas": 1,
  "storage_size": "20Gi",
  "storage_class": "block-rbd1",
  "service_endpoint": "http://clickhouse-telemetry-analytics.production.svc.cluster.local:8123",
  "connection_uri": "clickhouse://default:<PASSWORD>@clickhouse-telemetry-analytics.production.svc.cluster.local:9000/default"
}

Declarative Kubernetes Custom Resource (CHI)

For GitOps workflows (ArgoCD / Flux), ClickHouse clusters can be deployed directly via Altinity ClickHouseInstallation manifests:

apiVersion: clickhouse.altinity.com/v1
kind: ClickHouseInstallation
metadata:
  name: telemetry-analytics
  namespace: production
  labels:
    app.kubernetes.io/name: clickhouse
    opencloud.io/engine: clickhouse
spec:
  configuration:
    clusters:
      - name: analytics-cluster
        layout:
          shardsCount: 1
          replicasCount: 1
    users:
      default/networks/ip:
        - "::/0"
        - "0.0.0.0/0"
      default/password: "<CLICKHOUSE_PASSWORD>"
  defaults:
    templates:
      podTemplate: clickhouse-pod
      dataVolumeClaimTemplate: data-volume
  templates:
    podTemplates:
      - name: clickhouse-pod
        spec:
          containers:
            - name: clickhouse
              image: clickhouse/clickhouse-server:24.3
              resources:
                requests:
                  cpu: "250m"
                  memory: "1Gi"
                limits:
                  cpu: "2"
                  memory: "4Gi"
    volumeClaimTemplates:
      - name: data-volume
        spec:
          accessModes:
            - ReadWriteOnce
          storageClassName: block-rbd1
          resources:
            requests:
              storage: 20Gi

Connecting from Python (`clickhouse-connect`)

Applications and data pipelines connect over the high-speed HTTP REST API port (8123) or Native TCP (9000):

import os
import clickhouse_connect

# Connect to ClickHouse via internal ClusterIP service
client = clickhouse_connect.get_client(
    host="clickhouse-telemetry-analytics.production.svc.cluster.local",
    port=8123,
    username="default",
    password=os.environ.get("CLICKHOUSE_PASSWORD"),
    database="default",
)

# Create an analytical events table with MergeTree engine
client.command("""
CREATE TABLE IF NOT EXISTS api_request_events (
    timestamp DateTime64(3, 'UTC'),
    request_id UUID,
    tenant_id LowCardinality(String),
    route LowCardinality(String),
    status_code UInt16,
    duration_ms Float32,
    prompt_tokens UInt32,
    completion_tokens UInt32
) ENGINE = MergeTree()
PARTITION BY toYYYYMM(timestamp)
ORDER BY (tenant_id, route, timestamp)
""")

# High-throughput batch insertion
events_data = [
    [
        "2026-10-04 10:00:00.123",
        "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
        "tenant-alpha",
        "/v1/chat/completions",
        200,
        142.5,
        512,
        128,
    ],
]

client.insert(
    "api_request_events",
    events_data,
    column_names=[
        "timestamp",
        "request_id",
        "tenant_id",
        "route",
        "status_code",
        "duration_ms",
        "prompt_tokens",
        "completion_tokens",
    ],
)

# Run vectorized real-time aggregation
result = client.query("""
SELECT
    tenant_id,
    count() AS total_requests,
    avg(duration_ms) AS p50_duration,
    sum(prompt_tokens + completion_tokens) AS total_tokens
FROM api_request_events
WHERE timestamp >= now() - INTERVAL 1 HOUR
GROUP BY tenant_id
ORDER BY total_tokens DESC
""")

for row in result.result_rows:
    print(f"Tenant: {row[0]} | Requests: {row[1]} | Avg Latency: {row[2]:.2f}ms | Tokens: {row[3]}")

Connecting via cURL / HTTP Query Interface

The ClickHouse HTTP interface enables straightforward queries from scripts and health monitors:

# Query server version and current database
curl -s "http://clickhouse-telemetry-analytics.production.svc.cluster.local:8123/?query=SELECT%20version(),current_database()" \
  -H "X-ClickHouse-User: default" \
  -H "X-ClickHouse-Key: ${CLICKHOUSE_PASSWORD}"

# Execute an arbitrary SQL query returning JSONCompact
curl -s -X POST "http://clickhouse-telemetry-analytics.production.svc.cluster.local:8123/" \
  -H "X-ClickHouse-User: default" \
  -H "X-ClickHouse-Key: ${CLICKHOUSE_PASSWORD}" \
  --data-binary "SELECT count(), avg(duration_ms) FROM api_request_events FORMAT JSONCompact"

Technical Specifications

Parameter	Specification
Engine	ClickHouse Columnar OLAP (`clickhouse/clickhouse-server:24.3`)
Operator	Altinity ClickHouse Operator (`clickhouse.altinity.com/v1` v0.27.4)
Coordination	ClickHouse Keeper (Raft consensus)
Persistence	Ceph RBD Block Volume (`block-rbd1` / `ceph-rbd` StorageClass)
HTTP REST Port	TCP `8123`
Native TCP Port	TCP `9000`
Inter-Server Port	TCP `9009`
Network Exposure	Private `ClusterIP` (Zero-Trust isolated)
Public Ingress	None (internal traffic only)
Authentication	Password vaulted in OpenStack Barbican KMS
Table Engines	`MergeTree`, `ReplicatedMergeTree`, `SummingMergeTree`, `AggregatingMergeTree`
Platform Workloads	LLM Tracing (Langfuse), APISIX API Gateway metrics, audit telemetry

Architectural Highlights​

Key Capabilities​

Provisioning via OMC Portal & REST API​

Portal Cloud Console​

REST API Example​

Declarative Kubernetes Custom Resource (CHI)​

Connecting from Python (clickhouse-connect)​

Connecting via cURL / HTTP Query Interface​

Technical Specifications​