Contents
Grafana プラグインの公式インストール手順
Grafana に ClickHouse データソースを組み込む第一歩は、公式が提供するプラグインを正しく導入することです。最新版を使用すればバグ修正や新機能が自動的に取り込まれ、安定した接続が保証されます。本章では、Grafana Marketplace からのインストールと、外部ネットワークに制限がある環境向けの手動インストール方法を順番に解説します。
Marketplace からのインストール
Marketplace に掲載されている公式プラグインは、GUI と CLI のいずれかで簡単に導入できます。ここでは両方の手順と、インストール後に必要な確認ポイントをまとめます。
GUI でのインストール
Grafana の管理画面から操作するだけで完了します。
- 管理者権限で Grafana にログインし、左メニューの Configuration → Plugins を開く。
- 検索ボックスに「ClickHouse」と入力し、表示された grafana-clickhouse-datasource の Install ボタンをクリックする。
CLI でのインストール
自動化スクリプトやサーバー構築時に便利です。
|
1 2 3 4 5 6 |
# プラグインの取得とインストール grafana-cli plugins install grafana-clickhouse-datasource # インストールが完了したら Grafana サービスを再起動してプラグインを有効化 sudo systemctl restart grafana-server |
バージョン確認
インストール後に実際のバージョンが期待通りかどうかは次のコマンドで確かめられます。
|
1 2 |
grafana-cli plugins list | grep grafana-clickhouse-datasource |
表示例: grafana-clickhouse-datasource 2.3.0 → インストール成功です。
ポイント
- GUI と CLI のどちらでもインストール手順は同一のプラグインを取得します。
- 再起動は「1 回だけ」行えば十分で、重複して記載しないようにしてください。
手動インストール（zip / バイナリ）
社内ネットワークが外部と切り離されている場合や、特定バージョンを固定したいときは手動で zip ファイルを取得します。公式ダウンロード URL は常に最新情報を確認してください。
| 手順 | 内容 |
|---|---|
| 1 | https://grafana.com/api/plugins/grafana-clickhouse-datasource/versions/latest/download から zip をダウンロード（公式ページの「Download」リンクが推奨） |
| 2 | /var/lib/grafana/plugins ディレクトリに解凍し、所有者と権限を grafana:grafana に設定 |
| 3 | sudo systemctl restart grafana-server で Grafana を再起動 |
| 4 | GUI の Configuration → Plugins 画面で「Installed」タブに表示されることを確認 |
手動方式でも、インストール後は上記のバージョン確認コマンドで正しく認識されたかチェックしてください。
接続情報と読み取り専用ユーザーの設定
ClickHouse へ安全に接続するためには、必要なパラメータを整理し、最小権限の読み取り専用ユーザーを作成しておくことが不可欠です。本章では、接続に必須となる項目と、実際にロール・ユーザーを定義する SQL スクリプトを紹介します。
必要な接続パラメータ一覧
以下の表は Grafana から ClickHouse に接続する際に最低限必要になる情報です。各項目の概要と推奨設定例も併記しています。
| 項目 | 説明 | 設定例 |
|---|---|---|
| ホスト | ClickHouse が待ち受けている IP アドレスまたは DNS 名 | clickhouse.example.com |
| ポート | HTTP (8123) または Native (9000) のいずれかを選択 | 8123（HTTP） / 9000（Native） |
| データベース名 | 使用対象のデータベース | metrics_db |
| ユーザー／パスワード | 認証情報。読み取り専用ユーザーを推奨 | grafana_read / ******** |
| TLS/SSL | 暗号化が必要な場合は有効にする | true（証明書は別途設定） |
最小権限ユーザー作成例（SQL スクリプト）
以下のスクリプトは、特定データベースに対して SELECT のみを許可し、その他の操作を排除したロールとユーザーを作成します。実行前に管理者権限で ClickHouse にログインしてください。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
-- 1. 読み取り専用ロールを作成 CREATE ROLE grafana_read_role; -- 指定データベース全テーブルに対して SELECT 権限だけ付与 GRANT SELECT ON metrics_db.* TO grafana_read_role; -- 2. ユーザーを作成し、ロールを割り当てる CREATE USER grafana_read IDENTIFIED WITH plaintext_password BY 'StrongPassword123'; GRANT ROLE grafana_read_role TO grafana_read; -- 3. 任意で追加設定（例：同時クエリ数上限・IP 制限） ALTER USER grafana_read SETTINGS max_concurrent_queries = 10; |
ポイント
-SELECT権限のみ付与することで、データの取得以外は実行できません。
- 必要に応じてテーブル単位で権限を絞り込むと、更なるセキュリティ向上が期待できます。
HTTP と Native の比較と選択指針
ClickHouse への接続方式は大きく HTTP と Native (TCP) に分かれます。どちらが適切かは、ネットワーク構成やパフォーマンス要件に応じて判断します。
プロトコル比較表
| 項目 | HTTP（REST） | Native（TCP） |
|---|---|---|
| 通信方式 | テキストベースの POST/GET、標準ポート 8123 | バイナリプロトコル、標準ポート 9000 |
| TLS 対応 | https:// がそのまま利用可能 |
TLS は別途設定（clickhouse-client --secure） |
| レイテンシ | ヘッダー処理分だけやや高め | バイナリ転送に最適化され低レイテンシ |
| クエリサイズ上限 | デフォルト 256 MiB（設定で変更可） | 同様にサーバ側 max_query_size に依存 |
| Grafana プラグイン実装 | 「ClickHouse (HTTP)」として提供 | 「ClickHouse (Native)」がデフォルト |
| 適用シーン | ファイアウォールで HTTP のみ許可、外部クラウド連携 | 高頻度・大量データ取得、内部 LAN 環境 |
選択のポイント
- TLS が必須かつポート制限が厳しい場合 →
https://を利用できる HTTP を選択。 - リアルタイム監視で多数のクエリを高速に投げる必要がある → バイナリ転送の Native が有利です。
- 既存インフラがプロキシやロードバランサ経由で HTTP のみ許可 → 設定が簡単な HTTP を採用してください。
Grafana UI での ClickHouse データソース定義手順
GUI からデータソースを作成すれば、接続テストまで数クリックで完了します。本章では必須項目と推奨設定例を示し、実際に「Test & Save」まで行う流れを解説します。
必須項目と推奨設定（Native 接続例）
以下は Native プロトコルでデータソースを作成する際の代表的なフィールドです。各項目の意味と推奨値を表にまとめました。
| フィールド | 推奨設定例 |
|---|---|
| URL | clickhouse.example.com:9000 |
| Database | metrics_db |
| User | grafana_read |
| Password | （環境変数またはシークレットで管理） |
| TLS / SSL | Enable TLS（証明書は Grafana の「Certificates」設定でアップロード） |
| Timeout (seconds) | 30（ネットワーク遅延が予想される場合は増やす） |
注意
- GUI ではパスワード入力欄が暗号化されたまま保存されます。機密情報は環境変数経由で設定することを推奨します。
接続テストと保存
- データソース画面下部の Test & Save ボタンをクリック。
- 「Data source is working」メッセージが表示されたら接続成功です。エラーが出た場合は前項で設定したパラメータやネットワーク制限を再確認してください。
YAML によるデータソースプロビジョニング
インフラコードとして Grafana のデータソースを管理したい場合、provisioning 機能が有効です。YAML ファイルに設定を書き出すことで、GitOps パイプラインから安全かつ自動的に適用できます。
プロビジョニング YAML の基本構造
以下は ClickHouse データソースをプロビジョニングする際の最小構成例です。機密情報は環境変数で外部化しています。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
apiVersion: 1 datasources: - name: ClickHouse type: grafana-clickhouse-datasource access: proxy # Grafana がプロキシとして動作 url: clickhouse.example.com:9000 user: ${GF_CLICKHOUSE_USER} secureJsonData: password: ${GF_CLICKHOUSE_PASSWORD} jsonData: database: metrics_db tlsSkipVerify: false # 本番環境では必ず false に設定 editable: false |
- 配置場所：
/etc/grafana/provisioning/datasources/datasources.yaml（Docker コンテナの場合は同等のパス） - 権限設定：
chmod 640 datasources.yaml && chown grafana:grafana datasources.yaml
設定反映と再読み込み方法
YAML を変更しただけで即座に Grafana に反映させるには、管理者権限の API エンドポイントを呼び出します。
|
1 2 3 |
curl -X POST -u admin:YOUR_ADMIN_PASSWORD \ http://localhost:3000/api/admin/provisioning/reload |
このコマンドは Grafana プロセスの再起動なしでプロビジョニング設定をリロードでき、CI/CD パイプラインから安全に適用できます。
接続テスト・エラー対処・ダッシュボード作成・セキュリティベストプラクティス
実運用では接続確認やトラブルシューティング、そして安全な可視化環境の構築が重要です。本章では代表的なエラーとその解決策、基本的なパネル作成例、さらにセキュリティ強化策をまとめます。
接続テストの実施方法
| 方法 | 説明 |
|---|---|
| Grafana UI | データソース設定画面の Test & Save ボタンで即時確認。 |
| API 呼び出し | GET /api/datasources/proxy/:id/_health でヘルスチェック（:id はデータソース ID）。 |
| CLI (curl) | curl -H "Authorization: Bearer <admin-token>" http://localhost:3000/api/datasources/proxy/1/_health |
主なエラーメッセージと解決策
| エラー | 原因例 | 推奨対処 |
|---|---|---|
invalid username or password |
認証情報のタイプミス、ロールに SELECT 権限が無い | ユーザー名・パスワードを再確認し、GRANT SELECT が付与されているか確認。 |
connection timed out |
ファイアウォールやセキュリティグループでポートが閉じている | ClickHouse の 8123/9000 ポートが開放されているかネットワーク管理者に問い合わせる。 |
TLS handshake failed |
証明書の不一致、自己署名証明書未信頼 | 正しい CA 証明書を Grafana にインポートし、tlsSkipVerify: false を維持する。 |
基本的なパネル作成例
| パネルタイプ | サンプルクエリ |
|---|---|
| 時系列グラフ（CPU 使用率） | sql SELECT toStartOfMinute(timestamp) AS time, avg(cpu_usage) AS value FROM system.metrics WHERE metric = 'CPUUsage' AND $timeFilter GROUP BY time ORDER BY time ASC |
| テーブル（最新ログ） | sql SELECT timestamp, level, message FROM logs.table WHERE $timeFilter ORDER BY timestamp DESC LIMIT 20 |
- パネル設定では「Visualization → Time series」や「Table」を選択し、軸ラベル・単位を明示すると見やすくなります。
セキュリティ強化策（TLS / IP 制限 / 監査ログ）
- TLS/SSL の有効化
- ClickHouse 側で
https_port（例: 8443）と証明書を設定。 -
Grafana データソース画面で Enable TLS をオンにし、
tlsSkipVerifyは本番では必ずfalseにする。 -
IP 制限
-
ClickHouse の
users.xmlまたはaccess_control設定で許可 IP を限定。例:xml
<user>
<name>grafana_read</name>
<networks>
<ip>203.0.113.45</ip> <!-- Grafana サーバーの IP -->
</networks>
</user> -
監査ログ取得
-
system.query_logテーブルにクエリ履歴が記録されます。最近 1 日分を確認する例:sql
SELECT event_time, user_name, query FROM system.query_log
WHERE type = 'QueryFinish' AND database = 'metrics_db'
AND event_time >= now() - INTERVAL 1 DAY
ORDER BY event_time DESC;
ClickHouse Cloud と Grafana Cloud の統合
ClickHouse Cloud の公式ドキュメント（ClickHouse Cloud 監視ガイド（日本語））では、Grafana Cloud との接続手順が詳しく掲載されています。ポイントは以下の通りです。
- データソース URL：ClickHouse Cloud が提供する HTTPS エンドポイントを使用し、TLS 設定を有効にします。
- 認証方式：API キーまたは ClickHouse のユーザー認証情報を Grafana Cloud の「Secrets」機能で安全に管理します。
- Grafana Cloud プラグイン自動インストール：Marketplace から
grafana-clickhouse-datasourceを選択すれば、CLI 不要でプラグインが自動的に配置されます。
この統合手順は、オンプレミス環境と同様の設定項目（ホスト名・ポート・TLS）を踏襲するため、既存のプロビジョニング YAML を流用できる点もメリットです。最新情報は公式サイトで随時確認してください。
まとめ
この記事では、Grafana の ClickHouse データソース を安全かつ確実に導入するための手順を包括的に解説しました。Marketplace と手動ダウンロードの両方のインストール方法、最小権限ユーザーの作成例、HTTP/Native の選択指針、GUI での設定フロー、YAML によるプロビジョニング、エラー対処とセキュリティベストプラクティス、そして ClickHouse Cloud / Grafana Cloud との統合まで網羅しています。公式ドキュメントを定期的に確認しつつ、本稿の流れに沿って構築すれば、堅牢で高速な可視化基盤が手軽に実現できます。ぜひ本手順を参考に、リアルタイム監視や分析業務に活用してください。