この記事はKubernetes Advent Calendar 2021(2)の23日目の記事です。

あらかじめ検証で使用した環境を示します。

macOS 11.6.1
CPUアーキテクチャ: x86-64

clickhouse-operatorとは

clickhouse-operatorは、Altinityが作成したClickHouseをKubernetesで管理するツールです。
Altinityは英国のデータ分析コンサルを行う会社で、ClickHouseを用いた分析を得意とするほか、ClickHouse自体の開発やAltinity.CloudというClickHouseをAWSやGCPへホスティングを行うサービスも展開しています。
おそらくAltinity.Cloudでも使用されているため、今後もメンテナンスは続いていくツールになると思います。

公式のドキュメントに必要なことは書いてありますが、ちょいちょい動かないところもあります。
本記事では公式をベースに使い方を見ていきたいと思います。kubernetesがわからなくても進められるようコマンドは全て記載します。雰囲気を感じていただければと思います。

clickhouse-operatorのインストール

必要なツールは以下の通りです。()内は検証で使用したバージョン
clickhouse-operatorはドライバ無し(--vm-driver=none)では起動しないので、ここではdockerを使用します。

docker
kubectl(1.23.1)
minikube(1.24.0)

docker以外のインストールは Homebrew を使います。

$ brew update
$ brew install kubectl minikube

インストールが終わったら、minikubeを起動してください。

$ minikube start
😄  Darwin 11.6.1 上の minikube v1.24.0
✨  dockerドライバーが自動的に選択されました。他の選択肢:  hyperkit, ssh
👍  コントロールプレーンのノード minikube を minikube 上で起動しています
🚜  イメージを Pull しています...
💾  Kubernetes v1.22.3 のダウンロードの準備をしています
    > preloaded-images-k8s-v13-v1...: 501.73 MiB / 501.73 MiB  100.00% 40.93 Mi
    > gcr.io/k8s-minikube/kicbase: 355.78 MiB / 355.78 MiB  100.00% 11.90 MiB p
🔥  docker container (CPUs=2, Memory=15963MB) を作成しています...
🐳  Docker 20.10.8 で Kubernetes v1.22.3 を準備しています...
    ▪ 証明書と鍵を作成しています...
    ▪ Control Plane を起動しています...
    ▪ RBAC のルールを設定中です...
🔎  Kubernetes コンポーネントを検証しています...
    ▪ イメージ gcr.io/k8s-minikube/storage-provisioner:v5 を使用しています
🌟  有効なアドオン: storage-provisioner, default-storageclass
🏄  完了しました！ kubectl が「"minikube"」クラスタと「"default"」ネームスペースを使用するよう構成されました

minikubeの起動を確認します。

$ minikube status
minikube
type: Control Plane
host: Running
kubelet: Running
apiserver: Running
kubeconfig: Configured

minikubeを起動の起動が確認できたらclickhouse-operatorをインストールします。インストール方法はドキュメントに従います。

$ kubectl apply -f https://raw.githubusercontent.com/Altinity/clickhouse-operator/master/deploy/operator/clickhouse-operator-install-bundle.yaml
customresourcedefinition.apiextensions.k8s.io/clickhouseinstallations.clickhouse.altinity.com created
customresourcedefinition.apiextensions.k8s.io/clickhouseinstallationtemplates.clickhouse.altinity.com created
customresourcedefinition.apiextensions.k8s.io/clickhouseoperatorconfigurations.clickhouse.altinity.com created
serviceaccount/clickhouse-operator created
clusterrole.rbac.authorization.k8s.io/clickhouse-operator-kube-system created
clusterrolebinding.rbac.authorization.k8s.io/clickhouse-operator-kube-system created
configmap/etc-clickhouse-operator-files created
configmap/etc-clickhouse-operator-confd-files created
configmap/etc-clickhouse-operator-configd-files created
configmap/etc-clickhouse-operator-templatesd-files created
configmap/etc-clickhouse-operator-usersd-files created
deployment.apps/clickhouse-operator created
service/clickhouse-operator-metrics created

インストールの確認をします。clickhouse-opreratorはkube-systemに入っています。

$ kubectl get pods -n kube-system
NAME                                   READY   STATUS    RESTARTS      AGE
clickhouse-operator-6fd75cbd68-jmf95   2/2     Running   0             107s

$ kubectl describe deployment clickhouse-operator -n kube-system                   
Name:                   clickhouse-operator
Namespace:              kube-system
CreationTimestamp:      Thu, 03 Feb 2022 12:24:32 +0900
(省略)

STATUSが Running になっていれば正常にインストールできています。api-resourceは次のものが追加されています。

$ kubectl api-resources
clickhouseinstallations            chi          clickhouse.altinity.com/v1             true         ClickHouseInstallation
clickhouseinstallationtemplates    chit         clickhouse.altinity.com/v1             true         ClickHouseInstallationTemplate
clickhouseoperatorconfigurations   chopconf     clickhouse.altinity.com/v1             true         ClickHouseOperatorConfiguration

最後にこの記事中で使用するネームスペース(dev)を作成します。
小規模なクラスタでは特に必要なさそうですが、clickhouse-operatorのドキュメントではネームスペースで区切るのはいいことだとあるので従います。

$ kubectl create namespace dev
namespace/dev created

再起動後などminikubeの起動を忘れがちです。minikubeが起動していない状態でkubectl getなどを叩くと以下のような出力となります。その際は起動させてください。

$ kubectl get pods -n kube-system
The connection to the server 127.0.0.1:61810 was refused - did you specify the right host or port?

ClickHouseを構築する

公式のドキュメントにもあるサンプルを使用してClickHouseを構築します。

$ kubectl apply -n dev -f https://raw.githubusercontent.com/Altinity/clickhouse-operator/master/docs/chi-examples/01-simple-layout-01-1shard-1repl.yaml
clickhouseinstallation.clickhouse.altinity.com/simple-01 created

起動に少し時間がかかります。作成されたリソースを確認します。

$ kubectl get all -n dev 
NAME                             READY   STATUS    RESTARTS   AGE
pod/chi-simple-01-simple-0-0-0   1/1     Running   0          19m

NAME                               TYPE           CLUSTER-IP     EXTERNAL-IP   PORT(S)                         AGE
service/chi-simple-01-simple-0-0   ClusterIP      None           <none>        8123/TCP,9000/TCP,9009/TCP      19m
service/clickhouse-simple-01       LoadBalancer   10.100.74.68   <pending>     8123:31696/TCP,9000:30143/TCP   19m

NAME                                        READY   AGE
statefulset.apps/chi-simple-01-simple-0-0   1/1     19m

作成に使用したyamlファイルの内容は以下となります。(2021/12/23時点)

apiVersion: "clickhouse.altinity.com/v1"
kind: "ClickHouseInstallation"
metadata:
  name: "simple-01"
spec:
  configuration:
    clusters:
      - name: "simple"

命名規則

作成されるリソース名は以下の通りについています。chi はClickHouseInstallationのことです。

pod: chi-<metadata.name>-<spec.configuration.clusters.name>-<shard>-<replica>-0
service(ClusterIP): chi-<metadata.name>-<spec.configuration.clusters.name>-<shard>-<replica>
service(LoadBalancer): clickhouse-<metadata.name>
statefulset: chi-<metadata.name>-<spec.configuration.clusters.name>-<shard>-<replica>

構築できたら接続を確認します。
docker内のminikube上で動作しているため、直接httpアクセスはできません。minikubeに入ってアクセスを行います。IPはService(LoadBalancer)ののCLUSTER-IPの値になります。

$ docker exec -it minikube sh

$ curl 10.100.74.68:8123
OK

minikubeに入らなくてもclickhouse-clientを立て接続することも可能です。

$ kubectl -n dev exec -it pod/chi-simple-01-simple-0-0-0 -- clickhouse-client
ClickHouse client version 21.12.2.17 (official build).
Connecting to localhost:9000 as user default.
Connected to ClickHouse server version 21.12.2 revision 54452.

:) show databases

SHOW DATABASES

Query id: 101acd52-4ab9-46c5-aa97-38eebea5b3c1

┌─name───────────────┐
│ INFORMATION_SCHEMA │
│ default            │
│ information_schema │
│ system             │
└────────────────────┘

4 rows in set. Elapsed: 0.003 sec.
:) exit
Happy new year.

Happy new year.

構築と接続の確認ができたので、作成したリソースの削除をします。

$ kubectl delete -n dev -f https://raw.githubusercontent.com/Altinity/clickhouse-operator/master/docs/chi-examples/01-simple-layout-01-1shard-1repl.yaml
clickhouseinstallation.clickhouse.altinity.com "simple-01" deleted

削除を確認します。

$ kubectl get all -n dev
No resources found in dev namespace.

レプリケーション構成のClickHouseを構築する

続いてシャード、レプリケーションのクラスタ構成のClickHouseを構築します。

zookeeperの構築

ClickHouseのレプリケーションにはzookeeperが必要なのでドキュメントを参考に構築します。ここでは1インスタンス構成にします。

zookeeper用のネームスペースを作成します。

$ kubectl create namespace zoo1ns
namespace/zoo1ns created

1インスタンス構成のyamlファイルはリポジトリ内にあるのでそれを使用して構築します。

$ kubectl apply -n zoo1ns -f https://raw.githubusercontent.com/Altinity/clickhouse-operator/master/deploy/zookeeper/quick-start-persistent-volume/zookeeper-1-node.yaml
sistent-volume/zookeeper-1-node.yaml
service/zookeeper created
service/zookeepers created
Warning: policy/v1beta1 PodDisruptionBudget is deprecated in v1.21+, unavailable in v1.25+; use policy/v1 PodDisruptionBudget
poddisruptionbudget.policy/zookeeper-pod-disruption-budget created
statefulset.apps/zookeeper created

Warningが出力されていますが、zookeeper-1-node.yamlの問題なので一旦無視します。もしこの問題で動作しない時はファイルをダウンロードして apiVersion: policy/v1beta1 -> apiVersion: policy/v1 に変更して使用してください。

構築を確認します。

$ kubectl get all -n zoo1ns
NAME              READY   STATUS    RESTARTS   AGE
pod/zookeeper-0   1/1     Running   0          50s

NAME                 TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)             AGE
service/zookeeper    ClusterIP   10.111.66.234   <none>        2181/TCP,7000/TCP   50s
service/zookeepers   ClusterIP   None            <none>        2888/TCP,3888/TCP   50s

NAME                         READY   AGE
statefulset.apps/zookeeper   1/1     50s

ClickHouseクラスタの構築

zookeeperの構築が完了したらClickHouseの構築を行います。ドキュメントは以下です。

例によりリポジトリ内にあるサンプルを使用します。
2シャード2レプリカの4インスタンスの構成でクラスタが構築されます。

$ kubectl apply -n dev -f https://raw.githubusercontent.com/Altinity/clickhouse-operator/master/docs/chi-examples/04-replication-zookeeper-05-simple-PV.yaml
clickhouseinstallation.clickhouse.altinity.com/repl-05 created

起動にはしばらくかかるので待ちます。起動が終わったら状態を確認します。

$ kubectl get all -n dev
NAME                               READY   STATUS    RESTARTS   AGE
pod/chi-repl-05-replicated-0-0-0   1/1     Running   0          87s
pod/chi-repl-05-replicated-0-1-0   1/1     Running   0          45s
pod/chi-repl-05-replicated-1-0-0   1/1     Running   0          23s
pod/chi-repl-05-replicated-1-1-0   1/1     Running   0          3s

NAME                                 TYPE           CLUSTER-IP     EXTERNAL-IP   PORT(S)                         AGE
service/chi-repl-05-replicated-0-0   ClusterIP      None           <none>        8123/TCP,9000/TCP,9009/TCP      47s
service/chi-repl-05-replicated-0-1   ClusterIP      None           <none>        8123/TCP,9000/TCP,9009/TCP      29s
service/chi-repl-05-replicated-1-0   ClusterIP      None           <none>        8123/TCP,9000/TCP,9009/TCP      8s
service/chi-repl-05-replicated-1-1   ClusterIP      None           <none>        8123/TCP,9000/TCP,9009/TCP      1s
service/clickhouse-repl-05           LoadBalancer   10.99.134.99   <pending>     8123:30634/TCP,9000:31800/TCP   89s

NAME                                          READY   AGE
statefulset.apps/chi-repl-05-replicated-0-0   1/1     87s
statefulset.apps/chi-repl-05-replicated-0-1   1/1     45s
statefulset.apps/chi-repl-05-replicated-1-0   1/1     23s
statefulset.apps/chi-repl-05-replicated-1-1   1/1     3s

構築できました。
続いて実際にReplicatedのテーブルを作成、データを登録していきます。ドキュメントによるとレプリカの設定に使える変数として、macroにinstallation、cluster、replica、shardが設定されるようです。

$ kubectl -n dev exec -it pod/chi-repl-05-replicated-0-0-0 -- clickhouse-client
ClickHouse client version 20.7.4.11 (official build).
Connecting to localhost:9000 as user default.
Connected to ClickHouse server version 20.7.4 revision 54437.

展開される変数の確認

:) SELECT *
FROM system.macros

┌─macro─────────────┬─substitution───────────────┐
│ all-sharded-shard │ 1                          │
│ cluster           │ replicated                 │
│ installation      │ repl-05                    │
│ replica           │ chi-repl-05-replicated-0-0 │
│ shard             │ 0                          │
└───────────────────┴────────────────────────────┘

5 rows in set. Elapsed: 0.002 sec.

:) CREATE TABLE events_local ON CLUSTER `{cluster}`
(
    `event_date` Date,
    `event_type` Int32,
    `article_id` Int32,
    `title` String
)
ENGINE = ReplicatedMergeTree('/clickhouse/{installation}/{cluster}/tables/{shard}/{database}/{table}', '{replica}')
PARTITION BY toYYYYMM(event_date)
ORDER BY (event_type, article_id)

┌─host───────────────────────┬─port─┬─status─┬─error─┬─num_hosts_remaining─┬─num_hosts_active─┐
│ chi-repl-05-replicated-1-1 │ 9000 │      0 │       │                   3 │                1 │
│ chi-repl-05-replicated-0-0 │ 9000 │      0 │       │                   2 │                1 │
│ chi-repl-05-replicated-0-1 │ 9000 │      0 │       │                   1 │                1 │
└────────────────────────────┴──────┴────────┴───────┴─────────────────────┴──────────────────┘
┌─host───────────────────────┬─port─┬─status─┬─error─┬─num_hosts_remaining─┬─num_hosts_active─┐
│ chi-repl-05-replicated-1-0 │ 9000 │      0 │       │                   0 │                0 │
└────────────────────────────┴──────┴────────┴───────┴─────────────────────┴──────────────────┘

4 rows in set. Elapsed: 0.185 sec.

:) INSERT INTO events_local SELECT 
    today(),
    rand() % 3,
    number,
    'my title'
FROM numbers(100)

Ok.

0 rows in set. Elapsed: 0.017 sec.

:) SELECT *
FROM events_local
LIMIT 5

┌─event_date─┬─event_type─┬─article_id─┬─title────┐
│ 2021-12-22 │          0 │          4 │ my title │
│ 2021-12-22 │          0 │          5 │ my title │
│ 2021-12-22 │          0 │          7 │ my title │
│ 2021-12-22 │          0 │          8 │ my title │
│ 2021-12-22 │          0 │         12 │ my title │
└────────────┴────────────┴────────────┴──────────┘

5 rows in set. Elapsed: 0.003 sec.

zookeeperの確認

:) SELECT name
FROM system.zookeeper
WHERE path = '/clickhouse/repl-05/replicated/tables/0/default/events_local'

┌─name───────────────────────┐
│ metadata                   │
│ temp                       │
│ mutations                  │
│ log                        │
│ leader_election            │
│ columns                    │
│ blocks                     │
│ nonincrement_block_numbers │
│ replicas                   │
│ quorum                     │
│ block_numbers              │
└────────────────────────────┘

11 rows in set. Elapsed: 0.006 sec.

別のpodに接続してレプリケーションされていることを確認します。

> kubectl -n dev exec -it pod/chi-repl-05-replicated-0-1-0 -- clickhouse-client
ClickHouse client version 20.7.4.11 (official build).
Connecting to localhost:9000 as user default.
Connected to ClickHouse server version 20.7.4 revision 54437.

:) SELECT *
FROM events_local
LIMIT 5

┌─event_date─┬─event_type─┬─article_id─┬─title────┐
│ 2021-12-22 │          0 │          4 │ my title │
│ 2021-12-22 │          0 │          5 │ my title │
│ 2021-12-22 │          0 │          7 │ my title │
│ 2021-12-22 │          0 │          8 │ my title │
│ 2021-12-22 │          0 │         12 │ my title │
└────────────┴────────────┴────────────┴──────────┘

5 rows in set. Elapsed: 0.003 sec.

レプリケーションの確認ができました。

ClickHouseのアップグレード

最後にClickHouseのアップグレードを試していきます。ドキュメントは以下です。

ここでは、一つ前のシャード、レプリカ構成で作成したクラスタを1台ずつ更新していきたいと思います。
構築に使用したyamlファイルをダウンロードして04-replication-zookeeper-05-simple-PV-upgrade.yamlという名前で保存します。

最新の21.12に更新したいと思います。
まずはtemplates.podTemplatesに設定を追加します。各サーバの設定はlayout.shardsで指定すれば上書きできます。shardの名前はデフォルトが設定されているので、mocrosテーブルを参照してください。replicaも名前で指定したいのですが、デフォルトでついた名前(chi-repl-05-replicated-0-0)の文字列長が15を超えているため指定できませんでした。

apiVersion: "clickhouse.altinity.com/v1"
kind: "ClickHouseInstallation"

metadata:
  name: "repl-05"

spec:
  defaults:
    templates: 
      dataVolumeClaimTemplate: default
      podTemplate: clickhouse:19.6
 
  configuration:
    zookeeper:
      nodes:
      - host: zookeeper.zoo1ns
    clusters:
      - name: replicated
        layout:
          # shardsCount: 2
          # replicasCount: 2
          shards:
            - name: "0"
              replicas:
              - tcpPort: 9000
              - tcpPort: 9000
                templates:
                  podTemplate: clickhouse:21.12
            - name: "1"
              replicas:
              - tcpPort: 9000
              - tcpPort: 9000
  templates:
    volumeClaimTemplates:
      - name: default
        spec:
          accessModes:
            - ReadWriteOnce
          resources:
            requests:
              storage: 500Mi
    podTemplates:
      - name: clickhouse:19.6
        spec:
          containers:
            - name: clickhouse-pod
              image: yandex/clickhouse-server:20.7
      - name: clickhouse:21.12
        spec:
          containers:
            - name: clickhouse-pod
              image: clickhouse/clickhouse-server:21.12

変更を適用します。

$ kubectl apply -n dev -f 04-replication-zookeeper-05-simple-PV-upgrade.yaml

変更が走るまでしばらく時間がかかるので待ちます。変更完了後に状態を表示すると、AGEからpod/chi-repl-05-replicated-0-1-0のみ変更されていることがわかります。

$ kubectl get all -n dev                                    
NAME                               READY   STATUS    RESTARTS   AGE
pod/chi-repl-05-replicated-0-0-0   1/1     Running   0          19m
pod/chi-repl-05-replicated-0-1-0   1/1     Running   0          2m11s
pod/chi-repl-05-replicated-1-0-0   1/1     Running   0          18m
pod/chi-repl-05-replicated-1-1-0   1/1     Running   0          18m

NAME                                 TYPE           CLUSTER-IP     EXTERNAL-IP   PORT(S)                         AGE
service/chi-repl-05-replicated-0-0   ClusterIP      None           <none>        8123/TCP,9000/TCP,9009/TCP      19m
service/chi-repl-05-replicated-0-1   ClusterIP      None           <none>        8123/TCP,9000/TCP,9009/TCP      19m
service/chi-repl-05-replicated-1-0   ClusterIP      None           <none>        8123/TCP,9000/TCP,9009/TCP      18m
service/chi-repl-05-replicated-1-1   ClusterIP      None           <none>        8123/TCP,9000/TCP,9009/TCP      17m
service/clickhouse-repl-05           LoadBalancer   10.99.228.67   <pending>     8123:32628/TCP,9000:32547/TCP   19m

NAME                                          READY   AGE
statefulset.apps/chi-repl-05-replicated-0-0   1/1     19m
statefulset.apps/chi-repl-05-replicated-0-1   1/1     19m
statefulset.apps/chi-repl-05-replicated-1-0   1/1     18m
statefulset.apps/chi-repl-05-replicated-1-1   1/1     18m

ClickHouseにアクセスして更新後のバージョンを確認します。

$ kubectl -n dev exec -it pod/chi-repl-05-replicated-0-1-0 -- clickhouse-client
ClickHouse client version 21.12.2.17 (official build).
Connecting to localhost:9000 as user default.
Connected to ClickHouse server version 21.12.2 revision 54452.

21.12.2.1に更新されています。つづいてデータを確認します。

:) SELECT *
FROM events
LIMIT 5

Query id: 4e8eb4f2-f760-472c-8305-1c9c28273ce8

┌─event_date─┬─event_type─┬─article_id─┬─title────┐
│ 2021-12-22 │          0 │          0 │ my title │
│ 2021-12-22 │          0 │          3 │ my title │
│ 2021-12-22 │          0 │          5 │ my title │
│ 2021-12-22 │          0 │          9 │ my title │
│ 2021-12-22 │          0 │         12 │ my title │
└────────────┴────────────┴────────────┴──────────┘

5 rows in set. Elapsed: 0.002 sec.

1台の更新が確認できたので、同じように他のpodにも変更を行なっていけば全てのアップグレードが行えます。

clickhouse-operatorの設定変更

clickhouse-operatorの設定の変更方法を試します。ドキュメントは以下です。

デフォルトではclickhouse-operatorで作成したDBはdefaultユーザのアクセスをローカルのみに制限しています。ここではその制限を外すのと、passwordも空にします。
設定を変更する方法はいくつかありますが、今回は　ClickHouseOperatorConfiguration を使用します。ドキュメントにあるexampleのファイルを取得し、変更したcustom-config.yamlを作成します。変更箇所の差分を以下に示します。

$ diff -y 70-chop-config.yaml custom-config.yaml 
################################################           ################################################
##                                                         ##
## Configuration Users Section                             ## Configuration Users Section
##                                                         ##
################################################           ################################################
user:                                                      user:
  default:                                                   default:
    # Default values for ClickHouse user configuration         # Default values for ClickHouse user configuration
    # 1. user/profile - string                                 # 1. user/profile - string
    # 2. user/quota - string                                   # 2. user/quota - string
    # 3. user/networks/ip - multiple strings                   # 3. user/networks/ip - multiple strings
    # 4. user/password - string                                # 4. user/password - string
    profile: default                                           profile: default
    quota: default                                             quota: default
    networksIP:                                                networksIP:
      - "::1"                                           |        - "::/0"
      - "127.0.0.1"                                     <
     password: "default"                                |      password: ""

リソースを作成します。

$ kubectl apply -f custom-config.yaml -n kube-system

$ kubectl get chopconf -n kube-system                           
NAME        NAMESPACES
chop-config-01

作成が確認できたらclickhouse-operatorを再起動して反映します。

$ kubectl rollout restart deploy clickhouse-operator -n kube-system

以上で、設定を変更できました。今後作成するDBにはこの設定が反映されることになります。

clickhouse-operatorを使用してClickHouseの構築からアップグレードまで基本的な操作を動かしてきました。自分も触り始めたばかりでどういったことができるかわかっていませんが、設定ファイルのレイアウトを見る限りコンフィグファイルのカスタマイズなど細かい設定まで行えるようです。
また、リポジトリ内には多くのサンプルもあり、AWSでの設定や、複数ストレージの設定などもちょっと調べれば使える気がしているので、もっと使い込んでいこうと思います。