サポートセッション

サポートセッションは、ClickHouse Connector を介して ClickHouse に一時的な診断アクセスを付与します。このページでは、セッションの概要、有効化と無効化の方法、セッション中に ClickHouse Support エンジニアが実行できる操作、およびその監査方法について説明します。

サポートセッションとは

サポートセッションとは、トラブルシューターが ClickHouse Support エンジニアからのコマンドを受け付ける、時間制限付きの期間です。セッション外では、送信方向の WebSocket が接続されていても、あらゆるコマンドを拒否します。これ以外の実行経路はなく、ClickHouse が代わりにセッションを開くこともできません。ClickHouse Cloud がお客様の環境へ接続することは一切なく、受け取るのはトラブルシューターが送信方向のチャネルを通じて送信した内容のみです。セッションが制御するのは診断のみです。managed モードのサービスに対するライフサイクルコマンドは executor の別チャネルを経由し、このチャネルはサポートセッションによって開かれることも制御されることもありません。managed services を参照してください。セッションは次の 2 つの手段で制御します。

セッションゲートウェイ: トラブルシューターに埋め込まれた、認証付きの API です。POST /v1/clctl/session/enable、POST /v1/clctl/session/disable、GET /v1/clctl/session/status を提供します。すべての呼び出しには、メールアドレスがオペレーター許可リストに登録されている、短命の OIDC ID トークンが必要です。
ローカルセッションファイル: Linux VM へのインストールの場合に、root 権限でホスト上に書き込まれます。

ゲートウェイのトランスポートは target によって異なります。VM のゲートウェイは自己署名 TLS を提供し、各オペレーターはそのフィンガープリントをピン留めします。Kubernetes のゲートウェイはポッドローカルで HTTP を待ち受けるため、kubectl port-forward (トンネルは API server の TLS 上を通ります) 経由、または CA 発行の証明書で TLS を終端するイングレス経由でアクセスします。オペレーター許可リストを含むセッションの方針は、clicklink clctl init の実行時に選択します。

セッションの有効化と無効化

Kubernetes
Linux VM

ゲートウェイはトラブルシューターポッドのポート 8443 で待ち受けます。クラスターにアクセスできる場合は、ポートフォワード経由で接続してください。

CONNECTOR_NAMESPACE='clicklink'   # 初期化時に選択したコネクタのネームスペース
kubectl -n "${CONNECTOR_NAMESPACE}" port-forward statefulset/clicklink-connector-troubleshooter 8443:8443

次に、別の端末でセッションを有効にします。

clicklink clctl troubleshoot session enable \
  --gateway-url http://localhost:8443 \
  --duration 4h \
  --reason "<ticket reference>"

同様に、セッションの状態確認や終了も行えます。

clicklink clctl troubleshoot session status --gateway-url http://localhost:8443
clicklink clctl troubleshoot session disable --gateway-url http://localhost:8443

呼び出し元の OIDC アイデンティティは、オペレーター許可リストに含まれている必要があります。認証されていない呼び出し元や許可リストにない呼び出し元には 401 または 403 が返され、ゲートウェイがその試行をログに記録します。オペレーターがクラスター認証情報なしで作業できるようにするには、チャートのオプトインのイングレスを介してゲートウェイを公開してください。このイングレスは CA 発行の証明書で TLS を終端します。詳細は設定を参照してください。

ホストで root 権限を使用できる場合は、セッションを直接管理します。デーモンと CLI は、状態ファイル /var/lib/clicklink/session.json をアトミックに読み書きします。

sudo clicklink clctl troubleshoot session enable --duration 4h --reason "<ticket reference>"
sudo clicklink clctl troubleshoot session status
sudo clicklink clctl troubleshoot session disable

root 権限のない呼び出し元も、VM 上のゲートウェイを利用できます。ゲートウェイは自己署名 TLS を提供するため、各セッションユーザーはゲートウェイの証明書フィンガープリントを一度だけピン留めします。

clicklink clctl troubleshoot gateway trust \
  --gateway-url https://<vm-host>:8443 \
  --gateway-fingerprint <sha256-fingerprint>

ピンは ~/.clicklink/clctl.yaml に保存されます。提示された証明書が一致しない場合、接続はフェイルクローズします。ゲートウェイが自社の CA が発行した証明書を提供する場合は、各セッションコマンドで --gateway-ca にその CA bundle を指定してください。

セッションの有効期限

セッションは自動的に期限切れになります。デフォルトの有効期間は4時間で、session enable --duration は最大24時間まで指定できます。期限が切れるか、session disable を実行した時点で、トラブルシューターはコマンドを受け付けなくなります。無効化するとアクセスは即座に取り消されます。再起動やClickHouseとの協調は必要ありません。

オペレーター許可リスト

すべてのゲートウェイ呼び出しは、オペレーターのメールアドレスの許可リストに基づき認可されます。照合には検証済みの OIDC トークンで証明されたメールアドレスが使用され、クライアントが提供した値が使われることはありません。

Kubernetes: values オーバーレイで clctl.gateway.allowedOperators を設定します。チャートはリストを ConfigMap にレンダリングするため、values を変更して helm upgrade を実行すると、ポッドを再起動せずに許可リストを更新できます。
Linux VM: 許可リストは /etc/clicklink/allowed-operators.txt にあり、指定したオペレーターのメールアドレスに基づいて clicklink clctl init により書き込まれます。

いずれの環境でも、ゲートウェイは前回の読み取りから 30 秒が経過すると次のリクエスト時にファイルを再読み込みします。編集内容は再起動なしで反映されます。

セッション中にオペレーターが実行できること

セッションがアクティブな間、ClickHouse Support エンジニアは 2 種類のコマンドを実行できます。 読み取り専用 SQL は、pcm_troubleshooter ユーザーとしてクラスターに対して実行されます。このユーザーに付与される grants は、セッションのテーブル許可リストの範囲に限定されます。さらにトラブルシューターは、SELECT、WITH、SHOW、DESCRIBE、EXPLAIN のいずれでも始まらないステートメントをすべて拒否します。このユーザーが持つのはテーブル単位の SELECT grant のみで、書き込み、DDL、管理系の権限は一切ありません。デフォルトの許可リストには、system.parts、system.merges、system.replicas、system.metrics、system.settings などの system テーブルが含まれます。system.query_log と system.text_log は許可リストに追加できません。これらを列挙した設定はデーモンが拒否するため、これらに対する grant がプロビジョニングされることはありません。デフォルトの許可リストには system.processes も含まれており、その query 列には実行中のステートメントのテキストが表示されます。実行中のクエリテキストをセッション中に一切表示させたくない場合は、troubleshooter.allowedTables (Helm overlay) または troubleshooter.allowed_tables (VM 設定ファイル) から削除してください。 読み取り専用の Kubernetes ビュー とは、付与されたネームスペース内のポッド、ポッドステータス、ポッドログ、サービス、configmap、イベント、PersistentVolumeClaim、デプロイメント、statefulset、replicaset に対する get、list、watch を指します。access bundles は、いずれのインストール対象でも Kubernetes ServiceAccount に紐付けられます。bundle がプロビジョニングされていない場合、トラブルシューターは kubectl 系のコマンドを一切受け付けません。executor が managed service 向けにプロビジョニングするのは scraper であり、トラブルシューターはプロビジョニングしません。managed service の support sessions を参照してください。トラブルシューターの RBAC には exec、delete、patch の permission が含まれていないため、オペレーターがポッド内でシェルを開いたり、セッションを通じて何かを変更したりすることはできません。grant と RBAC の完全な一覧は権限モデルのリファレンスを参照してください。

監査ログ

セッション中に実行されたすべてのコマンドは、1行につき1つのJSONオブジェクト (NDJSON) の形式で /var/log/clicklink/troubleshoot-audit.log に追記されます。ブロックされたコマンドも記録され、blocked_by にその理由 (例: session inactive) が示されます。submitted_by はコマンドチャネル上の組織ID、すなわちご自身の組織IDです。個々のClickHouseエンジニアは、このファイルではなくClickHouse Cloud側に記録されます。セッションコマンドのエントリは次のようになります:

{
  "timestamp": "2026-06-22T22:30:00.123456789Z",
  "command_id": "11111111-2222-4333-8444-555555555555",
  "submitted_by": "<org-id>",
  "command_type": "sql",
  "command_text": "SELECT database, table, active, count() FROM system.parts GROUP BY ALL",
  "instance_id": "analytics",
  "status": "completed",
  "duration_ms": 42,
  "output_lines": 12
}

status にはコマンドの結果が入ります。completed、error、rejected のいずれかです。ゲートウェイの呼び出しは別途記録されます。拒否されたものも含め、すべての呼び出しは構造化された clctl.gateway 行としてトラブルシューター自身のログ (VM ではジャーナル、Kubernetes ではコンテナーログ) に出力されます。この行には、submitted_by (検証済みトークンによって証明されたメールアドレスであり、クライアントから渡された値ではありません) と command_type (clctl.session.enable、clctl.session.disable、clctl.session.status) が含まれます。さらに、reason (enable 時の --reason) 、remote_addr、status も含まれます。status は ok、unauthorized、forbidden、rate_limited、bad_request、conflict、error のいずれかであるため、拒否されたアクセスもログで確認できます。 VM 上のローカルセッションの変更は監査ログのエントリにはなりません。実行したホストユーザーは /var/lib/clicklink/session.json に enabled_by として記録され、session status で表示されます。 VM では、clicklink clctl troubleshoot audit tail で監査ログを読み取ります。Kubernetes の場合、ログはトラブルシューターポッド内にあり、コンテナーイメージにシェルが含まれていないため、kubectl exec 経由でバイナリ自身のリーダーを呼び出します:

CONNECTOR_NAMESPACE='clicklink'   # the connector namespace you chose at init
kubectl -n "${CONNECTOR_NAMESPACE}" exec statefulset/clicklink-connector-troubleshooter -- \
  /clicklink clctl troubleshoot audit tail

監査ログは環境内に配置される単純なファイルです。他のホストログやコンテナーログと同様に、自社の SIEM へ転送してください。

マスキング

トラブルシューターが返すすべての情報は、環境外に送信される前にマスキングされます。組み込みパターンは、IPv4 および IPv6 アドレス、Bearer トークン、AWS アクセスキー、メールアドレス、JWT、SSH 秘密鍵、接続文字列に埋め込まれた認証情報を対象とします。これらは /etc/clicklink/redaction-patterns.yaml で拡張またはオーバーライドできます。組み込みパターンと同じ名前のエントリは、そのパターンを置き換えます。パターンファイルが無効な場合、デーモンは起動を拒否し、clicklink clctl preflight によって検証されるため、マスキング設定が壊れている場合は明示的に失敗します。

Architecture: コネクタが確立するすべての接続と、セッションを中心としたデータフロー。
Configuration: ゲートウェイ、許可リスト、機密情報のマスキングに関する設定。
よくある質問: 失効、監査、データegressに関するよくある質問の概要。

はじめる

サービスとインフラストラクチャ

Bring Your Own Cloud

データとインテグレーション

接続とクエリ実行

アクセス管理

セキュリティとコンプライアンス

監視とバックアップ

AI ツールとエージェント

Cloud API

請求

サポート

ClickHouse Private