clicklink という単一のバイナリとして提供され、実行するコマンドは clicklink clctl 配下にあります。このページでは、インストール時および日常的な運用で使用するコマンドについて説明します。各コマンドに --help を付けて実行すると、詳細なヘルプを確認できます。
troubleshoot、scraper、preflight、executor、instances create、platform の各サブツリーのフラグ、およびグローバルな --endpoint と --cluster は、CLCTL_* 環境変数 (各フラグのヘルプ出力に記載) または ~/.clicklink/clctl.yaml でも指定できます。グローバルな -v は、コマンドが実行する管理 API リクエストをログに記録し、-vv ではリクエストボディも記録されます。
instances および commands コマンドと executor teardown は、executor のローカル API を参照します。これを選択するグローバルフラグは 2 つあります: --endpoint <url> (デフォルトは http://127.0.0.1:9999、環境変数 CLCTL_ENDPOINT) と --cluster <name> (環境変数 CLCTL_CLUSTER) で、後者はコマンドが必要とする場合にマネージドクラスターを指定します。Kubernetes では、まず executor のデプロイメントに対して kubectl port-forward を開いてください。詳細は managed services を参照してください。
clicklink clctl init
登録トークン、保存済みの登録バンドル、または帯域外で署名された証明書を使用して、コネクタを初期化します。1 回の実行で、設定の準備、ClickHouse へのアクセスの Provisioning、mTLS クライアント証明書の取得、デプロイ (Helm チャートまたは systemd ユニット) 、ヘルスチェックを行います。--managed を指定すると、検出された EKS クラスターの executor も有効化し、executor のクラスター全体へのアクセスを付与します。再実行しても安全です。init は設定とクラスター UUID を保持し、認証情報をアトミックに上書きします。また、--force を指定しない限り、既存のクライアント秘密鍵が再利用されます。手順全体についてはオンボーディングを、executor の動作については managed services を参照してください。
エントリポイント
エントリポイントは必ず 1 つだけ指定します。共通フラグ
署名フラグ (フェーズ 1 のみ)
Kubernetes 専用フラグ
--target helm でのみ有効です。
VM 専用フラグ
--target systemd を指定した場合にのみ有効です。
フラグの競合
--handoff、--enroll、--signed-certは相互排他的です。必ずいずれか 1 つを指定してください。- Kubernetes 専用のフラグは、
--target helmを指定しない限り拒否されます。--target helmでは、--server、--ca-data、--cluster-name、--no-instanceは拒否されます (Helm フローではワークステーションの kubeconfig を読み取り、クラスター内のインスタンスを検出します) 。 --no-instanceと--instanceは相互排他的です。--managedと--no-managedは相互排他的です。また、--cluster-nameは--no-managedと併用できません。--target helmでは、--instanceと--instance-namespaceは--managedと併用できません。--no-auto-signと--sign-endpointは互いに排他的です。また、これらと--api-private-ca、--managed、--no-managed、--cluster-nameは、いずれも--signed-certと併用できません。--platform-bundleを使用するには--target helm、--managed、--from-terraformの指定が必要です。また、--no-managedまたは--signed-certとは併用できません。4 つの pool フラグは--platform-bundleを指定しない場合は拒否され、NodePool がすでに存在する場合も拒否されます。--operatorsと--no-gatewayは相互排他的です。--skip-provisionを指定すると、--ch-pod、--ch-user-suffix、--server、--ca-data、--ch-admin-password-stdinは拒否されます (Provisioning は実行されません) 。
clicklink clctl preflight
コネクタのチェック群を、config、files、network、clickhouse、systemd、access、disk、redaction のカテゴリ別に実行します。各チェックの結果は、pass、warn、fail、skip のいずれかで報告されます。終了コード 0 はすべてのチェックが成功したことを示します (警告はノンブロッキングです) 。終了コード 2 は、少なくとも 1 つが失敗したことを示します。 このコマンドはデフォルトでローカルで実行されます。--k8s-namespace を指定すると、kubectl exec を使用してコネクタポッド内のバイナリを実行し、レポートはローカルで表示されます (ポッドでは systemd チェックは常にスキップされます) 。リモートチャネルフラグを指定すると、代わりにリモート VM 上にインストールされたバイナリを実行します。
--k8s-* フラグとリモートチャネルフラグは相互排他的です。いずれか一方のターゲットを選択してください。
clicklink clctl troubleshoot session
サポートセッション (トラブルシューターがコマンドを受け付ける時間制限付きの期間) を有効化、無効化、確認します。アクティブなセッションがない場合、WebSocket が接続されていても、デーモンはすべてのコマンドを拒否します。サポートセッションを参照してください。 コマンドは、次の 2 つのモードのいずれかで動作します。- ローカルファイル (デフォルト) : トラブルシューターが実行されているホスト上のセッション状態ファイル (デフォルト:
/var/lib/clicklink/session.json) の読み取りと書き込みを行います。 - ゲートウェイ:
--gateway-urlを指定すると、OIDC ID トークンを取得し、ワークステーションからトラブルシューターのセッションゲートウェイを呼び出します。
共通フラグ
セッションを有効化
すでにセッションが有効な場合は、有効化できません。先に無効化するか、有効期限が切れるまで待ってください。
session disable
セッションを直ちに無効化します。アクティブなセッションがない場合は何も実行されません。セッションのステータス
セッションがアクティブかどうか、有効化したユーザー、有効期限を表示します。--output (-o) では、table (デフォルト) またはjsonを選択できます。
Kubernetes では、ポートフォワードを使用してゲートウェイにアクセスします。
clicklink clctl troubleshoot gateway trust
VM 上では、セッションゲートウェイ が自己署名 TLS 証明書を提供します。このコマンドは証明書の SHA-256 フィンガープリントを~/.clicklink/clctl.yaml に記録し、session コマンドで検証できるようにします。固定したフィンガープリントが一致しなくなった場合は、フェイルクローズします。信頼は、次の 2 つのいずれかの帯域外の方法で確立されます。
- リモートチャネルフラグを使用する場合、コマンドはすでに認証済みのチャネル経由で VM から証明書を読み取り、固定します。
- チャネルを使用しない場合は、コネクタが証明書の生成時にログに記録した SHA-256 値を
--gateway-fingerprintで指定します。コマンドは、取得した証明書がこの値と一致した場合にのみ固定します。このフラグを省略すると、何も固定せずに提示されたフィンガープリントを表示します。
clicklink clctl troubleshoot audit tail
トラブルシューターの監査ログの末尾のエントリを出力します。改行区切り JSON 形式で、デーモンが受け入れた、またはブロックしたコマンドごとに 1 つのエントリが含まれます。ログは読み取り専用で開かれます。
コネクタのランタイムイメージにはシェルがないため、Kubernetes ではこのコマンドがサポート対象のリーダーです。
アクセスの Provisioning
clicklink clctl scraper access provision と clicklink clctl troubleshoot access provision は、コンポーネントごとのインスタンス単位のアクセスバンドル (読み取り専用の ClickHouse ユーザーとその権限、およびコンポーネントが使用する Kubernetes ServiceAccount、RBAC、トークン) を作成し、--force を指定するとローテーションします。init はインストール時にこれをインラインで実行します。スタンドアロンコマンドは、再実行およびローテーション用です。
1 つのコンポーネントのインスタンス認証情報をローテーションします。
clicklink clctl executor access
init --managed は、ご使用の認証情報で executor のクラスター全体の grant を適用します。適用できない場合、init はクラスター管理者権限を持つ kubeconfig から実行すべきコマンドを出力します。VM では access apply のみ (bundle はステージング済み) 、Kubernetes では access grant の後に access apply を実行します。オンボーディングを参照してください。
executor access grant
executor のクラスター全体のアクセス bundle を<output-dir>/_cluster/ 配下に生成します。生成されるのは、ServiceAccount 1 つ、クラスター ロール と ClusterRoleBinding、および ServiceAccount を executor のネームスペース プレフィックス配下のネームスペースに限定する ValidatingAdmissionPolicy です。適用する前に、生成された RBAC を確認してください。
executor access apply
生成されたクラスター全体の bundlegrant を適用します。対象は、ServiceAccount のホーム ネームスペース、ServiceAccount、クラスター ロールと ClusterRoleBinding、および admission ポリシーで、その後 ServiceAccount トークンを bundle に発行します。service の登録は行いません。
clicklink clctl executor prepare
managed service の作成に必要なユーザー側の準備をすべて整えます。処理は冪等な 1 回の実行にまとめられ、最初の失敗で停止します。service 名の選択または検証を行い、データ用バケットとバックアップ用バケットおよび IAM role の作成 (持ち込んだ role の場合は検証) を行います。VM 上では、さらに service のネームスペース向けに executor のアクセス bundle をレンダリングして適用します。Kubernetes 上では、executor は自身の Pod の ServiceAccount として動作するため bundle をスキップします。その後、default ユーザーの password を発行し (表示は一度きりです) 、instances create 用の作成ボディを書き出します。managed services を参照してください。
VM の場合はコネクタホスト上で実行します。Kubernetes インストールの場合は、AWS credentials と管理対象クラスターの kube コンテキストを備えた workstation 上で実行します。この workstation には、コネクタ設定のコピー (--config) 、executor のローカル API へのポートフォワード、および書き込み可能な --output-dir も必要です。
clicklink clctl executor teardown
ClickHouse Cloud 上で削除された service について、prepare が作成したリソースを削除します。対象は、IAM role、記録された名前、executor が保持する service のレコードで、VM 上ではさらに service の クラスター ロール と ClusterRoleBinding、ローカルの access bundle、registry エントリも含まれます。実行には executor が稼働中で、service が terminated (または stale) である必要があります。service のネームスペースに ClickHouse クラスター がまだ残っている場合、実行は拒否されます。prepare が作成した bucket は、そのデータと backups も含めて、削除を明示的に指定しない限り保持され、保持された bucket には clicklink:retained-from=<name> のタグが付け直されます。このコマンドは、削除を開始する前にすべての情報を読み取ります。delete a service を参照してください。
clicklink clctl instances
instances create
準備済みの create を、connector endpoint 経由で connector 自身の認証情報を用いて ClickHouse Cloud に送信します。作成は環境ごとに有効化されます。サービスの作成 を参照してください。ClickHouse Cloud が割り当てた呼称、state、および サービス name を用いたwatch: のヒントを出力します。create のボディは、prepare が書き出したファイル、または --deployed-name、--data-bucket、--backup-bucket、--irsa-role-arn の4つのフラグの組み合わせから取得されます。同じ入力で再試行した場合は、最初の create が返されます。
instances list
executor が認識しているすべてのサービスを JSON 形式で出力します。--cluster <name> を指定すると、マネージドクラスターでフィルタリングします。
instances get
1 つの service を、作成時に指定された storage とともに JSON 形式で出力します。--name <name> は必須で、クラスターの指定も必須です。--cluster を渡すか、CLCTL_CLUSTER を設定するか、~/.clicklink/clctl.yaml に記述してください。
以下の 3 つのサブコマンドは、ClickHouse Cloud を介さずに executor のローカル API へ直接コマンドを送信します。実行は、account team から依頼された場合のみにしてください。いずれも --name <name> とクラスターの指定 (--cluster、CLCTL_CLUSTER、または ~/.clicklink/clctl.yaml) が必要で、実行したコマンドを JSON 形式で出力します。その id を commands get に渡すと進捗を追跡できます。失敗したコマンドの result には、その error が格納されます。
instances scale
ScalingOverride を使用して、1 つのサービスのサーバーレプリカ数を設定します。--server-replicas <n> は必須で、0 より大きい値を指定する必要があります。executor は、オーバーライドを適用した時点でコマンドを running として報告し、レプリカが ready になった時点で completed として報告します。
instances patch
1 つのサービスをその場で変更します。指定できるパッチは--create-nlb のみで、これを指定しない場合、コマンドは nothing to patch を返して処理を拒否します。このオプションは内部 NLB を Kubernetes の Service としてプロビジョニングし (AWS のみ) 、クラスター外部のスクレイパーからサーバーへ到達できるようにします。エグゼキューターは次回の同期時に、ロードバランサーからスクレイパーのホストをバックフィルします。
instances delete
クラスターから 1 つの service を削除します。service を停止し、operator による順序付けされた shutdown の完了を待機します。その後、ワークロードをアンインストールし、ns-<name> ネームスペースと scraper の artifacts を削除し、ネームスペースが消えるのを待ってから、service を terminated としてマークします。service の bucket と IAM role は残り、executor teardown がお客様の認証情報を使用して削除します。完了済みの削除を再試行しても no-op となります。通常は ClickHouse Cloud 上で service を削除します。delete a service を参照してください。
clicklink clctl コマンド
commands list
executor が記録したコマンドを、新しいものから順に JSON で出力します。失敗したコマンドのresult にはそのエラーが格納されます。承認待ちのプラットフォーム同期の場合は、実行すべき platform approve コマンドがそこに正確に示されます。
commands get
clicklink clctl commands get <id> は、1 つのコマンドを stage と結果とともに出力します。
clicklink clctl platform approve
プラットフォーム変更 1 件を、自分のクラスター認証情報で承認します。executor がステージングしたバンドルを読み取ってハッシュを計算し、その中のすべての chart を executor とまったく同じようにレンダリングします。選択した kube context を使って権限側の半分を適用し、必要に応じて executor のpcm-platform identity を作成したうえで、そのトークンを発行します。connector endpoint へのリクエストは一切行いません。権限側の半分にあたるのは、ネームスペース、CustomResourceDefinition、ServiceAccount、クラスター ロールとその bindings、ロールとその bindings、webhook および admission の設定、PriorityClass、StorageClass です。executor が適用するのはワークロード側の半分のみで、しかもそのトークンが有効な間に限られます。プラットフォームの更新を参照してください。
ClickHouse の registry に直接アクセスする場合は、コネクタの EC2 VM 上で承認を実行してください。CLI はそのインスタンス プロファイルを使い、kubeconfig の認証情報とは独立に、読み取り専用の pull ロールを引き受けます。その他の ECR chart registry では、環境上の AWS 認証情報が使われます。registry の認証情報を参照してください。
clicklink clctl platform reset
サービスが存在しないテストクラスター向け: プラットフォームのリリースを依存関係の逆順でアンインストールし、executor のプラットフォームトークンバンドルを削除することで、初回インストールを再度実行できるようにします。変更を加える前に、このコネクタが所有するネームスペース内の ClickHouse クラスターを一覧表示し、1つでも存在する場合は処理を中止します。CustomResourceDefinition、RBAC、StorageClass は残ります。次回のプラットフォーム同期の前に、再度platform approve を実行してください。
リモートチャネルフラグ
preflight、gateway trust、access provision は、VM ターゲットへの接続方法を選択するためのフラグセットを共有します。