コンポーネント
ClickHouse Connector は 3 つのデーモンを実行します。いずれもclicklink バイナリに組み込まれています。
- executor は、コネクタ エンドポイント への アウトバウンド コマンドチャネルを保持し、ClickHouse Cloud がクラスター内で管理する サービス 向けに送信するライフサイクルコマンドを適用します。対象となるコマンドは、作成、scale、停止と開始、再起動、バックアップ と バックアップ の削除、削除、および承認済みのプラットフォーム更新 です。すべての操作は Kubernetes API 呼び出しです。ClickHouse への 接続 は開かず、バケット や IAM の認証情報も保持しません。managed モードでのみ実行されます。
- scraper は、ClickHouse システムテーブルの allowlist を一定の interval で読み取り、結果をローカルに buffer します。その結果を、インフラストラクチャのメタデータおよびヘルスステータスとともに コネクタ エンドポイント へ送信します。
- トラブルシューター は、コネクタ エンドポイント への アウトバウンド コマンドチャネルを保持し、アクティブな support session 中に読み取り専用の診断を実行します。session 外では何も実行しません。
clicklink-connector Helm チャートが、任意に選択したネームスペース (デフォルトは clicklink) にデーモンをデプロイします。executor は単一 replica の Deployment で、コマンドの state を永続 volume 上に保持します。Linux VM では、デーモンは非特権の clicklink システムユーザーのもとで clicklink-scraper、clicklink-troubleshooter、clicklink-executor の systemd unit として実行されます。
接続
コネクタが確立する接続はすべてアウトバウンドです。完全な一覧は次のとおりです。
すべての API リクエストには、メソッド、パス、タイムスタンプ、ボディのハッシュに対する HMAC-SHA256 署名を含む
Authorization ヘッダーが付与されます。TLS チャネル内であっても、リクエストのリプレイや改ざんはできません。
インバウンドについては、各デーモンがローカルのヘルスポートを 1 つ公開します。scraper は 8082、トラブルシューターは 8084、executor は 8086 です。このポートは /livez、/readyz、/healthz、および /metrics でのデーモンの Prometheus メトリクスを提供します。メトリクス専用のポートは別途ありません。executor のローカルコマンド API はループバックにのみバインドされ、Service で公開されることはありません。他に存在するリスナーは、オプトイン方式のセッションゲートウェイのみです。support sessions を参照してください。ClickHouse Cloud がこれらのいずれかに接続することはありません。
証明書のライフサイクル
コネクタは、自身で取得・維持するクライアント証明書を使用してエンドポイントに対して認証を行います。3 つのデーモンはいずれも同じ証明書を提示します。- 登録。
clicklink clctl initは、秘密鍵と証明書署名要求 (CSR) をローカルで生成します。CSR には、コモンネームとして組織 ID が、唯一の DNS SAN としてエンドポイントのホストが設定されます。秘密鍵が環境外に出ることはありません。 - 初回発行。
initは、HMAC で認証したうえで/v1/pcm/cert/signの登録用署名エンドポイントに CSR を送信します。対象の組織に有効期限内の証明書がすでに存在する場合、エンドポイントは 409 を返して拒否します。その際 CLI は、既存の証明書のまま完了する方法と、--forceで置き換える方法を表示します。 - 自動更新。 3 つのデーモンはいずれも 12 時間ごとに証明書の有効期間を確認します。残り 10 日になると、
/v1/pcm/cert/renew(mTLS と HMAC) を通じて有効期間 30 日の更新済み証明書を要求します。Kubernetes では、更新された証明書は名前を厳密に指定した RBAC の権限を通じてclicklink-mtlsSecret に書き戻されます。VM では各デーモンが/etc/clicklink/tlsに書き込みます。更新にあたって運用担当者の操作は不要です。
api.tls.ca_file (VM) または api.tls.caFile (Helm) が設定されている場合は、登録バンドルに含まれる CA チェーンがこれらのルート証明書に追加されます。
データフロー
環境外に送信されるもの
- allowlist に登録されたシステムテーブルのメトリクス。 スクレイパーのデフォルトセットは
metric_log、asynchronous_metric_log、tables、warnings、server_settingsです。allowlist は明示的に設定されており、スクレイパーはこれ以外を読み取りません。 - インフラストラクチャのメタデータ。 API を介して同期されるサービス、インフラストラクチャ、バックアップのインベントリ。マネージドサービスの場合、その状態、現在および期待されるレプリカ数、稼働中のサーバーバージョンと設定バージョンが含まれます。
- ヘルス情報と自己メトリクス。 コンポーネントのステータスとコネクタ自体の運用メトリクス。executor のハートビートは、コマンドチャネルが接続されているかどうかも報告します。これには、最後のプラットフォーム更新の結果、プラットフォームコンポーネントのバージョン、最後に適用したバンドルのダイジェストが含まれます。VM インストールの場合は、Kubernetes アクセスバンドルが
ok、expiring、expired、または存在しないかどうかが追加されます。 - コマンドの実行結果。 executor が実行する各ライフサイクルコマンドについて、収束中の進捗状況、続いて成功または失敗 (失敗時はエラーテキストを含む) 。
- 送信したサービス定義。
clicklink clctl instances createは、環境 ID、クラウドとリージョン、サービス名、そのバケット名と IAM ロール ARN、冪等性キーを送信します。また、デフォルトユーザーのパスワードの 2 つのハッシュ (SHA-256 とダブル SHA-1) も送信します。 - support session の出力。 有効化したセッション中に実行された読み取り専用診断の結果 (機密情報のマスキング後) 。
デフォルトで外部に出ないもの
- 生のクエリテキスト (scrape パス上) 。
system.query_logはデフォルトの scrape 対象セットから除外されています。クエリ関連のカラムにはリテラル値が含まれる可能性があり、それに伴って PII やシークレットが含まれることがあるためです。これを再度追加する場合は、デプロイメントごとの override となります。デフォルトのセッションテーブル allowlist にはsystem.processesが含まれており、生存中のクエリのテキストが表示されます。その絞り込み方法については support sessions を参照してください。 - テーブルのデータおよびバックアップ。 これらはお客様のアカウント内の バケット に留まります。executor はお客様の バケット への認証情報を保持しておらず、読み取ることもできません。
- 認証情報。
initは設定ファイルに認証情報を書き込みません。ClickHouse が保存するのはコネクタユーザーのパスワードの bcrypt ハッシュのみで、シークレットは Kubernetes Secrets またはホスト上の root のみが読み取れるファイルに留まります。マネージドサービスの default user のパスワードはお客様側で生成され、一度だけ表示されます。送信されるのはそのハッシュのみです。scrape パスにも同期パスにも、認証情報を送信する処理はありません。 - マスキングされていない トラブルシューター の出力。 トラブルシューター が返す内容はすべて、外部に出る前に マスキング patterns (組み込みのものとお客様独自のもの) を通過します。support sessions を参照してください。
信頼境界
- 境界はお客様の環境です。 ClickHouse Cloud が受け取るのは、コネクタが送信するものだけです。すなわち、スクレイプ、ハートビートとステータス、コマンド結果、そしてアクティブな support session が返す内容です。ClickHouse Cloud 側から内向きに接続を開始することは一切ありません。
- セッションゲートウェイはお客様のものです。 Ingress 経由での公開を明示的に選択しない限り、お客様の環境内からのみ到達可能です (Kubernetes では
kubectl port-forward経由、VM ではローカル) 。ClickHouse Cloud がこれに接続することはありません。 - ClickHouse へのアクセスは読み取り専用です。
pcm_scraperおよびpcm_troubleshooterユーザーが保持するのは、テーブル単位のSELECT権限、scraper のREAD ON REMOTE(clusterAllReplicas()に必要) 、および scraper 専用のSYSTEM FLUSH LOGS権限のみです。INSERT、DDL、ユーザー管理の権限は存在しません。executor は ClickHouse ユーザーを持ちません。正確な一覧は 権限モデル に記載しています。 - scraper とトラブルシューターはクラスターを変更できません。 これらの RBAC は、コネクタおよびサービスのネームスペース内の Role に由来します。それらの Role が付与するのは、ワークロードリソースに対する読み取り専用の verb と、コネクタ自身の Secret への名前を完全一致で指定したアクセスです。
exec、delete、patchの権限はありません。 - executor は
pcm-executorとしてサービスネームスペース内のクラスター状態を変更します。 サービスのプレフィックス (デフォルトではns-) を持つネームスペースを作成・削除し、ポッドを削除して再起動します。それらのネームスペース内では、ClickHouseCluster、Backup、ScalingOverride の各オブジェクトと、サービスに必要な Secret、ServiceAccount、Service を書き込みます。また、scraper に読み取りアクセスを与える Role と RoleBinding も書き込みます。ValidatingAdmissionPolicy により、その ServiceAccount からのプレフィックス外への書き込みはすべて拒否されます。例外はいずれも自身のホームネームスペース内にあり、自身のトークン更新、clicklink-instance-registryConfigMap、そして Kubernetes では mTLS Secret 内の更新されたクライアント証明書です。このポリシーは評価できない場合、拒否側にフェイルします。admission は読み取りには適用されないため、これらのリソースファミリーに対する読み取りはプレフィックスによって制限されません。 - executor がプラットフォームネームスペースを変更するのは、お客様が承認した更新中に
pcm-platformとして実行する場合のみです。clicklink clctl platform approveはそのアイデンティティのトークンを 2 時間有効で発行し、更新は行われません。このトークンを用いて executor が書き込めるのは、Deployment、Service、ConfigMap、Secret、Job、PodDisruptionBudget のみです。ネームスペース、CRD、ServiceAccount、RBAC、webhook および admission の設定、PriorityClass、StorageClass は、承認時にお客様の認証情報で適用されます。プラットフォーム更新 を参照してください。 - executor はお客様の バケット や IAM への認証情報を保持しません。
clicklink clctl executor prepareはサービスのデータ用 バケット とバックアップ用 バケット、およびその IAM ロールを作成します。clicklink clctl executor teardownはそれらを削除します。いずれもお客様の認証情報で実行されます。このロールが信頼するのはそのサービスのポッドのみであるため、executor も ClickHouse もこのロールを引き受けることはできません。クラウドへの呼び出しは Amazon ECR と STS に対するもののみです。プラットフォームの同期や作成でチャートを取得する際にレジストリへログインします。プラットフォーム更新中には、読み取り専用の pull ロールでイメージを確認します。 - ネットワークポリシー。 Kubernetes では、チャートが各デーモンに対してデフォルト拒否の NetworkPolicy をレンダリングします。egress が許可されるのは、DNS、コネクタエンドポイント用に指定した CIDR、および Kubernetes API サーバーの CIDR のみです。scraper とトラブルシューターのポリシーでは、executor が管理するネームスペース (executor が付与するラベルで選択) 内の ClickHouse サービス、または名前で指定した ClickHouse サービスへの通信も許可されます。executor のポリシーには ClickHouse 向けのルールはありません。プラットフォームバンドルのチャートが Amazon ECR に存在する場合は、ECR と STS の範囲 (またはレジストリミラー) を
allowEgressCIDRsに追加してください。これがないと、ポリシーを強制する CNI 下では同期でチャートを取得できません。ポリシーを強制する CNI がない場合、ポリシーは効果を持ちません。設定 を参照してください。 - VM でのホストの堅牢化。 ユニットはログイン不可のシステムユーザーとして実行され、
ProtectSystem=strict、NoNewPrivileges、読み取り専用の設定パス、FIPS モードの有効化が適用されます。