この記事は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以外のインストールは 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での設定や、複数ストレージの設定などもちょっと調べれば使える気がしているので、もっと使い込んでいこうと思います。