Deploy ByConity in Kubernetes

This page demonstrates how to deploy a ByConity cluster in your Kubernetes cluster.

Deploy local to try a demo

Prerequisites

• Install and setup kubectl in your local environment
• Install helm in your local environment
• Install kind and Docker
• Check out byconity-deploy code

git clone git@github.com:ByConity/byconity-deploy.git
cd byconity-deploy

Use Kind to configure a local Kubernetes cluster

Warning: kind is not designed for production use. Note for macOS users: you may need to increase the memory available for containers (recommend 6 GB).

This would create a 1-control-plane, 3-worker Kubernetes cluster.

kind create cluster --config examples/kind/kind-byconity.yaml

Test to ensure the local kind cluster is ready:

kubectl cluster-info

Initialize the Byconity demo cluster

# Install with fdb CRD first
helm upgrade --install --create-namespace --namespace byconity -f ./examples/kind/values-kind.yaml byconity ./chart/byconity --set fdb.enabled=false

# Install with fdb cluster
helm upgrade --install --create-namespace --namespace byconity -f ./examples/kind/values-kind.yaml byconity ./chart/byconity

Wait until all the pods are ready.

kubectl -n byconity get po

Let's try it out!

$ kubectl -n byconity exec -it sts/byconity-server -- bash
root@byconity-server-0:/# clickhouse client

172.16.1.1 :)

Delete or stop ByConity from your Kubernetes cluster

helm uninstall --namespace byconity byconity

In case you want to stop it temporarily stop it on your machine

docker stop byconity-cluster-control-plane byconity-cluster-worker byconity-cluster-worker2 byconity-cluster-worker3

Deploy in your self-built Kubernetes

How to deploy or buy a Kubernetes cluster?

You can get information here: Production environment

Prerequisites

• Install and setup kubectl in your local environment
• Install helm in your local environment

Prepare your storage provider

For best TCO with performance, local disks are preferred to be used with ByConity servers and workers.

Storage for ByConity servers and workers is for disk cache only, you can delete them any time.

You may use storage providers like OpenEBS local PV.

Prepare your own helm values files

You may copy from ./chart/byconity/values.yaml and modify some fields like:

• storageClassName

• timezone

• replicas for server/worker

• hdfs storage request

  if you want to use your own existing hdfs cluster please set hdfs.enabled=true you can override the hdfs address configuration in values.yaml

byconity:
  hdfs_address: hdfs://your own hdfs:port
hdfs:
  enabled: false

• fdb configuration

  if you want to use your own fdb. please set fdb.enabled=false and fdb-operator.enabled=false you can refer to values_use_existing_fdb.yaml

byconity:
  hdfs_address: hdfs://byconity-hdfs-namenodes:8020 # can using your own hdfs
  use_existing_fdb: true
  fdb_cluster_file: your fdb-cluster-file content. #byconity_fdb:Is0hBgl6iICdHuspBmhAODmD5WISXKzI@192.168.224.150:4501,192.168.226.83:4501,192.168.228.152:4501
fdb:
  enabled: false
fdb-operator:
  enabled: false

Initialize the Byconity cluster

# Install with fdb CRD first
helm upgrade --install --create-namespace --namespace byconity -f ./your/custom/values.yaml byconity ./chart/byconity --set fdb.enabled=false

# Install with fdb cluster
helm upgrade --install --create-namespace --namespace byconity -f ./your/custom/values.yaml byconity ./chart/byconity

Wait until all the pods are ready.

kubectl -n byconity get po

Let's try it out!

$ kubectl -n byconity exec -it sts/byconity-server -- bash
root@byconity-server-0:/# clickhouse client

172.16.1.1 :)

Test

Run some SQLs to test

CREATE DATABASE IF NOT EXISTS test;
USE test;
DROP TABLE IF EXISTS test.lc;
CREATE TABLE test.lc (b LowCardinality(String)) engine=CnchMergeTree ORDER BY b;
INSERT INTO test.lc SELECT '0123456789' FROM numbers(100000000);
SELECT count(), b FROM test.lc group by b;
DROP TABLE IF EXISTS test.lc;
DROP DATABASE test;

Update your Byconity cluster

Add new virtual warehouses

Assume you want to add 2 virtual warehouses for your users, 5 replicas for my-new-vw-default to read and 2 replicas for my-new-vw-write to write.

Modify your values.yaml

byconity:
  virtualWarehouses:
    ...

    - <<: *defaultWorker
      name: my-new-vw-default
      replicas: 5
    - <<: *defaultWorker
      name: my-new-vw-write
      replicas: 2

Apply your helm release with your new values

helm upgrade --install --create-namespace --namespace byconity -f ./your/custom/values.yaml byconity ./chart/byconity

Run CREATE WAREHOUSE DDL to create logic virtual warehouse in Byconity

CREATE WAREHOUSE IF NOT EXISTS `my-new-vw-default` SETTINGS num_workers = 0, type = 'Read';
CREATE WAREHOUSE IF NOT EXISTS `my-new-vw-write` SETTINGS num_workers = 0, type = 'Write';

Done. Let's create a table and use your new virtual warehouse now!

-- Create a table with SETTINGS cnch_vw_default = 'my-new-vw-default', cnch_vw_write = 'my-new-vw-write'
CREATE DATABASE IF NOT EXISTS test;
CREATE TABLE test.lc2 (b LowCardinality(String)) engine=CnchMergeTree
ORDER BY b
SETTINGS cnch_vw_default = 'my-new-vw-default', cnch_vw_write = 'my-new-vw-write';

-- Check if the table has the new settings
SHOW CREATE TABLE test.lc2;

Scaling up and down the existing VirtualWareHouse

Assuming you have a 'my-new-vw-default' and you want to scale up by adding 2 workers, you can directly update the Kubernetes resource object 'StatefulSet'.

First, use the following command to retrieve the names of all StatefulSet resources in the current Kubernetes cluster:

kubectl get statefulset

Then, locate and open the configuration file, and make the following modifications:

kubectl edit statefulset.apps/my-new-vw-default

Change the configuration from 'replicas: 1' to 'replicas: 2'.

spec:
  podManagementPolicy: OrderedReady
  replicas: 2 #change 1 to 2
  revisionHistoryLimit: 10
  selector:
    matchLabels:
      app.kubernetes.io/instance: byconity
      app.kubernetes.io/name: byconity
      byconity-role: worker
      byconity-vw: vw_default
  serviceName: my-new-vw-default

After updating, you can use 'kubectl' to check that the VirtualWarehouse has been scaled up and now includes 2 workers.

Configure ByConity high availability cluster (optional)

To enable high availability in the ByConity cluster, you need to enable the zookeeper configuration for all components. Please refer to the server.yaml

To enable zookeeper:

partition_by: event_date
flush_interval_milliseconds: 15000
mark_cache_size: 5368709120
zookeeper: {} # enable zookeeper
cnch_config: /etc/byconity/cnch-config.yaml

The official provides a Helm configuration YAML file value_HA_example.yaml for high availability.

Use helm upgrade to update cluster：

helm upgrade --install --create-namespace --namespace byconity -f ./your/custom/values.yaml byconity ./chart/byconity