アーキテクチャ

ClickHouse Connector は、いずれも clicklink バイナリに組み込まれた 2 つのデーモンを実行します。

• スクレイパーは、ClickHouse のシステムテーブルの許可リストを一定間隔で読み取り、結果をローカルにバッファリングして、インフラストラクチャのメタデータおよび稼働状況とともにコネクタエンドポイントへ送信します。
• トラブルシューターは、コネクタエンドポイントへのアウトバウンドコマンドチャネルを維持し、アクティブなサポートセッション中に読み取り専用の診断を実行します。セッション外では何も実行しません。

Kubernetes では、どちらも選択したネームスペース (デフォルトは clicklink) に clicklink-connector Helm チャートでデプロイされるワークロードとして実行されます。Linux VM では、非特権の clicklink システムユーザーとして、clicklink-scraper および clicklink-troubleshooter の systemd ユニットで実行されます。

コネクタが確立するすべての接続はアウトバウンドです。全一覧は次のとおりです。

すべての API リクエストには、メソッド、パス、タイムスタンプ、本文のハッシュに基づいて計算された HMAC-SHA256 署名を含む Authorization ヘッダーが付加されます。これにより、TLS チャネル内であっても、リクエストのリプレイや転送時の改ざんを防止します。

インバウンドでは、コネクタはローカルのヘルスチェックおよびメトリクスポートと、サポートセッションページで説明されているオプトインのセッションゲートウェイのみを公開します。ClickHouse のコントロールプレーンがこれらに接続することはありません。

コネクタは、自ら取得・管理するクライアント証明書を使用してエンドポイントに対して認証を行います。

• 登録。 clicklink clctl init は、ローカルで秘密鍵を生成し、組織 ID をコモンネーム、エンドポイントのホストを唯一の DNS SAN とする証明書署名リクエストを生成します。秘密鍵が環境外に出ることはありません。
• 初回発行。 CSR は HMAC で認証され、/v1/pcm/cert/sign の登録用署名エンドポイントに送信されます。組織に対して有効期限切れでない証明書がすでに存在する場合、エンドポイントは 409 を返して拒否します。CLI には、既存の証明書で完了する方法、または --force を使用して意図的に置き換える方法が表示されます。
• 自動更新。 各デーモンは 12 時間ごとに証明書の有効期間を確認し、残り 10 日になると /v1/pcm/cert/renew (mTLS と HMAC) を介して新たに 30 日間有効な証明書をリクエストします。Kubernetes では、各デーモンが名前を完全一致で指定した RBAC 権限により、更新済みの証明書を clicklink-mtls Secret に書き戻します。VM では、TLS ディレクトリはデーモンユーザーが書き込み可能です。更新にオペレーターの操作は必要ありません。

コネクタは、エンドポイントのサーバー証明書をシステムトラストストアで検証します。エンドポイントが private CA を使用している場合は、登録時に配布された CA bundle を使用します。

• 許可リストに登録されたシステムテーブルのメトリクス。 スクレイパーのデフォルトセットは metric_log、asynchronous_metric_log、tables、warnings、server_settings です。許可リストは明示的に設定されており、スクレイパーはこれ以外を読み取りません。
• インフラストラクチャのメタデータ。 API を介して同期されるインスタンス、インフラストラクチャ、バックアップのインベントリ。
• ヘルス情報と自己メトリクス。 コンポーネントのステータスとコネクタ自体の運用メトリクス。
• サポートセッションの出力。 有効化したセッション中に実行された読み取り専用診断の結果 (機密情報のマスキング後) 。

• スクレイプパス上の生のクエリテキスト。 system.query_log は、クエリカラムにリテラル値、ひいては PII やシークレットが含まれる可能性があるため、意図的にデフォルトのスクレイプ対象から除外されています。これを再追加するかどうかは、各デプロイメントでリスクを理解したうえで判断するオーバーライドです。サポートセッション中は、デフォルトのテーブル許可リストに、実行中のクエリテキストを表示する system.processes が含まれます。トリミング方法については、サポートセッションを参照してください。
• 認証情報。 構成ファイルには認証情報は含まれず、ClickHouse が保存するのはコネクタユーザーのパスワードの bcrypt ハッシュのみです。シークレットは Kubernetes Secrets またはホスト上で root のみが読み取れるファイルに保持されます。スクレイプパスや同期パスでこれらが送信されることはありません。
• マスキングされていない troubleshooter の出力。 troubleshooter が返すすべての内容は、外部に送信される前に、組み込みおよび独自のマスキングパターンによってマスキングされます。サポートセッションを参照してください。

• 境界はお客様の環境です。 ClickHouse Cloudが受信するのは、スクレイパーが送信するデータと、有効なサポートセッションから返されるデータだけです。お客様の環境に向けて接続を開始することはありません。
• セッションゲートウェイはお客様の管理下にあります。 イングレス経由で公開しない限り、Kubernetesではkubectl port-forward経由で、VMではローカルからのみ、お客様の環境内でアクセスできます。ClickHouseのコントロールプレーンが接続することはありません。
• ClickHouseへのアクセスは読み取り専用です。 pcm_scraperおよびpcm_troubleshooterユーザーにはテーブルごとのSELECT権限があり、これに加えて、ログテーブルをディスクにフラッシュするためだけのスクレイパー専用システム権限が1つ付与されています。INSERT、DDL、ユーザー管理の権限はありません。正確な一覧は権限モデルに記載されています。
• Kubernetesへのアクセスはネームスペース単位に限定されます。 すべてのRBACは、コネクタおよびインスタンスのネームスペース内のロールを通じて付与されます。ワークロードリソースには読み取り専用の動詞のみが許可され、コネクタ自身のSecretsには完全一致する名前でのみアクセスできます。exec、delete、patchの権限はありません。
• ネットワークポリシー。 Kubernetesでは、チャートにより、指定したCIDR以外へのコネクタのegressをすべて拒否するNetworkPolicyを生成できます。強制されるかどうかは、クラスターでポリシーを強制するCNIが稼働しているかに依存します。そのようなCNIがない場合、ポリシーは機能しません。設定を参照してください。
• VMのホスト強化。 ユニットはログイン不可のシステムユーザーとして実行され、ProtectSystem=strict、NoNewPrivileges、読み取り専用の設定パス、および有効化されたFIPSモードを使用します。

コネクタの正確な権限およびRBACルールについては、権限モデルを参照してください。ClickHouseがお客様に代わってクラスターを運用する場合は、信頼モデルが異なります。BYOC architectureおよびBYOC privilegeのページを参照してください。