ClickHouse Keeper (clickhouse-keeper)
このページは ClickHouse Cloud には適用されません。ここに記載されている手順は、ClickHouse Cloud サービスで自動化されています。
ClickHouse Keeperは、データのレプリケーションと分散DDLクエリの実行のためのコーディネーションシステムを提供します。ClickHouse KeeperはZooKeeperと互換性があります。
実装の詳細
ZooKeeperは、最初の有名なオープンソースのコーディネーションシステムの一つです。Javaで実装されており、かなりシンプルで強力なデータモデルを持っています。ZooKeeperのコーディネーションアルゴリズム、ZooKeeper Atomic Broadcast (ZAB)は、各ZooKeeperノードがローカルでリードを処理するため、リードの線形性保証を提供しません。ZooKeeperとは異なり、ClickHouse KeeperはC++で書かれており、RAFTアルゴリズムの実装を使用しています。このアルゴリズムは、リードとライトの線形性を可能にし、さまざまな言語でのオープンソースの実装を持っています。
デフォルトでは、ClickHouse KeeperはZooKeeperと同じ保証を提供します：線形性のあるライトと非線形性のあるリードです。互換性のあるクライアントサーバープロトコルを持っているので、標準的なZooKeeperクライアントを使用してClickHouse Keeperとやり取りできます。スナップショットとログはZooKeeperとは互換性のない形式ですが、clickhouse-keeper-converterツールを使用することでZooKeeperデータをClickHouse Keeperスナップショットに変換することができます。ClickHouse Keeperのサーバー間プロトコルもZooKeeperと互換性がないため、混合ZooKeeper / ClickHouse Keeperクラスターは不可能です。
ClickHouse Keeperは、ZooKeeperと同様にアクセス制御リスト (ACL) をサポートしています。ClickHouse Keeperは同じ権限のセットをサポートし、同一の組み込みスキームを持っています：world、auth、およびdigest。ダイジェスト認証スキームはusername:passwordの組み合わせを使用し、パスワードはBase64でエンコードされます。
外部統合はサポートされていません。
設定
ClickHouse Keeperは、ZooKeeperのスタンドアロンの代替として使用することも、ClickHouseサーバーの内部部分として使用することもできます。どちらの場合でも、設定はほぼ同じ.xmlファイルです。
Keeper設定項目
主なClickHouse Keeperの設定タグは<keeper_server>で、次のパラメータを持っています：
| パラメータ | 説明 | デフォルト |
|---|---|---|
tcp_port | クライアントが接続するためのポート。 | 2181 |
tcp_port_secure | クライアントとkeeper-server間のSSL接続のためのセキュアポート。 | - |
server_id | 一意のサーバーID。ClickHouse Keeperクラスターの各参加者は一意の番号（1、2、3、など）を持つ必要があります。 | - |
log_storage_path | コーディネーションログのパス。ZooKeeperと同様に、ログは混雑のないノードに保存するのが最適です。 | - |
snapshot_storage_path | コーディネーションスナップショットのパス。 | - |
enable_reconfiguration | reconfigを介した動的クラスタ再構成を有効にします。 | False |
max_memory_usage_soft_limit | Keeperの最大メモリ使用に対するソフトリミット（バイト）。 | max_memory_usage_soft_limit_ratio * physical_memory_amount |
max_memory_usage_soft_limit_ratio | max_memory_usage_soft_limitが設定されていないか、ゼロに設定されている場合、この値を使用してデフォルトのソフトリミットを定義します。 | 0.9 |
cgroups_memory_observer_wait_time | max_memory_usage_soft_limitが設定されていないか0に設定されている場合、この間隔を使用して物理メモリの量を観察します。メモリ量が変更されると、Keeperのメモリソフトリミットをmax_memory_usage_soft_limit_ratioで再計算します。 | 15 |
http_control | HTTPコントロールインターフェースの設定。 | - |
digest_enabled | リアルタイムデータ整合性チェックを有効にします。 | True |
create_snapshot_on_exit | シャットダウン中にスナップショットを作成します。 | - |
hostname_checks_enabled | クラスター設定のためのサニティホスト名チェックを有効にします（例：ローカルホストがリモートエンドポイントと一緒に使用される場合）。 | True |
four_letter_word_white_list | 4文字の命令のホワイトリスト。 | conf, cons, crst, envi, ruok, srst, srvr, stat, wchs, dirs, mntr, isro, rcvr, apiv, csnp, lgif, rqld, ydld |
他の一般的なパラメータは、ClickHouseサーバーの設定（listen_host、loggerなど）から継承されます。
内部コーディネーション設定
内部コーディネーション設定は、<keeper_server>.<coordination_settings>セクションにあり、次のパラメータを持っています：
| パラメータ | 説明 | デフォルト |
|---|---|---|
operation_timeout_ms | 単一のクライアント操作のタイムアウト（ms）。 | 10000 |
min_session_timeout_ms | クライアントセッションの最小タイムアウト（ms）。 | 10000 |
session_timeout_ms | クライアントセッションの最大タイムアウト（ms）。 | 100000 |
dead_session_check_period_ms | ClickHouse Keeperがデッドセッションをチェックし、それを削除する頻度（ms）。 | 500 |
heart_beat_interval_ms | ClickHouse Keeperリーダーがフォロワーにハートビートを送信する頻度（ms）。 | 500 |
election_timeout_lower_bound_ms | フォロワーがこの間隔でリーダーからハートビートを受け取らなかった場合、リーダー選挙を開始できます。この値はelection_timeout_upper_bound_ms以下でなければなりません。理想的には同じであってはいけません。 | 1000 |
election_timeout_upper_bound_ms | フォロワーがこの間隔でリーダーからハートビートを受け取らなかった場合、リーダー選挙を開始しなければなりません。 | 2000 |
rotate_log_storage_interval | 単一のファイルに保存するログレコードの数。 | 100000 |
reserved_log_items | コンパクション前に保存するコーディネーションログレコードの数。 | 100000 |
snapshot_distance | ClickHouse Keeperが新しいスナップショットを作成する頻度（ログ内のレコード数）。 | 100000 |
snapshots_to_keep | 保持するスナップショットの数。 | 3 |
stale_log_gap | リーダーがフォロワーをスタレと見なす閾値。この場合、ログの代わりにスナップショットを送信します。 | 10000 |
fresh_log_gap | ノードが新鮮になったとき。 | 200 |
max_requests_batch_size | RAFTに送信される前のリクエストカウントのバッチの最大サイズ。 | 100 |
force_sync | コーディネーションログへの各書き込みでfsyncを呼び出します。 | true |
quorum_reads | 読み取りリクエストを、同様の速度で全体のRAFT合意として実行します。 | false |
raft_logs_level | コーディネーションに関するテキストログレベル（トレース、デバッグなど）。 | system default |
auto_forwarding | フォロワーからリーダーへの書き込みリクエストの転送を許可します。 | true |
shutdown_timeout | 内部接続を終了し、シャットダウンを待機します（ms）。 | 5000 |
startup_timeout | サーバーが指定されたタイムアウト内に他のクォーラム参加者に接続できない場合、終了します（ms）。 | 30000 |
async_replication | 非同期レプリケーションを有効にします。全ての書き込みおよび読み取りの保証が保持される一方で、より良いパフォーマンスが達成されます。設定はデフォルトで無効になっており、後方互換性を破らないようにしています。 | false |
latest_logs_cache_size_threshold | 最新のログエントリのインメモリキャッシュの最大サイズ。 | 1GiB |
commit_logs_cache_size_threshold | コミットに必要なログエントリのインメモリキャッシュの最大サイズ。 | 500MiB |
disk_move_retries_wait_ms | ファイルがディスク間で移動されている最中に発生した失敗後の再試行の間隔。 | 1000 |
disk_move_retries_during_init | 初期化中にファイルがディスク間で移動されている最中に発生した失敗の再試行の回数。 | 100 |
experimental_use_rocksdb | rocksdbをバックエンドストレージとして使用します。 | 0 |
クォーラム設定は<keeper_server>.<raft_configuration>セクションにあり、サーバーの説明を含んでいます。
全クォーラムに対して唯一のパラメータはsecureで、クォーラム参加者間の通信に暗号化された接続を有効にします。このパラメータはSSL接続が必要な場合はtrueに設定し、それ以外の場合は指定しないでおきます。
各<server>の主なパラメータは次のとおりです：
id— クォーラム内のサーバー識別子。hostname— このサーバーが存在するホスト名。port— このサーバーが接続をリッスンするポート。can_become_leader— サーバーをlearnerとして設定するにはfalseに設定します。省略した場合、値はtrueになります。
ClickHouse Keeperクラスターのトポロジーに変更があった場合（例：サーバーの置換）、server_idとhostnameのマッピングを一貫して保ち、既存のserver_idを異なるサーバーに対してシャッフルまたは再利用しないようにしてください（自動化スクリプトに依存してClickHouse Keeperをデプロイする場合に起こることがあります）。
Keeperインスタンスのホストが変更される可能性がある場合は、生のIPアドレスの代わりにホスト名を定義して使用することをお勧めします。ホスト名を変更することは、サーバーを削除して再追加するのと同じであり、場合によっては不可能なことがあります（例：クォーラムのために十分なKeeperインスタンスがない場合）。
async_replicationは後方互換性を破らないようにデフォルトで無効になっています。クラスター内の全てのKeeperインスタンスがasync_replicationをサポートするバージョン（v23.9+）で実行されている場合、パフォーマンスが向上し、欠点がないため、これを有効にすることをお勧めします。
三つのノードを持つクォーラムの設定の例は、test_keeper_プレフィックスを持つ統合テストで見つけることができます。サーバー#1の設定例：
実行方法
ClickHouse KeeperはClickHouseサーバーパッケージにバンドルされており、<keeper_server>の設定を/etc/your_path_to_config/clickhouse-server/config.xmlに追加し、従来通りにClickHouseサーバーを起動します。スタンドアロンのClickHouse Keeperを実行したい場合は、次のように開始できます：
シンボリックリンク（clickhouse-keeper）がない場合は、それを作成するか、clickhouseに対してkeeperを引数として指定できます：
Four Letter Word Commands
ClickHouse Keeper は Zookeeper とほぼ同じ 4lw コマンドを提供します。各コマンドは mntr や stat などの4文字から構成されています。いくつかの興味深いコマンドがあります。stat はサーバーと接続されたクライアントに関する一般的な情報を提供し、srvr と cons はそれぞれサーバーと接続に関する詳細を表示します。
4lw コマンドには、ホワイトリストの設定 four_letter_word_white_list があり、デフォルト値は conf,cons,crst,envi,ruok,srst,srvr,stat,wchs,dirs,mntr,isro,rcvr,apiv,csnp,lgif,rqld,ydld です。
コマンドは telnet または nc を介して ClickHouse Keeper に発行できます。クライアントポートで実行します。
以下は、詳細な 4lw コマンドです。
ruok: サーバーがエラーステートで動作しているかをテストします。サーバーが正常に動作している場合はimokと応答します。そうでなければ、全く応答しません。imokの応答は、サーバーがクォーラムに参加していることを示すものではなく、サーバープロセスがアクティブで指定されたクライアントポートにバインドされていることを示します。クォーラムやクライアント接続情報に関しての詳細を知るには「stat」を使用してください。
mntr: クラスターの健康状態を監視するために使用できる変数のリストを出力します。
srvr: サーバーの完全な詳細をリストします。
stat: サーバーと接続されたクライアントの簡潔な詳細をリストします。
srst: サーバーの統計をリセットします。このコマンドはsrvr,mntr,statの結果に影響します。
conf: サーバーの設定に関する詳細を表示します。
cons: このサーバーに接続されているすべてのクライアントの完全な接続/セッション詳細をリストします。受信/送信パケットの数、セッション ID、操作の遅延、最後に実行された操作などの情報を含みます…
crst: すべての接続の接続/セッション統計をリセットします。
envi: サーバーの環境に関する詳細を表示します。
dirs: スナップショットとログファイルの合計サイズをバイト単位で表示します。
isro: サーバーが読み取り専用モードで実行されているかどうかをテストします。サーバーが読み取り専用モードの場合はroと応答し、そうでない場合はrwと応答します。
wchs: サーバーに対するウェッチの簡単な情報をリストします。
wchc: セッションごとのウェッチに関する詳細情報をリストします。これは、関連するウェッチ（パス）を持つセッション（接続）のリストを出力します。この操作は、ウェッチの数に応じて高コストになる可能性があるため（サーバー性能に影響を与える）、注意して使用してください。
wchp: パスごとのウェッチに関する詳細情報をリストします。これは、関連するセッションを持つパス（ノード）のリストを出力します。この操作は、ウェッチの数に応じて高コストになる可能性があるため（サーバー性能に影響を与える）、注意して使用してください。
dump: 未解決のセッションとエフェメラルノードをリストします。これはリーダーのみで機能します。
csnp: スナップショット作成タスクをスケジュールします。成功した場合はスケジュールされたスナップショットの最終コミットされたログインデックスを返し、失敗した場合はFailed to schedule snapshot creation task.と返します。「lgif」コマンドを使用すると、スナップショットの完了状況を確認できます。
lgif: Keeper ログ情報。first_log_idx: ログストア内の私の最初のログインデックス;first_log_term: 私の最初のログターム;last_log_idx: ログストア内の私の最後のログインデックス;last_log_term: 私の最後のログターム;last_committed_log_idx: 状態マシン内の私の最後のコミットされたログインデックス;leader_committed_log_idx: 私の観点からのリーダーのコミットされたログインデックス;target_committed_log_idx: コミットされるべきターゲットログインデックス;last_snapshot_idx: 最後のスナップショットでコミットされた最大のログインデックス。
rqld: 新しいリーダーになるリクエストを送信します。リクエストを送信した場合はSent leadership request to leader.と返され、送信されなかった場合はFailed to send leadership request to leader.と返されます。ノードがすでにリーダーである場合、結果は同じです。
ftfl: すべてのフィーチャーフラグと、それらが Keeper インスタンスで有効になっているかどうかをリストします。
ydld: リーダーシップを放棄してフォロワーになるリクエストを送信します。このリクエストを受け取ったサーバーがリーダーである場合、最初に書き込み操作を一時停止し、その後、後任（現在のリーダーは後任になれない）が最新のログのキャッチアップを終了するまで待機し、次に辞任します。後任は自動的に選択されます。リクエストを送信した場合はSent yield leadership request to leader.と返され、送信されなかった場合はFailed to send yield leadership request to leader.と返されます。ノードがすでにフォロワーである場合、結果は同じです。
pfev: 収集されたすべてのイベントの値を返します。各イベントについて、イベント名、イベント値、およびイベントの説明を返します。
HTTP Control
ClickHouse Keeper は、レプリカがトラフィックを受け取る準備ができているかどうかを確認するための HTTP インターフェースを提供します。これは、Kubernetes のようなクラウド環境で使用できます。
/ready エンドポイントを有効にする設定の例:
Feature flags
Keeper は ZooKeeper とそのクライアントと完全に互換性がありますが、ClickHouse クライアントが使用できる独自の機能とリクエストタイプも導入しています。
これらの機能は後方互換性のない変更を引き起こす可能性があるため、デフォルトではほとんどが無効になっており、keeper_server.feature_flags 設定を使用して有効にすることができます。
すべての機能は明示的に無効にすることができます。
Keeper クラスター用の新しい機能を有効にする場合は、最初にクラスター内のすべての Keeper インスタンスをその機能をサポートするバージョンに更新し、その後で機能自体を有効にすることをお勧めします。
multi_read を無効にし、check_not_exists を有効にする機能フラグ設定の例:
利用可能な機能は以下の通りです：
multi_read - 複数リクエストの読み取りをサポートします。デフォルト: 1
filtered_list - ノードの種類（エフェメラルまたは永続的）によって結果をフィルタリングするリストリクエストをサポートします。デフォルト: 1
check_not_exists - ノードが存在しないことを確認する CheckNotExists リクエストをサポートします。デフォルト: 0
create_if_not_exists - ノードが存在しない場合にノードを作成しようとする CreateIfNotExists リクエストをサポートします。存在する場合、変更は適用されず、ZOK が返されます。デフォルト: 0
Migration from ZooKeeper
ZooKeeper から ClickHouse Keeper へのシームレスな移行は不可能です。 ZooKeeper クラスターを停止し、データを変換し、ClickHouse Keeper を起動する必要があります。clickhouse-keeper-converter ツールは、ZooKeeper のログとスナップショットを ClickHouse Keeper のスナップショットに変換できます。これは ZooKeeper > 3.4 のみで動作します。移行手順：
-
すべての ZooKeeper ノードを停止します。
-
オプションですが推奨されます: ZooKeeper のリーダーノードを見つけて、そのノードを再起動して停止します。これにより、ZooKeeper は一貫したスナップショットを作成します。
-
リーダー上で
clickhouse-keeper-converterを実行します。たとえば：
- スナップショットを ClickHouse サーバーノードにコピーします。
keeperが設定されている場合、または ZooKeeper の代わりに ClickHouse Keeper を起動します。スナップショットはすべてのノードに存在する必要があります。そうでないと、空のノードが速くなる可能性があり、そのうちの1つがリーダーになる可能性があります。
keeper-converter ツールは、Keeper のスタンドアロンバイナリからは利用できません。
ClickHouse をインストールしている場合は、バイナリを直接使用できます：
そうでない場合は、バイナリをダウンロードし、前述のように ClickHouse をインストールせずにツールを実行できます。
Recovering after losing quorum
ClickHouse Keeper は Raft を使用しているため、クラスターサイズに応じて一定数のノードクラッシュに耐えることができます。 たとえば、3ノードクラスターの場合、1ノードがクラッシュしても正しく動作し続けます。
クラスター構成は動的に構成できますが、いくつかの制限があります。再構成も Raft に依存しているため、クラスターからノードを追加または削除するにはクォーラムが必要です。同時に多くのノードがクラスター内で失われ、再起動の可能性がない場合、Raft は機能を停止し、通常の方法でクラスターを再構成できなくなります。
それにもかかわらず、ClickHouse Keeper には、ノードが1つだけで強制的にクラスターを再構成できる回復モードがあります。 この操作は、ノードを再起動できない場合、または同じエンドポイントで新しいインスタンスを起動する場合、最後の手段としてのみ行うべきです。
続行する前に注意すべき重要なポイント：
- 故障したノードが再度クラスターに接続できないことを確認してください。
- ステップで指定されるまで、新しいノードを一つも起動しないでください。
上記のことが真であると確認した後、次のことを行う必要があります：
- 新しいリーダーとなる単一の Keeper ノードを選択します。そのノードのデータがクラスター全体に使用されるため、最新の状態のノードを使用することをお勧めします。
- 何かをする前に、選択したノードの
log_storage_pathとsnapshot_storage_pathフォルダのバックアップを取ります。 - 使用するすべてのノードでクラスターを再構成します。
- 選択したノードに対して、ノードを回復モードに移行するための4文字コマンド
rcvrを送信するか、選択したノードで Keeper インスタンスを停止し、--force-recovery引数を付けて再起動します。 - 選択したノードに対する
mntrがzk_server_stateに対してfollowerを返すまで、新しいノードの Keeper インスタンスを一つずつ起動します。 - 回復モード中は、リーダーノードは、新しいノードとクォーラムを達成するまで
mntrコマンドにエラーメッセージを返し、クライアントおよびフォロワーからのリクエストを拒否します。 - クォーラムが達成された後、リーダーノードは通常の動作モードに戻り、すべてのリクエストを受け入れ、
mntrを使用して Raft 検証を行い、zk_server_stateに対してleaderを返します。
Using disks with Keeper
Keeper はスナップショット、ログファイル、状態ファイルの保存に使用する 外部ディスク のサブセットをサポートします。
サポートされているディスクのタイプは以下の通りです：
- s3_plain
- s3
- local
以下は、設定ファイル内のディスク定義の例です。
ログ用にディスクを使用するには、keeper_server.log_storage_disk 設定をディスクの名前に設定する必要があります。
スナップショット用にディスクを使用するには、keeper_server.snapshot_storage_disk 設定をディスクの名前に設定する必要があります。
さらに、最新のログまたはスナップショット用に異なるディスクを使用する場合は、それぞれ keeper_server.latest_log_storage_disk と keeper_server.latest_snapshot_storage_disk を使用できます。
その場合、Keeper は新しいログまたはスナップショットが作成されると、ファイルを適切なディスクに自動的に移動します。
状態ファイル用にディスクを使用するには、keeper_server.state_storage_disk 設定をディスクの名前に設定する必要があります。
ディスク間でのファイル移動は安全であり、Keeper が転送中に停止した場合でもデータが失われるリスクはありません。 ファイルが新しいディスクに完全に移動されるまで、古いディスクからは削除されません。
keeper_server.coordination_settings.force_sync を true (true がデフォルト) に設定した Keeper は、すべてのタイプのディスクに対していくつかの保証を満たすことができません。
現在、localタイプのディスクのみが永続的な同期をサポートします。
force_sync が使用される場合、latest_log_storage_disk が使用されていない場合は、log_storage_disk は local ディスクである必要があります。
latest_log_storage_disk が使用されている場合、それは常に local ディスクであるべきです。
force_sync が無効になっている場合、すべてのタイプのディスクを任意の構成で使用できます。
Keeper インスタンスのための可能なストレージ設定は以下の通りです。
このインスタンスは、最新でないすべてのログをディスク log_s3_plain に保存しますが、最新のログは log_local ディスクに保存されます。
同じ論理がスナップショットにも適用され、最新のスナップショット以外のすべてのスナップショットは snapshot_s3_plain に保存されますが、最新のスナップショットは snapshot_local ディスクに保存されます。
Changing disk setup
新しいディスク設定を適用する前に、すべての Keeper ログとスナップショットを手動でバックアップしてください。
階層的なディスク設定が定義されている場合（最新のファイルに異なるディスクを使用する場合）、Keeper は起動時に自動的にファイルを正しいディスクに移動しようとします。
以前と同じ保証が適用されます。ファイルが新しいディスクに完全に移動されるまで、古いディスクからは削除されないため、複数の再起動を安全に実行できます。
完全に新しいディスクにファイルを移動する必要がある場合（または 2 つのディスク構成から単一のディスク構成に移動する場合）、keeper_server.old_snapshot_storage_disk と keeper_server.old_log_storage_disk の複数の定義を使用することができます。
以下の設定は、以前の2ディスク構成から完全に新しい単一ディスク構成に移動する方法を示しています：
起動時に、すべてのログファイルは log_local と log_s3_plain から log_local2 ディスクに移動されます。
また、すべてのスナップショットファイルは snapshot_local と snapshot_s3_plain から snapshot_local2 ディスクに移動されます。
Configuring logs cache
ディスクから読み取るデータ量を最小限に抑えるために、Keeper はメモリ内にログエントリをキャッシュします。
リクエストが大きい場合、ログエントリがメモリを占有しすぎるため、キャッシュされるログの量は制限されています。
この制限は、以下の2つの設定によって管理されます：
latest_logs_cache_size_threshold- キャッシュに保存される最新のログの総サイズcommit_logs_cache_size_threshold- 次にコミットする必要がある後続のログの総サイズ
デフォルト値が大きすぎる場合は、これらの2つの設定を減らすことでメモリ使用量を削減できます。
pfev コマンドを使用して、各キャッシュからおよびファイルから読み取られたログの量を確認できます。
Prometheus エンドポイントからのメトリクスを使用して、両方のキャッシュの現在のサイズを追跡することもできます。
Prometheus
Keeper は、Prometheus からのスクレイピングのためにメトリクスデータを公開できます。
設定：
endpoint- Prometheus サーバーによってメトリクスをスクレイピングするための HTTP エンドポイント。/から始まります。port-endpoint用のポート。metrics- system.metrics テーブルからメトリクスを公開するフラグ。events- system.events テーブルからメトリクスを公開するフラグ。asynchronous_metrics- system.asynchronous_metrics テーブルから現在のメトリクス値を公開するフラグ。
例
確認する（127.0.0.1 を ClickHouse サーバーの IP アドレスまたはホスト名に置き換えます）：
ClickHouse Cloud の Prometheus 統合 についてもご覧ください。
ClickHouse Keeper User Guide
このガイドでは、ClickHouse Keeper の設定を簡単かつ最小限にした例を提供し、分散操作をテストする方法を説明します。この例は、Linux の3ノードを使用して実施されます。
1. Keeper 設定でノードを構成する
-
3つのホスト（
chnode1,chnode2,chnode3）に3つの ClickHouse インスタンスをインストールします。（ClickHouse のインストールの詳細は Quick Start をご覧ください。） -
各ノードで、ネットワークインターフェースを介して外部通信を許可するために、次のエントリーを追加します。
-
すべてのサーバーに次の ClickHouse Keeper 設定を追加し、各サーバーの
<server_id>設定を更新します。chnode1の場合は1、chnode2の場合は2などです。これらは上記の基本設定です：
Parameter Description Example tcp_port keeper のクライアントが使用するポート 9181（デフォルトの2181と等価） server_id Raft 構成で使用される各 ClickHouse Keeper サーバーの識別子 1 coordination_settings タイムアウトなどのパラメータが含まれたセクション タイムアウト: 10000, ログレベル: trace server 参加するサーバーの定義 各サーバーのリスト定義 raft_configuration Keeper クラスター内の各サーバーの設定 各サーバーの設定 id keeper サービスのサーバーの数値 ID 1 hostname Keeper クラスター内の各サーバーのホスト名、IP、または FQDN chnode1.domain.comport サーバー間 Keeper 接続を待ち受けるポート 9234 -
Zookeeper コンポーネントを有効にします。ClickHouse Keeper エンジンを使用します：
これらは上記の基本設定です：
Parameter Description Example node ClickHouse Keeper 接続用のノードリスト 各サーバーの設定エントリ host 各 ClickHouse keeper ノードのホスト名、IP、または FQDN chnode1.domain.comport ClickHouse Keeper クライアントポート 9181 -
ClickHouse を再起動し、各 Keeper インスタンスが実行中であることを確認します。各サーバーで次のコマンドを実行します。
ruokコマンドは、Keeper が正常に動作している場合はimokを返します： -
systemデータベースには、ClickHouse Keeper インスタンスの詳細を含むzookeeperという名前のテーブルがあります。このテーブルを表示してみましょう：テーブルは以下のようになります：
2. ClickHouseでクラスターを構成する
-
2つのシャードと2つのノード上に1つのレプリカを持つシンプルなクラスターを構成しましょう。3番目のノードはClickHouse Keeperにおける過半数を達成するために使用されます。
chnode1とchnode2の構成を更新してください。以下のクラスター定義は、各ノードに1つのシャードを持ち、合計2つのシャードでレプリケーションは行われません。この例では、一部のデータはあるノードに、残りは別のノードに存在します：パラメータ 説明 例 shard クラスター定義のレプリカのリスト 各シャードのレプリカのリスト replica 各レプリカの設定のリスト 各レプリカの設定エントリ host レプリカシャードをホストするサーバーのホスト名、IPまたはFQDN chnode1.domain.comport ネイティブなtcpプロトコルを使って通信するためのポート 9000 user クラスターインスタンスに認証するために使用されるユーザー名 default password クラスターインスタンスへの接続を可能にするために定義されたユーザーのパスワード ClickHouse123! -
ClickHouseを再起動し、クラスターが作成されたことを確認します：
あなたのクラスターが表示されるはずです：
3. 分散テーブルの作成とテスト
-
chnode1でClickHouseクライアントを使用して新しいクラスター上に新しいデータベースを作成します。ON CLUSTER句は、自動的に両方のノードにデータベースを作成します。 -
db1データベースに新しいテーブルを作成します。再度、ON CLUSTERは両方のノードにテーブルを作成します。 -
chnode1ノードで、いくつかの行を追加します： -
chnode2ノードでもいくつかの行を追加します： -
各ノードで
SELECTステートメントを実行すると、そのノードのデータのみが表示されることに注意してください。たとえば、chnode1で：chnode2では： -
2つのシャードのデータを表す
Distributedテーブルを作成できます。Distributedテーブルエンジンを持つテーブルは自身のデータを保存せず、複数のサーバーで分散クエリ処理を可能にします。読み取りはすべてのシャードに対して行われ、書き込みはシャード間で分散できます。次のクエリをchnode1で実行します： -
dist_tableをクエリすると、2つのシャードから全4行のデータが返されることに注意してください：
概要
このガイドでは、ClickHouse Keeperを使用してクラスターを設定する方法を示しました。ClickHouse Keeperを使用すると、クラスターを構成し、シャードを跨いで複製される分散テーブルを定義できます。
ユニークなパスを使用したClickHouse Keeperの構成
このページは ClickHouse Cloud には適用されません。ここに記載されている手順は、ClickHouse Cloud サービスで自動化されています。
説明
この記事では、組み込みの{uuid}マクロ設定を使用して、ClickHouse KeeperまたはZooKeeperでユニークなエントリを作成する方法を説明します。ユニークなパスは、テーブルを頻繁に作成および削除する際に役立ちます。これは、パスが作成されるたびに新しいuuidがそのパスで使用され、パスが再利用されないため、Keeperのガーベジコレクションがパスエントリを削除するのを数分待つ必要がなくなります。
例の環境
ClickHouse Keeperを全3ノードに構成し、2つのノードにClickHouseを配置する3ノードのクラスター。この構成により、ClickHouse Keeperに対して3ノード（タイブレイカーノードを含む）が提供され、2つのレプリカから構成された単一のClickHouseシャードが作成されます。
| ノード | 説明 |
|---|---|
chnode1.marsnet.local | データノード - クラスターcluster_1S_2R |
chnode2.marsnet.local | データノード - クラスターcluster_1S_2R |
chnode3.marsnet.local | ClickHouse Keeperタイブレイカーノード |
クラスターの例の構成：
{uuid}を使用したテーブルのセットアップ手順
- 各サーバーでマクロを構成します。サーバー1の例：
shardとreplicaのマクロを定義することに注意してください。ただし、{uuid}はここで定義されていません。それは組み込みであり、定義する必要はありません。
- データベースを作成します。
- マクロと
{uuid}を使用してクラスター上にテーブルを作成します。
- 分散テーブルを作成します。
テスト
- 最初のノード（例：
chnode1）にデータを挿入します。
- 2番目のノード（例：
chnode2）にデータを挿入します。
- 分散テーブルを使用してレコードを表示します。
代替案
デフォルトのレプリケーションパスは、マクロを使用して事前に定義でき、{uuid}も使用できます。
- 各ノードのテーブルのデフォルトを設定します。
ノードが特定のデータベースに使用される場合は、各ノードでマクロ{database}を定義することもできます。
- 明示的なパラメータなしでテーブルを作成します：
- デフォルト構成で使用されている設定を確認します。
トラブルシューティング
テーブル情報とUUIDを取得する例のコマンド：
上記のテーブルのUUIDに関するZooKeeper情報を取得する例のコマンド：
データベースはAtomicである必要があります。以前のバージョンからのアップグレード時には、defaultデータベースはOrdinaryタイプである可能性があります。
確認するには：
例えば、
ClickHouse Keeperの動的再構成
このページは ClickHouse Cloud には適用されません。ここに記載されている手順は、ClickHouse Cloud サービスで自動化されています。
説明
ClickHouse Keeperは、keeper_server.enable_reconfigurationがオンになっている場合、ZooKeeperのreconfigコマンドを部分的にサポートしています。これにより、動的なクラスター再構成が可能になります。
この設定がオフになっている場合、レプリカのraft_configurationセクションを手動で変更してクラスターを再構成できます。変更を適用するのはリーダーだけであるため、すべてのレプリカのファイルを編集する必要があります。あるいは、ZooKeeper互換のクライアントを通じてreconfigクエリを送信できます。
仮想ノード/keeper/configは、次の形式で最後にコミットされたクラスター構成を含みます：
- 各サーバーエントリーは改行で区切られています。
server_typeはparticipantまたはlearnerである必要があります（learnerはリーダー選挙に参加しません）。server_priorityは非負整数で、リーダー選挙で優先すべきノードを指示します。0の優先順位は、サーバーがリーダーになることはないことを意味します。
例：
reconfigコマンドを使用して新しいサーバーを追加したり、既存のサーバーを削除したり、既存のサーバーの優先順位を変更したりできます。以下は例です（clickhouse-keeper-clientを使用）：
そして、kazooに関する例は以下の通りです：
joiningのサーバーは上記で説明されたサーバー形式である必要があります。サーバーエントリーはカンマで区切る必要があります。新しいサーバーを追加する際には、server_priority（デフォルト値は1）およびserver_type（デフォルト値はparticipant）を省略することができます。
既存のサーバーの優先順位を変更したい場合は、ターゲット優先順位を加えてjoiningに追加します。ただし、サーバーのホスト、ポート、およびタイプは既存のサーバー構成と一致しなければなりません。
サーバーは、joiningおよびleavingでの出現順序で追加および削除されます。joiningからのすべての更新は、leavingからの更新の前に処理されます。
Keeperの再構成実装にはいくつかの留意点があります：
-
インクリメンタルな再構成のみがサポートされています。
new_membersが空でないリクエストは拒否されます。ClickHouse Keeperの実装は、構成を動的に変更するためにNuRaft APIに依存しています。NuRaftには、サーバーを1つずつ追加または削除する方法があります。このため、構成に対する各変更（
joiningの各部分、leavingの各部分）は個別に決定する必要があります。したがって、バルク再構成は利用できません。なぜなら、これはエンドユーザーにとって誤解を招くことだからです。サーバータイプ（participant/learner）を変更することもできません。これはNuRaftによってサポートされておらず、サーバーを削除して追加する必要があります。これもまた、誤解を招くことになります。
-
戻り値の
znodestat値は使用できません。 -
from_versionフィールドは使用されません。from_versionが設定されたすべてのリクエストは拒否されます。これは、/keeper/configが仮想ノードであるためで、これは永続ストレージに保存されるのではなく、リクエストごとに指定されたノード構成で生成されるためです。この決定は、データの重複を防ぐために行われました。なぜなら、NuRaftはこの構成をすでに保存しているからです。 -
ZooKeeperとは異なり、
syncコマンドを送信することでクラスターの再構成を待機する方法はありません。新しい構成は_最終的に_適用されますが、時間保証はありません。 -
reconfigコマンドは、さまざまな理由で失敗することがあります。クラスターの状態をチェックして、更新が適用されたかどうかを確認できます。
単一ノードのKeeperをクラスターに変換する
実験的なKeeperノードをクラスターに拡張する必要がある場合があります。以下は、3ノードクラスターにおけるその手順を示したスキームです：
- 重要：新しいノードは、現在の過半数未満のバッチで追加する必要があります。そうしないと、彼らは自分たちの中でリーダーを選出します。この例では1つずつ追加します。
- 既存のKeeperノードでは、
keeper_server.enable_reconfiguration構成パラメータをオンにしておく必要があります。 - 完全な新しいKeeperクラスターの構成で2番目のノードを起動します。
- 起動後、ノード1にそれを追加します（
reconfigを使用）。 - 次に、3番目のノードを起動し、
reconfigを使用してそれを追加します。 - 新しいKeeperノードを追加し、変更を適用するために
clickhouse-serverの構成を更新して再起動します。 - ノード1のRaft構成を更新し、オプションで再起動します。
このプロセスに自信を持つために、こちらのサンドボックスリポジトリをご覧ください。
サポートされていない機能
ClickHouse KeeperはZooKeeperとの完全互換を目指していますが、現在実装されていない機能もいくつかあります（開発は進行中です）：
createは、Statオブジェクトの返却をサポートしていません。createはTTLをサポートしていません。addWatchはPERSISTENT監視と連携しません。removeWatchおよびremoveAllWatchesはサポートされていません。setWatchesはサポートされていません。CONTAINERタイプのznodesを作成することはサポートされていません。SASL認証はサポートされていません。