HyperbytedbCluster¶

The HyperbytedbCluster custom resource declares a HyperbyteDB database deployment. The operator reconciles this into a StatefulSet, headless Service, client Service, PVCs, ConfigMaps, and optional monitoring resources.

Quick Start¶

Deploy the operator first, then apply one of the examples below.

Single Node¶

A minimal single-node deployment for development or testing:

kubectl apply -f https://raw.githubusercontent.com/hyperbyte-cloud/hyperbytedb/main/deploy/examples/single-node.yaml

Three-Node Cluster¶

A production-ready cluster with replication, monitoring, and failover. Requires at least 3 worker nodes or a topologySpreadConstraints override.

kubectl apply -f https://raw.githubusercontent.com/hyperbyte-cloud/hyperbytedb/main/deploy/examples/three-node.yaml

High-Availability with Autoscaling¶

A full-featured deployment with sync-quorum replication, autoscaling, and zone-aware scheduling:

apiVersion: hyperbytedb.hyperbyte.cloud/v1alpha1
kind: HyperbytedbCluster
metadata:
  name: hyperbytedb-ha
  namespace: default
spec:
  replicas: 5
  image: hyperbytedb:latest
  version: "0.9.4-beta"
  server:
    port: 8086
    requestTimeoutSecs: 60
    queryTimeoutSecs: 60
  storage:
    volumeClaimTemplate:
      size: 50Gi
      storageClassName: fast-ssd
  flush:
    intervalSecs: 5
  chdb:
    sessionDataPath: /var/lib/hyperbytedb/chdb
  auth:
    enabled: true
    credentialsSecretName: hyperbytedb-auth
  logging:
    level: info
    format: json
  cardinality:
    maxTagValuesPerMeasurement: 100000
    maxMeasurementsPerDatabase: 10000
  statementSummary:
    enabled: true
    maxEntries: 1000
  hintedHandoff:
    enabled: true
    maxHintsPerPeer: 100000
    maxHintAgeSecs: 3600
  rateLimit:
    enabled: true
    maxRequestsPerSecond: 1000
  retention:
    enabled: true
    interval: 5m
  resources:
    requests:
      cpu: "2"
      memory: 4Gi
    limits:
      cpu: "4"
      memory: 8Gi
  cluster:
    heartbeatIntervalSecs: 1
    heartbeatMissThreshold: 3
    replicationMaxRetries: 10
    raftHeartbeatIntervalMs: 200
    raftElectionTimeoutMs: 800
    raftSnapshotThreshold: 500
    replication:
      mode: sync_quorum
      ackTimeoutMs: 5000
      syncQuorum:
        minAcks: majority
  monitoring:
    enabled: true
    serviceMonitor: true
  failover:
    enabled: true
    maxFailoverCount: 2
    failoverTimeoutSecs: 180
  autoscaling:
    enabled: true
    minReplicas: 3
    maxReplicas: 10
    targetCPUUtilizationPercentage: 70
  topologySpreadConstraints:
    - maxSkew: 1
      topologyKey: topology.kubernetes.io/zone
      whenUnsatisfiable: DoNotSchedule
      labelSelector:
        matchLabels:
          app.kubernetes.io/name: hyperbytedb
          app.kubernetes.io/instance: hyperbytedb-ha
  tolerations:
    - key: dedicated
      operator: Equal
      value: hyperbytedb
      effect: NoSchedule

TLS-Enabled Cluster¶

Enable TLS with operator-managed self-signed certificates:

apiVersion: hyperbytedb.hyperbyte.cloud/v1alpha1
kind: HyperbytedbCluster
metadata:
  name: hyperbytedb-tls
  namespace: default
spec:
  replicas: 3
  image: hyperbytedb:latest
  version: "0.9.4-beta"
  server:
    port: 8086
    tls:
      enabled: true
      # Omit secretName to let the operator generate a self-signed certificate.
      # Provide secretName to use a pre-existing TLS Secret:
      # secretName: hyperbytedb-tls-cert
  storage:
    volumeClaimTemplate:
      size: 10Gi
  resources:
    requests:
      cpu: 500m
      memory: 1Gi
    limits:
      cpu: "2"
      memory: 4Gi
  failover:
    enabled: true
  monitoring:
    enabled: true
    serviceMonitor: true

To use cert-manager instead of self-signed certificates:

server:
  tls:
    enabled: true
    certManagerIssuerRef:
      name: letsencrypt-prod
      kind: ClusterIssuer

Spec Reference¶

Top-Level Fields¶

server¶

server.tls¶

storage¶

HyperbyteDB stores WAL, metadata, Raft state, and chDB session data on the per-replica PVC. The operator mounts fixed paths under /var/lib/hyperbytedb/ and writes them into config.toml.

flush¶

chdb¶

Set server.maxConcurrentQueries ≥ the query pool for best overlap. A larger query pool is not always faster: each query also runs threads of its own, and on 3-CPU pods 12 connections were 10-40% slower than 4.

auth¶

With enabled: true (HyperbyteDB 0.9.1-beta and later) the operator:

• creates the Secret if it is missing, and fills in any key it lacks: cluster-token (random), admin-username (admin) and admin-password (random). Values already there are kept, so you can choose the admin password yourself. A Secret it names <cluster>-auth is owned by the cluster and deleted with it; one you name in credentialsSecretName is kept.
• passes the three keys to every pod as HYPERBYTEDB__AUTH__CLUSTER_TOKEN, HYPERBYTEDB__AUTH__ADMIN_USERNAME and HYPERBYTEDB__AUTH__ADMIN_PASSWORD. Each node creates the admin at startup if it is missing.
• sends the token on its own calls (membership, decommission, leader) and in the pods' drain hook.

Read the admin login with kubectl get secret <cluster>-auth -o jsonpath='{.data.admin-password}' | base64 -d. Changing the token in the Secret takes effect as pods restart; restart them all together, since nodes with different tokens cannot talk to each other. Turning auth on for a running cluster rolls its pods once.

logging¶

cardinality¶

statementSummary¶

hintedHandoff¶

rateLimit¶

Per-endpoint token-bucket rate limiting for /write and /query. Each endpoint refills at maxRequestsPerSecond tokens per wall-clock second. See Rate limiting for behavior and tuning.

retention¶

cluster¶

Tuning parameters for multi-replica cluster behavior. These only take effect when replicas > 1.

In cluster mode, the Raft leader compares /internal/sync/manifest responses from peers and triggers sync when needed. See Deep Dive: Clustering.

sharding¶

Experimental series-id range sharding. Omitted fields are left out of config.toml so server defaults apply. Enable only on a new cluster (replicas > 1) before ingest. See Series sharding and Configuration — sharding.

spec:
  replicas: 6
  sharding:
    enabled: true
    replicationFactor: 2
    regionSplitSeries: 5
    regionMaxSeries: 10
    regionMergeSeries: 2
    splitMergeIntervalSecs: 30
    heartbeatIntervalSecs: 10

When enabled is true, validation requires regionMergeSeries < regionSplitSeries < regionMaxSeries (same inequalities as the server).

monitoring¶

autoscaling¶

failover¶

Status¶

The operator maintains a .status subresource with the following fields:

Check cluster status:

kubectl get hyperbytedbcluster hyperbytedb-cluster -o wide

NAME               REPLICAS   READY   PHASE     CLUSTER   AGE
hyperbytedb-cluster   3          3       Running   Healthy   5m

Inspect detailed status:

kubectl get hyperbytedbcluster hyperbytedb-cluster -o jsonpath='{.status}' | jq

Annotations and versions¶

Opt-in behaviour is set with annotations on the HyperbytedbCluster:

Versions. The operator (v0.2.0 and later) works out which HyperbyteDB version each cluster runs (the database-version annotation, else version, else the image tag; if none is a version, the newest it knows) and renders only what that version accepts: HyperbyteDB 0.9 rejects config keys it does not know, and 0.8 silently ignores them. On 0.8.x it writes pool_size only, no [sharding] section, and ignores the evacuate-together and control-listener annotations. The DatabaseVersion status condition says which version was used, where it came from, and what was left out:

kubectl get hyperbytedbcluster my-cluster \
  -o jsonpath='{.status.conditions[?(@.type=="DatabaseVersion")].message}'

The full matrix is in the operator repository's docs/compatibility.md.

Operations¶

Rolling Upgrade¶

Change the version field to trigger a rolling upgrade:

kubectl patch hyperbytedbcluster hyperbytedb-cluster \
  --type merge -p '{"spec":{"version":"1.1.0"}}'

The operator upgrades one pod at a time, waiting for readiness before proceeding. The cluster phase transitions to Upgrading during the process.

Scaling¶

kubectl scale hyperbytedbcluster hyperbytedb-cluster --replicas=5

Or patch the spec directly:

kubectl patch hyperbytedbcluster hyperbytedb-cluster \
  --type merge -p '{"spec":{"replicas":5}}'

Pause Reconciliation¶

kubectl patch hyperbytedbcluster hyperbytedb-cluster \
  --type merge -p '{"spec":{"paused":true}}'

Resume with "paused":false.

See Also¶

• Installation -- Installing the operator
• Backup & Restore -- Automated backups and restores
• Administration -- HyperbyteDB operational guide (monitoring, backups, cluster ops)