サーチヘッドで作成されたナレッジオブジェクトがSplunkクラスタ環境で配布される仕組み

Tips & Tricks June 25, 2026 今井浩平 (Kohei Imai)

注：こちらの記事の内容は、Splunk Enterprise環境を前提にして書かれています。Splunk Cloudでは利用することのできない機能についての記載があります。

1. ナレッジオブジェクト(Knowledge Object)とは

Splunkでは、サーチヘッドへログインしたユーザーが作成したサーチ(セーブドサーチ)、ルックアップテーブル、ダッシュボードなど、ランタイム時に作成・変更される設定を「ナレッジオブジェクト」と呼びます。これらをクラスタ内で適切に配布することにより、ユーザーはどのインスタンスからアクセスしても、必要に応じて自身のナレッジオブジェクトを利用することが可能となります。

これらのオブジェクトについては、Splunkアドミンが適切に管理する必要があります。設定された上限値のサイズを超えるナレッジオブジェクトバンドルは、エラーとなり正常に配布されません。これが原因で様々な運用上の問題を引き起こすため、十分な注意が必要です。

2. 配布される範囲

作成されたナレッジオブジェクトは、以下の2つの宛先に配布されます。

サーチヘッドクラスタ(SHC)メンバー：他のサーチヘッド同士での設定同期。
サーチピア(インデクサー)：検索処理を実行するために必要な設定の配布。

3. コンフィグレーションレプリケーション(Configuration Replication)

サーチヘッドが自身のもつナレッジオブジェクトを、他の サーチヘッドクラスタメンバー へ配布することを「コンフィグレーションレプリケーション」と呼びます。

役割：クラスタ内のすべてのサーチヘッドで、ナレッジオブジェクトの状態を同一に保ちます。
仕組み：SHCキャプテンがオーケストレーターとして機能し、各メンバーが行ったランタイム時の変更を全メンバーへ同期します。
注意点：Splunk Web、CLI、REST API経由の変更は自動同期されますが、設定ファイルを直接編集した場合は同期されません。その場合はDeployerによる配布が必要となります。

4. ナレッジバンドルリプリケーション(Knowledge Bundle Replication)

サーチヘッドメンバーが、検索の実行に必要なナレッジオブジェクトを サーチピア(インデクサー) に配布することを「ナレッジバンドルリプリケーション」と呼びます。

役割：インデクサー側でルックアップの適用や権限の照合を行うために、最新の設定を届けます。
SHCにおける挙動：サーチヘッドクラスタ環境においては、SHCキャプテンのみがサーチピアに対してこの配布処理を行います。他のメンバーは配布処理には参加しません ¹ 。
注意点：配布可能なバンドルにはサイズの上限値が設定されています。これを超えるとエラーとなり、配布する事ができません。上限値はdistsearch.confの[replicationSettings]配下でmaxBundleSizeにより変更する事ができます。

5. スプランクディレクトリ内での保存形式と確認方法

配布されるナレッジオブジェクトは、サーチヘッドで作成(アーカイブ)され、インデクサーへ転送された後、それぞれの役割に応じたディレクトリに一時保存されます。

1. サーチヘッド(送信側)での保存先

キャプテンがインデクサーへ配布するために作成した最新のバンドルファイルが置かれます。

ディレクトリ：$SPLUNK_HOME/var/run/
ファイル名： <GUID>-<タイムスタンプ>.bundle

2. インデクサー(受信側)での保存先

サーチヘッドから受け取ったバンドルファイルは、インデクサー内の以下のディレクトリに展開・保存されます。

ディレクトリ：$SPLUNK_HOME/var/run/searchpeers/
構造：各サーチヘッド(送信元)のGUIDごとにサブディレクトリが作成され、その中に.bundleファイルや展開された設定ファイルが保持されます。
確認のポイント：インデクサー側でls -laを実行し、保存されている.bundleファイルのタイムスタンプを確認することで、最新の設定が正しく届いているか(同期が止まっていないか)を判断できます。

3. ファイル形式と中身の確認方法

これらのファイルは tar形式 で圧縮されています。

確認方法：通常のtarコマンドを使用して、ファイルを展開することなく中身のリストを確認することが可能です。
- コマンド例：tar -tvf <ファイル名>.bundle | sort -nk3
- これにより、どのファイルがバンドルサイズを肥大化させているかを特定し、調査に役立てることができます。

6. 配布ステータスと設定の確認方法

運用管理のため、以下のCLIコマンドを用いて配布の正常性を確認することが推奨されます。

Bundle replication statusの確認：splunk show bundle-replication-status 各サーチピアへの配布が成功(succeeded)しているか、あるいは進行中かを確認できます。

例：

splunk@master1:/home/splunk$ splunk show bundle-replication-status 
WARNING: Server Certificate Hostname Validation is disabled. Please see server.conf/[sslConfig]/cliVerifyServerName for details. 
Your session is invalid.  Please login. 
Splunk username: xxxxx 
 ***Knowledge Bundle Replication Cycle Status*** 

Replication Policy: classic 
Replication In Progress: 0 
Bundle ID: master1-1777254973 
Cycle ID: BF3491A0-xxxx-4B87-9280-7560B3B27CF7 
Current Bundle: /opt/splunk/var/run/master1-xxx7254973.bundle 
Current Replication Start Time: 1778822282 
Peers: 
Peer URI: https://10.xxx.x.xxx:8089 
Peer State: succeeded 
Peer URI: https://10.xxx.x.xxx:8089 
Peer State: succeeded 
Peer URI: https://10.xxx.x.xx:8089 
Peer State: succeeded

Bundle replication configの確認：splunk show bundle-replication-config 現在の maxBundleSize (上限値)やレプリケーションポリシーなどの設定値を確認できます。

例：

splunk show bundle-replication-config 
WARNING: Server Certificate Hostname Validation is disabled. Please see server.conf/[sslConfig]/cliVerifyServerName for details. 
 ***Knowledge Bundle Replication Configuration*** 

Replication Policy: classic 
Replication Threads: 2 
Max Bundle Size: 2147483648 bytes 
Warn Max Bundle Size Percentage: 0.75% 
Status Queue Size: 5 
Replication Period: 60s 
File Size Warning Threshold: 524288000 bytes 
Connection Timeout: 60s 
Send Timeout: 60s 
Receive Timeout: 60s

7. ナレッジバンドルの異常が引き起こす問題例

例1：新たに作成されたRoleが特定のインデックスをサーチできない

症状：authorize.confで適切に権限を設定したにもかかわらず、非管理者ユーザーが特定のインデックスを検索すると結果が0件になる。
原因：ナレッジバンドルのサイズがmaxBundleSizeを超過したため、インデクサーへの配布がブロックされている。その結果、インデクサー側が古い権限設定(バンドル)を保持し続けている。
解決方法：不要なルックアップファイルを削除するか、distsearch.confのmaxBundleSizeを引き上げ、同時にインデクサー側のserver.confで max_content_lengthを調整します。

例2：CSVルックアップのサイズが肥大化してサーチが実行終了できない

症状：検索が開始されない(Pending状態)、あるいは検索実行中にタイムアウトが発生する。
原因：数GB規模の巨大なCSVファイルをoutputlookup等で頻繁に更新している。これにより、同期処理がネットワーク帯域やディスクI/Oを占有し、クラスタ全体のコンフィグレーションレプリケーションが停滞(Stall)している。
解決方法：問題となっている保存済み検索を一時停止し、$SPLUNK_HOME/var/run/splunk/lookup_tmp/内の古い一時ファイルを削除します。根本対策として、巨大なファイルをreplicationDenylistで配布対象から除外することを検討します。

8. エラーの検索方法

同期や配布に関する異常を検知するためには、サーチヘッドにおいて以下の_internalログを調査することが有効です。

【検索文】

index=_internal sourcetype=splunkd
component=DistributedBundleReplicationManager log_level=WARN

ログ内に「Discard the candidate bundle as its size exceeds maxBundleSize」という警告が記録されている場合、サイズ制限による配布失敗が確定となります。

9.まとめ

ナレッジバンドルがSplunkクラスタ環境内でどのように配布されているかを理解し、定期的にその状態を確認することで、クラスタ全体の状態を良好に保つことができます。スプランクを分散クラスタ構成で利用することで、その冗長性を最大限に活用するためにも、重要な役割を果たすナレッジバンドルの仕組みを理解し、充実したスプランカーライフを送るのに役立てていただければと思います。

Splunkドキュメント「Troubleshoot knowledge bundle replication」

Style

two-column