前提条件
- コネクタのエンドポイントと登録トークン。オンボーディング時にClickHouseから提供されます (ステップ1を参照) 。
- インストール時に
https://<subdomain>.<connector-domain>およびhttps://<subdomain>.enroll.<connector-domain>、ならびにreleases.clicklink.clickhouse.comとAmazon ECR Publicへのポート443でのアウトバウンド通信。これらのいずれかに到達できない場合は、エアギャップ環境およびミラーインストールを参照してください。 - コネクタの実行環境から到達可能なClickHouseネイティブリスナー。セキュア (9440) または平文 (9000) で、Kubernetesでは自動検出されます。
- プロビジョニング用のClickHouse管理者アクセス。パスワードなしの
defaultユーザー、パスワード (プロンプトで入力するか、--ch-admin-password-stdinで指定) 、またはオペレーター管理のインスタンスが必要です。後者では、プロビジョニングはCRの挿入に切り替わるため、パスワードは不要です。 - リリースアーティファクトをダウンロードするすべての場所でのcosign。インストーラーは常にSHA-256チェックサムを検証し、cosignがインストールされている場合はcosign署名検証も行います。
CLICKLINK_REQUIRE_COSIGN=1を設定した場合、cosignなしでは続行しません。
- 準拠した任意のKubernetesクラスター。
- コネクタのネームスペースを作成・読み取りでき、Secretの適用、ClickHouseポッド内でのexec (プロビジョニングではポッド内で
clickhouse-clientを実行) 、ServiceAccount、ロール、RoleBindingの作成、およびチャートのインストールが可能なkubeconfig。 - デフォルトのStorageClass、または
--storage-classで指定するクラス。トラブルシューターはPersistentVolumeClaimに状態を保持します。 - イメージ取得アクセス: クラスターのノードは、パブリックECRイメージまたはホストするミラーを取得できる必要があります。
- amd64またはarm64の任意のsystemd Linuxホスト。LinuxビルドはFIPSモードで実行されます。
- インストーラーおよび
init用のrootアクセス。 - 空いているポート8080、8082、8084 (ヘルス) と9090、9092、9094 (メトリクス) 。サポートセッションゲートウェイが有効な場合は、8443も必要です。
- プロビジョニング用のKubernetes APIサーバーへの管理者アクセス。ホスト上のkubeconfig、
--serverと--ca-data、またはプロンプトで指定します。アクセスバンドルは、両方のターゲットでKubernetes ServiceAccountに紐付けられます。
--skip-provisionはKubernetes要件を回避する唯一の方法ですが、ステージング専用です。ClickHouseユーザーのプロビジョニングをスキップし、VMではユニットの有効化と検証もスキップするため、これだけでは実行中のコネクタは作成されません。インストールと登録
1
コネクタのエンドポイントと登録トークンを取得する
ClickHouse は、オンボーディング時にコネクタのエンドポイントと一度限り有効な登録トークンを提供します。エンドポイントの形式は次のとおりです。トークンは1回しか使用できず、すぐに期限切れになるため、受け取ったら速やかに登録を実行してください。シークレットとして扱ってください。CLIはコマンドライン引数、ディスク、ログからは読み取らず、非表示のプロンプト (またはstdinの最初の行) から読み取ります。使用前にトークンの期限が切れた場合は、新しいトークンを取得するためにClickHouseのアカウントチームにお問い合わせください。
2
CLI をインストールして動作を確認する
1 つのコマンドで、検証済みの VM にインストールする場合は、ホスト上で同じスクリプトを どちらの方法でも
clicklink バイナリをインストールできます。このコマンドはプラットフォームとアーキテクチャ (macOS または Linux、amd64 または arm64) を検出し、最新のリリースをダウンロードして SHA-256 チェックサムを検証します。cosign がインストールされている場合はリリース署名も検証し、バイナリを PATH にインストールします。Kubernetes にインストールする場合は、クラスターに kubeconfig でアクセスできる任意のワークステーションでこのコマンドを実行します。--host オプション付きで実行します。ダウンロードの検証後、clicklink システムユーザー、/etc/clicklink、/var/lib/clicklink、/var/log/clicklink の各ディレクトリ、systemd ユニットが作成され、デフォルトの /etc/clicklink/redaction-patterns.yaml も作成されます (既存のファイルがある場合は保持されます) 。これにより、次の手順は登録から直接開始できます。--version vX.Y.Z を指定してリリースを固定でき、いずれも安全に再実行できます。ホストへのインストールでは、以前のバイナリがバックアップされ、現在の設定は保持されます。実行前にスクリプトを確認する場合や、リリースの tarball を自分で取得して検証する場合は、手動ダウンロードと検証を参照してください。3
コネクタを登録してインストールする
登録は 1 つのコマンドで完了します。トークンの引き換え、ClickHouse へのアクセスのプロビジョニング、署名済みクライアント証明書の取得、コネクタのインストール、検証までをエンドツーエンドで実行します。
- Kubernetes
- Linux VM
ワークステーションから、次を実行します。非表示のプロンプトで登録トークンを貼り付けます。続いて CLI から、次の入力を求められます。ClickHouse インスタンスごとに
- コネクタのネームスペース (デフォルトは
clicklink) - ClickHouse インスタンスが実行されるネームスペース
- 検出された ClickHouse Service に基づいて初期設定されるインスタンスの接続情報
- クラスターにデフォルトの StorageClass がない場合にのみ、StorageClass
- サポートセッションの設定方針と、有効にする場合はオペレーターのメールアドレス許可リスト
- SQL によるプロビジョニングで必要な場合にのみ、ClickHouse 管理者パスワード
handoff.yaml として保存) 、Helm values オーバーレイ clicklink-values.yaml を準備し、ネームスペースを作成して clicklink-hmac および clicklink-mtls Secrets を適用します。さらに、各インスタンス用の読み取り専用 ClickHouse ユーザーをプロビジョニングし (operator 管理のインスタンスでは SQL 権限付与または CR 挿入を自動選択) 、秘密鍵と CSR を生成して ClickHouse にクライアント証明書へ署名させます。組み込みの Helm クライアントを使用して clicklink-connector Helm リリースをインストールし (helm バイナリは不要) 、正常性を検証します。無人実行では、代わりにフラグを使用してプロンプトへの応答を指定します。非端末実行では --enroll が stdin の先頭行から登録トークンを読み取るため、リダイレクトしたパスワードまで読み込んでしまいます。そのため、保存済みバンドルをエントリポイントとして使用してください。--instance を指定します。サポートセッションを無効にするには、--operators ではなく --no-gateway を指定します。この 2 つのフラグは同時に使用できません。4
正常に完了したことを確認する
init は、成功を報告する前にインストールを検証します。Kubernetes では、有効な各コンポーネントの /livez エンドポイントを最大 5 分間ポーリングします。さらに、サポートセッションゲートウェイが有効な場合は、ゲートウェイが未認証のプローブに対して 401 を返すことも確認します。VM では、各デーモンの /livez を待機した後、config、ファイル、ポートの競合、ネットワーク到達性、ClickHouse への接続、systemd ユニットの状態、コンポーネントごとのアクセス、ディスク、redaction パターンを含む完全な Preflight スイートを実行します。Kubernetes で手動確認するには:Running 状態で、Ready になっている必要があります。VM で手動で確認するには：0 で終了し、いずれかのチェックが失敗すると 2 で終了して、失敗したチェックを出力します。5
クリーンアップ
登録バンドル 実行中のコネクタは認証情報のコピーを独自に保持するため、運用上このファイルに依存することはありません。アップグレードや設定変更でこのファイルが必要になることはなく、後で再度
handoff.yaml (作業ディレクトリにモード 0600 で書き込まれます) は、インストール中に再実行や復旧を行う際、2つ目のトークンを必要としないようにするためのものです。コネクタの API シークレットが平文で含まれているため、インストールの検証後に削除してください：init を実行する必要が生じた場合は、ClickHouse のアカウントチームに新しい登録トークンを依頼し、init --enroll --force を実行してください。エアギャップ環境およびミラーインストール
--enroll の代わりに clicklink clctl init --handoff <bundle-file> を実行してください。--handoff が置き換えるのはトークンの引き換えだけです。証明書の署名は引き続き登録エンドポイント経由で行われるため、init の実行元からそのエンドポイントにアクセスできる場合にのみ使用してください。
帯域外での証明書署名。 init の実行元から登録エンドポイントにアクセスできない場合は、--no-auto-sign を追加してください。init は必要なものをすべてステージングし、clicklink.csr を書き出します。CSR をアカウントチーム経由で ClickHouse に送信し、返却された証明書とチェーンを使用してインストールを完了します。VM では sudo clicklink clctl init --signed-cert client.crt --chain ca-chain.crt を実行します。Kubernetes では、ステージング実行時に表示される完全な完了コマンド (--target helm を含む) を実行してください。送信されるのは CSR のみで、秘密鍵が環境外に出ることはありません。
Kubernetes では、--chart に、--chart-repo で解決されるチャート名、oci:// 参照、直接 URL、ローカルのアーカイブまたはディレクトリを指定できます。--chart-version はデフォルトで CLI 自身のバージョンとなるため、バイナリとチャートを同じバージョンで扱えます。独自のレジストリからイメージを配信するには、コンテナーイメージをミラーリングし、values オーバーレイで image.repository を設定します。egress パスがコネクタにプライベート CA を提示する場合は、--api-private-ca を指定してください。これにより、API エンドポイントはシステムトラストストアではなく、登録バンドル内の CA チェーンに対して検証されます。
インストーラーはミラーからも利用できます。リリースアーティファクトと install.sh を独自のミラーでホストし、CLICKLINK_MIRROR_URL で指定してください。
手動でのダウンロードと検証
sudo ./install.sh を実行します。リリースアーティファクトの隣に配置すると、--host と同じホストインストールが実行されます。
問題が発生した場合
initは冪等であり、再実行しても同じ状態に収束します。既存のconfigとステージング済みファイルは保持され、完了済みの作業はスキップされます。手順の途中で失敗した場合、CLIは状況に応じた正確な復旧コマンドを出力します。出力されたコマンドは安全に繰り返し実行できます。
登録が拒否された場合、トークンはすでに使用されているか (最終クリーンアップ手順まで存在する--handoff handoff.yamlを指定して再実行してください) 、無効または期限切れです (新しいトークンについてはClickHouseのアカウントチームにお問い合わせください) 。トランスポートエラーにより登録に失敗した場合、トークンは消費されていません。同じコマンドを再実行してください。
--forceは通常の再試行ではなく、明示的なリセットです。保持されているconfigまたはvaluesオーバーレイを上書きし、クライアント秘密鍵を再生成して、有効期限内のクライアント証明書を置き換えます (署名エンドポイントからの409は、すでに証明書が存在することを意味します) 。コネクタのクラスターUUIDは--forceを使用しても保持されるため、再初期化後もコネクタのidentityは維持されます。認証情報のローテーションや証明書の置き換えが必要な場合に使用してください。再実行と復旧の詳細なモデルについては、操作を参照してください。