CLI リファレンス

コネクタは clicklink という単一のバイナリとして提供され、実行するコマンドは clicklink clctl 配下にあります。このページでは、インストール時および日常的な運用で使用するコマンドについて説明します。各コマンドに --help を付けて実行すると、詳細なヘルプを確認できます。troubleshoot および preflight サブツリーのフラグは、CLCTL_* 環境変数 (各フラグのヘルプ出力に記載) または ~/.clicklink/clctl.yaml でも指定できます。

登録トークン、保存済みの登録バンドル、または帯域外で署名された証明書を使用して、コネクタを初期化します。1 回の実行で、設定の準備、ClickHouse へのアクセスの Provisioning、mTLS クライアント証明書の取得、デプロイ (Helm チャートまたは systemd ユニット) 、ヘルスチェックを行います。再実行しても安全です。設定とクラスター UUID は保持され、認証情報はアトミックに上書きされます。また、--force を指定しない限り、既存のクライアント秘密鍵が再利用されます。手順全体については、オンボーディングを参照してください。

3 つのエントリポイントのうち、指定するのは必ず 1 つだけです。これらは相互排他的です。

--target helm でのみ有効です。

--target systemd を指定した場合にのみ有効です。

• --handoff、--enroll、--signed-cert は相互排他的です。必ずいずれか 1 つを指定してください。
• Kubernetes 専用のフラグは、--target helm を指定しない限り拒否されます。--target helm では、--server と --ca-data は拒否されます (Helm フローではワークステーションの kubeconfig を読み取ります) 。
• --no-auto-sign と --sign-endpoint は互いに排他的です。また、これらと --api-private-ca は、いずれも --signed-cert と併用できません。
• --operators と --no-gateway は相互排他的です。
• --skip-provision を指定すると、--ch-pod、--ch-user-suffix、--server、--ca-data、--ch-admin-password-stdin は拒否されます (プロビジョニングは実行されません) 。

コネクタのチェック群を、config、files、network、clickhouse、systemd、access、disk、redaction のカテゴリ別に実行します。各チェックの結果は、pass、warn、fail、skip のいずれかで報告されます。終了コード 0 はすべてのチェックが成功したことを示します (警告はノンブロッキングです) 。終了コード 2 は、1 つ以上のチェックが失敗したことを示します。

このコマンドはデフォルトでローカルで実行されます。--k8s-namespace を指定すると、kubectl exec を使用してコネクタポッド内のバイナリを実行し、レポートはローカルで表示されます (ポッドでは systemd チェックは常にスキップされます) 。リモートチャネルフラグを指定すると、代わりにリモート VM 上にインストールされたバイナリを実行します。

--k8s-* フラグとリモートチャネルフラグは相互排他的です。いずれか一方のターゲットを選択してください。

サポートセッション (トラブルシューターがコマンドを受け付ける時間制限付きの期間) を有効化、無効化、確認します。セッションがアクティブでない場合、WebSocket が接続されていても、デーモンはすべてのコマンドを拒否します。サポートセッションを参照してください。

コマンドは、次の 2 つのモードのいずれかで動作します。

• ローカルファイル (デフォルト) : トラブルシューターが実行されているホスト上のセッション状態ファイル (デフォルト: /var/lib/clicklink/session.json) の読み取りと書き込みを行います。
• ゲートウェイ: --gateway-url を指定すると、OIDC ID トークンを取得し、ワークステーションからトラブルシューターのセッションゲートウェイを呼び出します。

すでにセッションが有効な場合は、有効化できません。先に無効化するか、有効期限が切れるまで待ってください。

セッションを直ちに無効化します。アクティブなセッションがない場合は何も実行されません。

セッションがアクティブかどうか、有効化したユーザー、有効期限を表示します。--output (-o) では、table (デフォルト) またはjsonを選択できます。

Kubernetes では、ポートフォワードを使用してゲートウェイにアクセスします。

kubectl -n <connector-namespace> port-forward \
  statefulset/clicklink-connector-troubleshooter 8443:8443
clicklink clctl troubleshoot session enable \
  --gateway-url http://localhost:8443 \
  --duration 1h --reason "support ticket 1234"

VM 上では、セッションゲートウェイ が自己署名 TLS 証明書を提供します。このコマンドは証明書の SHA-256 フィンガープリントを ~/.clicklink/clctl.yaml に記録し、session コマンドで検証できるようにします。固定したフィンガープリントが一致しなくなった場合は、フェイルクローズします。信頼は、次の 2 つのいずれかの帯域外の方法で確立されます。

• リモートチャネルフラグを使用する場合は、すでに認証済みのチャネル経由で VM から証明書を直接読み取り、固定します。
• チャネルを使用しない場合は、コネクタが証明書の生成時にログに記録した SHA-256 値を --gateway-fingerprint で指定します。取得した証明書は、この値と一致した場合にのみ固定されます。このフラグを省略すると、何も固定せずに提示されたフィンガープリントを表示します。

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

Kubernetes では、pinning は使用しません。CA 発行の証明書を使用するイングレス経由でゲートウェイを公開するか、ポートフォワードを使用してください。

トラブルシューターの監査ログの末尾のエントリを出力します。改行区切り JSON 形式で、デーモンが受け入れた、またはブロックしたコマンドごとに 1 つのエントリが含まれます。このコマンドはログを読み取り専用で開き、変更を加えることはありません。

コネクタのランタイムイメージにはシェルがないため、Kubernetes ではこのコマンドがサポート対象のリーダーです。

kubectl -n <connector-namespace> exec <troubleshooter-pod> -- \
  /clicklink clctl troubleshoot audit tail

clicklink clctl scraper access provision と clicklink clctl troubleshoot access provision は、コンポーネントごとのインスタンス単位のアクセスバンドル (読み取り専用の ClickHouse ユーザーとその権限、およびコンポーネントが使用する Kubernetes ServiceAccount、RBAC、トークン) を作成し、--force を指定するとローテーションします。init はインストール時にこれをインラインで実行します。スタンドアロンコマンドは、再実行およびローテーション用です。

1 つのコンポーネントのインスタンス認証情報をローテーションします。

clicklink clctl scraper access provision --target helm \
  --target-namespace <connector-namespace> \
  --instance <instance-name> --instance-namespace <clickhouse-namespace> \
  --server <kubernetes-api-server-url> \
  --apply-ch-grants --ch-pod <clickhouse-pod-or-label-selector> --ch-pod-namespace <clickhouse-namespace> \
  --force

preflight、gateway trust、access provision は、VM ターゲットへの接続方法を選択するための共通フラグセットを受け付けます。