【Apache ZooKeeper】ZKClientConfigとは？

2025年6月13日2025年7月4日

Apache ZooKeeper を本番環境で安全に利用するためには、クライアントとサーバ間の通信を適切に構成することが重要です。特に認証（SASL/Kerberos）や暗号化通信（SSL/TLS）を行う環境では、細かな設定が求められます。

従来、これらの設定はJavaのシステムプロパティで管理されていましたが、ZooKeeper 3.5以降ではZKClientConfigクラスが導入され、コードベースでより柔軟な接続管理が可能になりました。

この記事では、ZKClientConfig の基本的な役割と構成方法、Apache Curator を使った応用、そして実装時に注意すべきポイントまでを実例を交えて解説します。

ZKClientConfigとは？

ZKClientConfig は、ZooKeeper クライアントの接続に関する設定を管理するためのクラスで、ZooKeeper 3.5 から導入されました。これにより、セキュリティや接続の構成をコードレベルで柔軟に制御できるようになっています。

ZKClientConfig が提供する主要な機能は以下のとおりです。

SASL（Kerberos）認証の構成
SSL/TLS を用いた暗号化通信の設定
ソケットファクトリなどのクライアント側詳細設定

従来は Java のシステムプロパティでこれらを指定していましたが、ZKClientConfig を使うことで、アプリケーション内部から構成を一元的に制御でき、外部依存を減らすことが可能になります。

よく使われる設定項目

ZKClientConfig では、セキュリティや接続に関するさまざまな設定をプロパティとして定義できます。特に以下のような項目は、SASL認証やSSL/TLS通信を構成する際によく使われます。

プロパティ名	内容	例
zookeeper.sasl.client	SASL認証の有効化	true
zookeeper.sasl.client.username	認証ユーザー名（任意）	zookeeper
zookeeper.client.secure	SSL/TLS接続の有効化	true
zookeeper.ssl.keyStore.location	キーストアのパス	/path/to/keystore.jks
zookeeper.ssl.keyStore.password	キーストアのパスワード	changeit
zookeeper.ssl.trustStore.location	トラストストアのパス	/path/to/truststore.jks
zookeeper.ssl.trustStore.password	トラストストアのパスワード	changeit

これらのプロパティは、ZKClientConfig インスタンスに setProperty() メソッドで設定することで、プログラム上から明示的に構成できます。

すべての利用可能な設定項目に関しては、ZooKeeper公式ドキュメントを参照してください。

実践：Javaコードによる設定例

ここでは、ZKClientConfig を使って ZooKeeper クライアントの設定を Java コードで行う方法を紹介します。セキュリティ要件に応じて、SASL認証やSSL/TLS通信を設定することが可能です。

SASL認証の有効化

Kerberos を用いた認証を行う場合の基本構成です。

ZKClientConfig config = new ZKClientConfig();
config.setProperty("zookeeper.sasl.client", "true");
config.setProperty("zookeeper.sasl.client.username", "zookeeper");

ZooKeeper zk = new ZooKeeper(
    "zk.example.com:2181",
    30000,
    event -> {},
    false,
    config
);

Kerberos 認証を有効にするには、別途 JAAS 設定ファイルの用意とチケットの取得（kinit）が必要です。

SSL/TLS による通信の暗号化

ZooKeeper サーバと安全に通信するための TLS 構成例です。

ZKClientConfig config = new ZKClientConfig();
config.setProperty("zookeeper.client.secure", "true");
config.setProperty("zookeeper.ssl.keyStore.location", "/opt/app/keystore.jks");
config.setProperty("zookeeper.ssl.keyStore.password", "changeit");
config.setProperty("zookeeper.ssl.trustStore.location", "/opt/app/truststore.jks");
config.setProperty("zookeeper.ssl.trustStore.password", "changeit");

ZooKeeper zk = new ZooKeeper(
    "zk.example.com:2281",  // SSL/TLS 用に別ポートを使用
    30000,
    event -> {},
    false,
    config
);

このとき、ZooKeeperサーバ側も TLS に対応している必要があります。

外部設定ファイルの活用

複数の設定を外部ファイルにまとめておきたい場合は、以下のように .properties ファイルを活用できます。

zookeeper.sasl.client=true
zookeeper.sasl.client.username=zookeeper

ZKClientConfig config = new ZKClientConfig("zk-config.properties");

ZooKeeper zk = new ZooKeeper(
    "zk.example.com:2181",
    30000,
    event -> {},
    false,
    config
);

設定ファイルのパスは、クラスパス上または絶対パスで指定可能です。

Apache Curatorとの連携方法

Apache ZooKeeper のラッパーライブラリである Apache Curator を利用している場合も、ZKClientConfig によるセキュアな接続設定は有効です。Curatorでは、ビルダーパターンの中で zkClientConfig() を指定することで、ZooKeeperクライアントと同様の構成が可能です。

以下はその実装例です。

ZKClientConfig config = new ZKClientConfig();
config.setProperty("zookeeper.sasl.client", "true");
config.setProperty("zookeeper.sasl.client.username", "zookeeper");

CuratorFramework client = CuratorFrameworkFactory.builder()
    .connectString("zk.example.com:2281")
    .sessionTimeoutMs(15000)
    .zkClientConfig(config)  // ZKClientConfigを適用
    .retryPolicy(new ExponentialBackoffRetry(1000, 3))
    .build();

このように、Curator を使う開発環境でも ZKClientConfig を活用することで、セキュリティ要件に対応した構成をシンプルに管理できます。

注意点とトラブル事例

ZKClientConfig を使ったセキュアな構成は強力ですが、設定ミスやサーバとの不整合により接続トラブルが発生することがあります。ここでは、よくある問題とその原因を整理します。

❗ ケース1：接続エラー時の切り分けポイント

接続失敗時は、以下の点を順に確認することで原因の特定がスムーズになります。

SSL 設定ミス
→ ZooKeeper サーバが SSL ポート（例：2281）を使っているか確認しましょう。クライアントが通常ポート（2181）に接続していると通信できません。
認証エラー（例：GSSException）
→ Kerberos チケットの取得忘れや、JAAS 設定ファイルのパスミスが主な原因です。環境変数 KRB5_CONFIG や java.security.auth.login.config の設定も確認しましょう。

❗ ケース2：クライアントとサーバの設定不一致

セキュリティ関連の設定が一方にしか適用されていない場合、通信が確立できないことがあります。

クライアントが SSL を要求しているが、サーバが非SSL
→ サーバ側も clientPortAddress や secureClientPort の設定が必要です。
サーバが SASL（Kerberos）認証を要求しているが、クライアントが無設定
→ クライアント側にも zookeeper.sasl.client=true の設定が必要です。

接続に失敗した場合は、ZooKeeper のクライアント・サーバ両方のログを確認することがトラブルシュートの第一歩です。サーバログに SaslServerCallbackHandler や SslSocket 関連の例外が出ていれば、それがヒントになります。