よくある質問
誰が、いつサービスを変更できますか？
managed モードでは、ClickHouse Cloud はマネージドサービスのみを変更します。executor ホストまたは ポッド にアクセスできるユーザーであれば、ローカルのclicklink clctl instances コマンドで操作することも可能です。サービスライフサイクルを参照してください。ClickHouse Cloud は、executor のアウトバウンドチャネルを介してライフサイクルコマンドを送信します:
- create (送信されたサービス定義に基づく)
- scale (ClickHouse Cloud が指定する固定のレプリカ数へ。ClickHouse Cloud の設定による上限があり、デフォルト設定では 20)
- stop、start、restart
- バックアップおよびバックアップの削除
- delete
clicklink clctl executor prepare と clicklink clctl instances create の実行が必要です。バケットと IAM role を作成できるのはユーザーだけだからです。もう 1 つはクラスター内のプラットフォームコンポーネントの更新です。executor が提案された各バンドルをステージングし、clicklink clctl platform approve によってそれが承認され、2 時間有効なトークンが発行されます。プラットフォーム更新を参照してください。
executor の操作はすべて Kubernetes API を経由します。admission ポリシーは、書き込みをサービスプレフィックス (デフォルトでは ns-) を持つネームスペースに限定します。加えて、executor 自身のネームスペース内では 3 つの書き込み、すなわちトークンの更新、サービスレジストリの ConfigMap、そして Kubernetes における clicklink-mtls Secret 内の更新されたクライアント証明書が許可されます。一方、同じリソースファミリーに対する読み取りはクラスター全体に及びます。承認されたプラットフォーム更新は、プラットフォームネームスペースに限定された別の pcm-platform identity として実行されます。ユーザー自身が運用するクラスターが変更されることは一切ありません: scraper とトラブルシューターは読み取り専用です。正確なスコープについては権限モデルのページを参照してください。
環境から外部に出るデータは何ですか？
データが外部に出る経路は 3 つあり、いずれもコネクタ自身が開くアウトバウンド接続を経由します。スクレイプ経路、executor、そして有効化したサポートセッションです。 scraper は、デフォルトでは固定されたシステムテーブル群 (metric_log、asynchronous_metric_log、tables、warnings、server_settings) の結果を送信します。あわせて、ヘルスおよびステータスのハートビート、サービスとバックアップの状態、コネクタ自身のメトリクスも送信します。デフォルトのスクレイプ対象に system.query_log は含まれません。生の SQL テキストやその中のリテラル、個人データが、そのテーブルを明示的に追加しない限りスクレイプ経路から外部に出ることはありません。セッション中は、デフォルトのテーブル許可リストに system.processes が含まれており、実行中のクエリテキストが表示されます。これを秘匿する必要がある場合は、許可リストから削除してください。
executor は、実行した各コマンドの結果と、各マネージドサービスの状態およびレプリカ数を送信します。そのハートビートでは、コマンドチャネルが接続されているかどうかが報告されます。あわせて、プラットフォームのコンポーネントバージョン、最後に適用したバンドルのダイジェスト、最後のプラットフォーム更新の結果も伝達されます。VM インストールの場合は、Kubernetes アクセスバンドルが ok、expiring、expired、または存在しないかのいずれであるかもハートビートで報告されます。サービスを作成すると、clicklink clctl instances create が環境 ID、クラウドとリージョン、サービス名、バケット名、IAM role ARN を送信します。また、デフォルトユーザーのパスワードのハッシュを 2 つ送信しますが、パスワード自体が外部に出ることはありません。
サポートセッションが有効な間は、トラブルシューターがコマンド出力も返します。この出力は、許可リストに登録された ClickHouse テーブルと、ポッドログを含む読み取り専用の Kubernetes ビューに限定されます。また、送信前にマスキング (IP、認証情報、トークン、キーに対する組み込みパターンと、独自に定義したパターン) を通過します。テーブルデータ、バックアップ、クエリ履歴 (system.query_log、system.text_log) は環境内に留まります。外部に出るのは次の 3 つです。
- 許可リストに登録されたメトリクス履歴テーブル (
system.metric_log、system.asynchronous_metric_log) の行は、スクレイプのたびに送信されます - 実行中のクエリテキストは、許可リストから削除しない限り、セッション中に
system.processesを通じて参照できます - Kubernetes サポートセッション中に読み取られたポッドログは、マスキングを経て送信されます
ClickHouse によるクラスターの変更を止めるには？
managed モードを使わずに実行してください。インストール時にclicklink clctl init へ --no-managed を渡すか、確認を求められた際に「いいえ」と回答します。デプロイされるのは scraper と トラブルシューター のみになるため、ClickHouse はサービスを作成・変更・削除できません。ただし、コネクタは引き続き読み取り専用の ClickHouse ユーザーと ServiceAccount をプロビジョニングします。詳細は権限モデルを参照してください。
既存のインストール環境では、executor を停止し、cluster admin としての権限を削除します。停止するには、Helm values で executor.enabled: false を設定して helm upgrade を実行するか、VM 上で systemctl disable --now clicklink-executor を実行します。その後、権限を削除してください。最後のコマンドは ServiceAccount 自体を削除します。そのネームスペースは、VM へのインストールの場合は clicklink-system、Kubernetes へのインストールの場合はコネクタのネームスペースです。
コネクタがオフラインになった場合はどうなりますか？
ClickHouse サービスには影響しません。コネクタは data path 上には存在せず、managed service は executor なしでも稼働を続けます。影響が出るのは可視性と制御の面です。ClickHouse Cloud はテレメトリーの受信を停止し、コネクタが復帰するまで サポートセッション は使用不可になります。マネージドモードでは、ハートビートが 5 分間届かないと ClickHouse Cloud 上で環境がオフラインと表示され、次のハートビートが届いた時点で再び ready になります。 executor が接続されていない間、ライフサイクル commands の挙動は 2 通りに分かれます。ClickHouse Cloud が既に受理した create、delete、プラットフォーム同期は保持され、再試行されます。create は最後の progress レポートから最大 30 分間、delete は最大 2 時間、プラットフォーム同期は最大 10 回まで再試行されます。それを超えると、その command は失敗として報告されます。この 2 つの期限はexecutor.create_retry_horizon および executor.delete_retry_horizon の設定キーで指定します。それ以外のすべての command (scale、stop、start、restart、backup、backup の削除) 、および executor が接続されていない間に送信された create や delete は、queue に入れられず、送信時点で拒否されます。executor が報告できなかった結果は、次回の connection 時に送信されます。コネクタがオフラインのときを参照してください。
VM 上では、connector endpoint が reachable でない間、scraper は scrape したデータを /var/lib/clicklink/buffer にスプールします (デフォルトで最大 168 時間または 1024 MB) 。再接続時にスプールされたデータを送信するため、エンドポイントの障害でテレメトリーが失われることはありません。crash したデーモンは、VM では systemd により、Kubernetes ではキューブレットにより再起動されます。executor は command の state をディスク上に保持するため、再起動後も処理中だった commands が再開されます。
診断するには、各 component の /livez エンドポイントを確認し (判断材料となるのは JSON の status フィールドであり、HTTP コードではありません) 、clicklink clctl preflight を実行してください (VM ホストでは sudo を付けます) 。Preflight では、設定、接続性、ClickHouse への到達性、access、ディスクを一度にチェックします。運用を参照してください。コネクタの health が回復しない場合は、ClickHouse Support にお問い合わせください。
サービスを削除すると何が削除されますか？
executor はサービスを停止し、その Kubernetes リソースを削除したうえで、ネームスペースを削除します。ネームスペースが消えた時点で、サービスは終了したと報告されます。Kubernetes の外にあるものはすべて残ります。データ用 バケット、バックアップ用 バケット、およびサービスの IAM role です。executor はお客様の バケット や IAM に対する認証情報を保持していないため、それらに触れることはできません。 残りは、お客様の認証情報を用いて実行するclicklink clctl executor teardown で削除します。デフォルトでは IAM role を削除し、データと バックアップ は保持します。これらを削除するには明示的な flag の指定が必要です。サービスの削除を参照してください。
default ユーザーのパスワードはどこで確認できますか？
clicklink clctl executor prepare がユーザー側で生成し、一度だけ出力します。--from-prepare ではなく個別のフラグを指定して送信する場合は、clicklink clctl instances create が --default-user-password-file から読み取るか、新たに生成して出力します。ClickHouse Cloud に送信されるのはそのハッシュのみであるため、コネクタも ClickHouse も再度表示することはできません。表示されたら必ず保存してください。
ClickHouse のアクセスを取り消すにはどうすればよいですか？
影響が小さい順に説明します。- 対話型アクセスを終了します。 VM ホストで
sudo clicklink clctl troubleshoot session disableを実行してセッションを無効にするか、Kubernetes ではポートフォワード経由で--gateway-urlを指定して同じコマンドを実行します (正確なコマンドについてはサポートセッションページを参照) 。アクティブなセッションがない場合、トラブルシューターは接続中であってもすべてのコマンドを拒否します。 - managed モードを停止します。 ClickHouse が自分のクラスターを変更しないようにするにはどうすればよいですか？ の説明に従って、executorを停止し、その権限を削除します。プラットフォームの更新はもともと承認が必要なため、承認を保留すれば更新は停止します。
- 今後のセッションを防止します。 オペレーターの許可リストを空にする (許可リストを空にするとゲートウェイが閉じます) か、ゲートウェイを無効にします。VM では、ホスト上の root は引き続きローカルセッション管理を利用できます。設定ガイドを参照してください。
- ClickHouse Cloud との接続を遮断します。 ネットワーク層でコネクタエンドポイントへの送信トラフィックをブロックするか、強制適用される CNI で
networkPolicy.allowEgressCIDRsを空にします。コネクタは送信専用のため、ClickHouse Cloud には接続を復旧するための受信経路がありません。ワークロードを停止またはアンインストールするまで、ClickHouse に対するローカル読み取りは継続します。これが完全な停止です。 - 認証情報を取り消します。
pcm_scraperとpcm_troubleshooterの ClickHouse ユーザーを削除し、コネクタの Secret (Kubernetes) または/etc/clicklink配下のファイル (VM) を削除します。 - コネクタを完全に削除します。 操作を参照してください。
エアギャップ環境や自前のミラー経由で実行できますか？
はい。インストール時に必要なアーティファクトはすべて、自組織の境界内から取得できます。- CLI の tarball とコンテナイメージを
releases.clicklink.clickhouse.comおよびパブリックレジストリからミラーし、image.repositoryをそのミラーに向けます。 --chartにはoci://参照、URL、またはローカルアーカイブを指定できます。--chart-versionのデフォルトは CLI 自身のバージョンです。- コネクタエンドポイントが自組織の境界内でプライベート CA の背後に配置されている場合、
--api-private-ca(Kubernetes) またはapi.tls.ca_file(VM) により、登録バンドルの CA チェーンがシステムのルート証明書に追加されます。 - 直接接続できない環境で登録する場合は、
init --handoffが帯域外で取得したバンドルを消費し、--no-auto-signとinit --signed-certの組み合わせで証明書の署名を帯域外で完了できます。 - マネージドモードでは、サービスおよびプラットフォームコンポーネント向けの ClickHouse イメージを、自組織のレジストリにインポートしたうえでそこから取得できます。ClickHouse はそのレジストリをお客様の環境に登録します。
- プラットフォームバンドルは帯域外で受け渡し、ファイルとして
clicklink clctl platform approve --bundleに渡すことができます。
サポートセッションはどのように監査されますか？
セッション中に実行されたすべてのコマンドは、許可されたものもブロックされたものも、newline-delimited JSON形式で/var/log/clicklink/troubleshoot-audit.logに追記されます。各エントリには、submitted_by (コマンドチャネル上の組織ID) 、コマンドのテキスト、対象インスタンス、結果、および拒否されたコマンドの場合はblocked_byが記録されます。ゲートウェイ呼び出しは、拒否されたものも含め、トラブルシューター自身のログに構造化されたclctl.gateway行として記録されます。これらはトークンによって証明されたオペレーターのメールアドレスに帰属され、自己申告の名前は使用されません。VM上のローカルセッションの変更では、実行元のホストユーザーが/var/lib/clicklink/session.jsonのenabled_byとして記録されます。
セッションには時間制限があります (デフォルトでは4時間、最長24時間) 。有効化のたびに、有効化したユーザー、有効期限、任意の理由が記録され、これらはclicklink clctl troubleshoot session statusで表示できます。
監査ログはclicklink clctl troubleshoot audit tailで閲覧します。Kubernetesでは、このコマンドがサポートされているreaderです (runtimeイメージにはシェルがありません) 。デフォルトのpersistence.enabled: trueでは、ログはトラブルシューターの永続volumeに保存されるため、ポッドの再スケジュール後も監査履歴が維持されます。永続化を無効にすると、監査ログとセッション状態はポッドの存続期間に限定され、chartでもローカル開発専用として扱われます。rotationでは、デフォルトで最大128 MBのファイルを5つ、168時間保持します。調整方法については設定リファレンスを、信頼モデルの詳細についてはサポートセッションを参照してください。