ClickHouse Keeper (clickhouse-keeper)
このページは ClickHouse Cloud には適用されません。ここに記載された手順は、ClickHouse Cloud サービスで自動化されています。
ClickHouse Keeperは、データのレプリケーションおよび分散DDLクエリの実行のための調整システムを提供します。ClickHouse Keeperは、ZooKeeperと互換性があります。
実装の詳細
ZooKeeperは、初期の著名なオープンソースの調整システムの1つです。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に設定されている場合、この間隔を使用して物理メモリの量を観察します。メモリ量が変わると、max_memory_usage_soft_limit_ratioによってKeeperのメモリソフトリミットを再計算します。 | 15 |
http_control | HTTP制御インターフェイスの設定。 | - |
digest_enabled | リアルタイムデータ整合性チェックを有効にします。 | True |
create_snapshot_on_exit | シャットダウン中にスナップショットを作成します。 | - |
hostname_checks_enabled | クラスター設定のためのサニティホスト名チェックを有効にします（例：リモートエンドポイントと共にlocalhostが使われている場合）。 | True |
four_letter_word_white_list | 4lwコマンドのホワイトリスト。 | 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+）を実行している場合は、パフォーマンスの向上が望めるため、有効にすることをお勧めします。
3つのノードを持つクォーラムの設定の例は、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コマンドには、デフォルト値がconf,cons,crst,envi,ruok,srst,srvr,stat,wchs,dirs,mntr,isro,rcvr,apiv,csnp,lgif,rqld,ydldのホワイトリスト設定four_letter_word_white_listがあります。
テレネットまたは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: パスごとのサーバーのウォッチに関する詳細情報をリストします。これにより、関連付けられたセッションを持つパス（znodes）のリストが出力されます。ウォッチの数によっては、この操作が高コスト（すなわち、サーバーのパフォーマンスに影響を与える）になる可能性があるため、注意して使用してください。
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- 複数のリクエストを読むためのサポート。デフォルト:1filtered_list- ノードの種類（エフェメラルまたは永続）によって結果をフィルタリングするリストリクエストのサポート。デフォルト:1check_not_exists- ノードが存在しないことを主張するCheckNotExistsリクエストのサポート。デフォルト:0create_if_not_exists- ノードが存在しない場合にノードを作成しようとするCreateIfNotExistsリクエストのサポート。存在する場合、変更は適用されずZOKが返されます。デフォルト:0remove_recursive- ノードとそのサブツリーを削除するRemoveRecursiveリクエストのサポート。デフォルト: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を実行します。例えば：
- スナップショットを構成された
keeperのあるClickHouseサーバーノードにコピーするか、ZooKeeperの代わりにClickHouse Keeperを起動します。スナップショットはすべてのノードに保存される必要があります。そうでない場合、空のノードが早く、いずれかのノードがリーダーになる可能性があります。
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フォルダのバックアップを作成します。 - 使用するすべてのノードでクラスターを再設定します。
- 選択したノードに
rcvrという4文字コマンドを送信し、そのノードをリカバリーモードに移行するか、選択したノードでKeeperインスタンスを停止し、--force-recovery引数をつけて再起動します。 - 1つずつ新しいノードでKeeperインスタンスを起動し、次のノードを起動する前に
mntrがzk_server_stateに対してfollowerを返すことを確認します。 - リカバリーモードの間、リーダーノードは
mntrコマンドに対してエラーメッセージを返し、新しいノードとクォーラムを達成するまでクライアントやフォロワーからのリクエストを拒否します。 - クォーラムが達成されると、リーダーノードは通常の動作モードに戻り、すべてのリクエストをRaft-verifyを使用して受け入れ、
mntrは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に設定されているKeeperは（デフォルト値はtrue）、すべてのタイプのディスクに対していくつかの保証を満たすことができません。
現在、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. Configure Nodes with Keeper settings
-
3つのホスト（
chnode1、chnode2、chnode3）に3つのClickHouseインスタンスをインストールします。（ClickHouseをインストールする詳細については、クイックスタートを参照してください。） -
各ノードで、ネットワークインターフェイスを介した外部通信を許可するために、以下のエントリを追加します。
-
すべてのサーバーに以下のClickHouse Keeper構成を追加し、各サーバーの
<server_id>設定を更新します。chnode1では1、chnode2では2などです。上記で使用された基本設定は以下の通りです：
Parameter Description Example tcp_port Keeperのクライアントが使用するポート 9181（デフォルトは2181、Zookeeperと同じ） 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つのレプリカのみを持つシンプルなクラスターを構成します。第三のノードは、ClickHouse Keeperの要件を満たすためにクォーラムを達成するために使用されます。
chnode1とchnode2で設定を更新します。以下のクラスターは、各ノードに1つのシャードを定義しており、合計で2つのシャードがあり、レプリケーションはありません。この例では、データの一部は1つのノードに、残りは別のノードに配置されます：パラメータ 説明 例 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で： -
-
Distributedテーブルを作成して、2つのシャード上のデータを表現できます。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があります。これにより、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）にデータを挿入
- 二番目のノード（例：
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回に1つのサーバーを追加したり、削除したりする方法があります。したがって、構成の各変更（
joiningの各部分、leavingの各部分）は別々に決定する必要があります。したがって、大量の再構成は、エンドユーザーには誤解を招く可能性があるため、利用できません。サーバーのタイプ（参加者/学習者）を変更することもできません。これはNuRaftによってサポートされていないため、サーバーを削除して追加する必要があるため、これも誤解を招くことになります。
-
戻り値の
znodestatを使用することはできません。 -
from_versionフィールドは使用されていません。from_versionを設定したすべてのリクエストは拒否されます。 これは、/keeper/configが仮想ノードであるため、永続ストレージには保存されず、各リクエストに対して指定されたノード設定をオンザフライで生成されるためです。 この判断はNuRaftがすでにこの構成を保存しているため、データの重複を避けるために行われました。 -
ZooKeeperとは異なり、
syncコマンドを送信することによってクラスターの再構成を待つ方法はありません。 新しい構成は 最終的に 適用されますが、時間的保証はありません。 -
reconfigコマンドはさまざまな理由で失敗する可能性があります。クラスターの状態を確認し、更新が適用されたかどうかを確認できます。
シングルノードKeeperをクラスターに変換する
時には、実験的なKeeperノードをクラスターに拡張する必要があります。以下は、3ノードクラスターのための手順の図です：
- 重要: 新しいノードは、現在のクォーラムより少ないバッチで追加する必要があります。そうしないと、それらの間でリーダーが選出されます。この例では1つずつ追加します。
- 既存のKeeperノードは、
keeper_server.enable_reconfiguration構成パラメータがオンになっている必要があります。 - Keeperクラスターの完全な新しい構成を使用して2番目のノードを起動します。
- 起動後、最初のノードに新しいノードを追加します（
reconfigを使用）。 - 次に、3番目のノードを起動し、
reconfigを使用して追加します。 - 新しいKeeperノードを追加して、
clickhouse-serverの設定を更新し、変更を適用するために再起動します。 - 最初のノードのraft設定を更新し、オプションで再起動します。
このプロセスに慣れるために、こちらのサンドボックスリポジトリを参照してください。
サポートされていない機能
ClickHouse KeeperはZooKeeperと完全に互換性を持つことを目指していますが、現在実装されていない機能がいくつかあります（開発は進行中です）：
createはStatオブジェクトを返すことをサポートしていません。createは TTLをサポートしていません。addWatchはPERSISTENTウォッチで機能しません。removeWatchとremoveAllWatchesはサポートされていません。setWatchesはサポートされていません。CONTAINERタイプのznodesを作成することはサポートされていません。SASL認証はサポートされていません。
