ZooKeeper CLI(zkCli.sh)の使い方

目次

はじめに

Apache ZooKeeperは、分散システムにおける設定情報の共有やリーダー選出などを担う、信頼性の高いコーディネーションサービスです。そのZooKeeperを直接操作・監視できる便利なツールが、公式のコマンドラインインターフェース「ZooKeeper CLI(zkCli.sh)」です。

「構成変更を試したい」「ノードの状態をリアルタイムで確認したい」「アプリケーションの挙動を調査したい」——こうした場面で、ZooKeeper CLI はGUIツールでは得られない柔軟性と即応性を提供します。

この記事では、ZooKeeper CLIの基本的な使い方から、実務で役立つ応用コマンドまでを丁寧に解説します。ZooKeeperを学び始めた方から、日常的に運用・障害対応に関わるエンジニアの方まで、幅広く参考にしていただければと思います。

ZooKeeper CLIとは?ZooKeeperと対話する公式ツール

ZooKeeper CLI(zkCli.sh)は、Apache ZooKeeperと直接対話するための公式コマンドラインツールです。ZooKeeperサーバーに接続し、znodeの作成・更新・削除・監視など、さまざまな操作をコマンドベースで実行できます。

CLI形式のため、GUIツールにはないリアルタイム性と柔軟性があり、次のような場面で特に重宝します。

  • ノードの作成や削除といった動作検証・デバッグ
  • アプリケーションの設定値やメタデータの確認・変更
  • ZooKeeperクラスタの接続状況や状態の手動確認

ZooKeeper CLIは、ZooKeeperをインストールすると標準で同梱されており、特別な設定や追加ツールなしですぐに使用できます。初学者から運用担当者まで、ZooKeeperの動作を深く理解するうえで欠かせないツールです。

ZooKeeper CLI の起動手順

ZooKeeper CLI は、ZooKeeperサーバーに接続してznodeの操作や状態確認を行うためのコマンドラインツールです。起動スクリプトとして zkCli.sh(Windowsでは zkCli.cmd)が用意されており、ZooKeeperのインストールディレクトリ内の bin 配下に格納されています。

基本的な起動コマンド

ZooKeeper CLI を起動するには、次のようにコマンドを実行します。

bin/zkCli.sh

デフォルトの接続先は localhost:2181 です。接続に成功すると、次のようなプロンプトが表示されます。

[zk: localhost:2181(CONNECTED) 0]

この状態でコマンドを入力すれば、ZooKeeperノードの操作や状態確認が可能になります。

また、zkCli.sh に引数としてコマンドを渡すことで、CLIを起動せずに単発でノード操作を実行することも可能です(バッチ処理やスクリプトに便利です)。

bin/zkCli.sh create /myapp "hello"

オプション一覧

zkCli.sh 実行時には、以下のようなオプションを指定することで、接続先や動作を柔軟に制御できます。

オプション説明
-serverZooKeeperサーバーのアドレス。カンマ区切りで複数ホストのクラスタ指定も可能。デフォルトはlocalhost:2181
-timeout接続タイムアウトのミリ秒。デフォルトは30000
-r読み取り専用モードへの移行を許可
-client-configurationクライアント設定(ZKClientConfig)のプロパティファイルパスを指定
-waitforconnectionZooKeeperへの接続が確立するまで待機してからコマンド実行

クライアント設定(ZKClientConfig)については、以下の記事で詳しく解説しています。

ZooKeeper CLI コマンド一覧

ZooKeeper CLI では、znodeの操作や監視、アクセス制御、構成変更といった幅広い操作をコマンドで実行できます。ここでは、実務でよく使われる代表的なコマンドから、知っておくと便利な補助的コマンドまで、カテゴリごとに整理して紹介します。

ノード操作関連

znode の作成・更新・削除・取得など、基本的なリソース操作に関するコマンドです。

コマンド説明
create <path> [data] [acl]ノードを作成。-e:一時ノード、-s:連番ノード、-c:コンテナノード、-t ttl:TTLノード
delete <path>ノードを削除(空でないノードは削除不可)。-v version:対象ノードバージョン
deleteall <path>ノード配下を再帰的に削除。-b batch size:1回あたりの削除操作数
get <path>ノードのデータを取得。-s:ノード状態を表示、-w:ノードの変更を監視
getAllChildrenNumber <path>ノード配下の子ノードの数をすべて取得
getEphemerals <path>現在のセッションで作成されたすべての一時ノードを取得
ls <path>ノード配下の子ノード一覧を取得。-s:ノード状態を表示、-w:ノードの変更を監視、-R:再帰的に取得
set <path> <data>ノードのデータを更新。-s:ノード状態を表示、-v version:対象ノードバージョン
stat <path>ノードの状態(バージョン、タイムスタンプ等)を取得、-w:ノードの変更を監視
sync <path>リーダーとフォロワー間でノードのデータを同期

get -w などの watch は「1回限り」の通知です。永続的な監視には addWatch を使用しましょう。

アクセス制御(ACL)関連

ノードごとのアクセス制限(ACL)を確認・設定するためのコマンド群です。セキュリティの強化やユーザ管理に欠かせません。

コマンド説明
addauth <scheme> <auth>ACLに承認されたユーザを追加
getAcl <path>ノードのACLを取得。-s:ノードの状態を表示
setAcl <path> <acl>ノードのACLを更新。-s:ノードの状態を表示、-v version:対象ノードバージョン、-R:再帰的に更新
whoami現在のセッションに追加されたすべての認証情報を取得

モニタリング・監視関連

ZooKeeper上の変更をリアルタイムで検知するための監視(watch)に関するコマンドです。動作確認や障害調査で重宝します。

コマンド説明
addWatch <path>ノードの監視を開始。-m:監視モード(PERSISTENT または PERSISTENT_RECURSIVE)
printwatches <on|off>ノードの変更時の表示オン/オフを切り替え
removewatches <path>ノードの監視を停止。-c:子ノードのみ、-d:自身のノードのみ、-a:子ノードと自身のノード両方、-l:サーバ未接続時にローカルで削除

クォータ(quota)関連

ノードごとにリソースの上限(ノード数・データサイズ)を設定・確認・削除するためのコマンドです。大規模環境での運用時に有用です。

コマンド説明
delquota <path>クォータを削除。-n:ノード数上限(ソフトクォータ)、-b:データサイズ上限(ソフトクォータ)、-N:ノード数上限(ハードクォータ)、-B:データサイズ数上限(ハードクォータ)
listquota <path>クォータを表示
setquota <path>クォータを設定。-n val:ノード数上限(ソフトクォータ)、-b val:データサイズ上限(ソフトクォータ)、-N val:ノード数上限(ハードクォータ)、-B val:データサイズ数上限(ハードクォータ)

セッション・接続関連

ZooKeeperとの接続状態を管理するための基本的なコマンドです。

コマンド説明
connect <host:port>ZooKeeperサーバーに接続
close現在のセッションを終了

設定関連

ZooKeeperクラスタの構成情報(アンサンブル)を表示・変更するためのコマンドです。

コマンド説明
configアンサンブル構成を表示。-s/zookeeper/configのノード状態を表示、-w:構成の変更を監視、-c:クライアントからの接続文字列を表示
reconfigアンサンブル構成を動的に変更。-s/zookeeper/configのノード状態を表示、-v version:対象構成バージョン、-file path:設定ファイルパス、-members servers:全構成サーバ、-add servers:追加構成サーバ、-remove serverID[,...]*:削除構成サーバ

※reconfigコマンドのサーバ(servers)の指定方法
server.<positive id> = <address1>:<port1>:<port2>[:role];[<client port address>:]<client port>**

補助的なユーティリティ

CLIの操作履歴やバージョン確認など、日常的な作業を効率化するための補助コマンドです。

コマンド説明
historyこれまで実行したコマンド履歴を表示
redo <cmdno>指定番号の履歴コマンドを再実行
quitZooKeeper CLI を終了
versionZooKeeper CLI のバージョンを表示

ZooKeeper CLI では、ノードのデータは内部的にはバイト列で管理されていますが、CLI上では文字列として入力・表示することができます。

まとめ:ZooKeeper CLI を使いこなして、ZooKeeperを自在に操作しよう

ZooKeeper CLI(zkCli.sh)は、Apache ZooKeeper を深く理解し、柔軟に操作するための強力なツールです。GUIでは見えにくいノードの状態やセッションの振る舞いも、CLIを通じてリアルタイムに確認・制御できます。

特に、障害調査や設定の検証、動作確認といった場面では、ZooKeeper CLI の基本的な操作を習得しておくことが大きな武器になります。

本記事で紹介したコマンドやオプションを参考に、まずは手元の環境でいくつか試してみることをおすすめします。CLIを自在に使いこなせるようになれば、ZooKeeper の信頼性をさらに引き出せるはずです。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!
目次