設定箇所
コネクタでは、インストール先ごとに設定箇所が 1 つあります。- Kubernetes
- Linux VM
clicklink clctl init は、作業ディレクトリに clicklink-values.yaml という values オーバーレイを作成し、それを使用して clicklink-connector チャートをデプロイします。このオーバーレイはデプロイメントの永続的な記録です。--force を指定しない限り、init を再実行しても保持されるため、編集内容は再実行後や復旧後も維持されます。このページおよび操作の Day 2 コマンドでは、
helm CLI を使用します。組み込みの Helm クライアントを持つのは init のみです。--repo をミラーに置き換えてください。直接指定したチャート参照 (oci://、URL、またはローカルのアーカイブやディレクトリ。詳細はプライベートミラーを参照) からインストールした場合、解決に使用できるリポジトリはありません。インストール時に使用した参照を指定して、アップグレードを再実行してください。managed モード
managed モードでは executor が動作し、ClickHouse Cloud が主導するサービスのライフサイクルをクラスターに適用します。init は登録時に managed モードを有効化し、クラスターの identity を設定します (managed モードの有効化を参照) 。以下のオプションは、その後に見直す可能性があるものです。設定を変更するには、--force と --managed または --no-managed を付けて init を再実行します。他の init 実行と同様に、entry point の指定が必要です。バンドルを保持している場合は --handoff、新しいトークンを使う場合は --enroll を指定します (再実行と復旧を参照) 。
VM 上では、--no-managed は設定上 executor を無効化しますが、実行中の systemd unit の停止や無効化は行いません。設定を変更する前に停止してください:
executor.enabled: false を設定し、helm upgrade で適用することで executor のデプロイメントを削除します。いずれのターゲットでも、クラスターの権限は明示的に削除するまで残ります。managed モードの停止を参照してください。
- Kubernetes
- Linux VM
init は、kube コンテキストが指している EKS クラスターの情報をもとに、clicklink-values.yaml 内の executor ブロックをステージングします。cluster.namespacePrefixはすべてのコンポーネントで共有され、executor の grant による適用範囲を限定するプレフィックスです。インストール後に変更した場合は、grant を再実行することになります。executor.clusterには、ちょうど 1 つのクラスターを指定します:name、region、accountId、およびinCluster: trueを指定すると、executor はポッドの ServiceAccount として認証されます。その他のキーは snake_case のまま executor にそのまま渡されます (例:s3_storage) 。executor.serviceAccountはcreate: falseのままにします。initがコネクタネームスペース内のpcm-executorServiceAccount に Cluster-wide なアクセスを付与し、チャートは未バインドの ServiceAccount を新規作成するのではなく、その ServiceAccount にバインドします。executor.persistenceは/var/lib/clicklinkの永続化を担います。executor はここにコマンドデータベースとサービスレジストリを保持します。storage を参照してください。executor.platformBundleSecretには、承認済みのプラットフォーム更新を保持する Secret を指定します。このマウントは任意であるため、最初の承認前でもポッドは起動します。プラットフォーム更新を承認する を参照してください。executor.ports.healthは/livezと/metricsを提供します。いずれのコンポーネントにも、メトリクス専用のポートはありません。
helm upgrade を使用します。ClickHouse インスタンスの追加・変更
executor が作成するサービスは自身を登録するため、managed モードではここに追加する必要はありません。本セクションは、executor なしで稼働する別のコネクタデプロイメントに適用されます。このデプロイメントは、ユーザー自身が運用する ClickHouse を監視します。2 つのデプロイメントが 1 つのインスタンスを共有する場合は、そのinit 時に --ch-user-suffix を渡してください。instances 配下の各エントリは、コネクタが読み取る ClickHouse のネイティブプロトコルエンドポイントを指定します。指定項目は host、port、database、secure、cluster、および Kubernetes では namespace です。max_open_conns と max_idle_conns は接続プールの上限を設定します。認証情報を設定に記述することはありません。各コンポーネントは、provisioning が作成するアクセスバンドルから読み取り専用の ClickHouse USER を解決します。
- Kubernetes
- Linux VM
clicklink-values.yaml のトップレベルの instances マップにインスタンスを追加します (VM のレジストリと同じフィールド) 。そのネームスペースを networkPolicy.clickhouseNamespaces に追加します。これはネームスペースの kubernetes.io/metadata.name ラベルに基づいて照合されます。チャートはこのマップを、両方のデーモンが読み取る clicklink-instance-registry ConfigMap にレンダリングします。これは executor.enabled が false の場合にのみ機能します。executor を有効にしている場合、その ConfigMap は executor が所有するため、レンダリングは失敗します。--apply-ch-grants は、生成された ClickHouse 権限を kubectl exec 経由でポッド内に適用します。指定しない場合、コマンドは Kubernetes 側のリソースのみを作成し、適用するための ch-grants.sql をディスクに残します。管理ユーザーにパスワードが設定されている場合は、--ch-admin-password-stdin を追加し、パイプで渡します。--apply-ch-grants の代わりに --ch-user-via cr を使用します (ポッド選択フラグはそのまま使用します) 。詳細は CLI リファレンスを参照してください。次に、各コマンドで作成される Secret と ServiceAccount の組を対応する accessBundles マップに設定し、上記の helm upgrade を実行します。Operator 許可リスト
operator のメールアドレスの許可リストが、ゲートウェイで管理されるセッションを制限します。セッションゲートウェイへのすべてのリクエストには、証明済みメールアドレスがリストに含まれている、短期間有効な OIDC ID トークンが必要です。許可リストが空の場合、ゲートウェイは閉鎖されます。VM では、ホストの root ユーザーはローカルのセッションファイルを通じてセッションを直接管理することもできます。許可リストはゲートウェイ経由の経路にのみ適用されます。信頼モデルの詳細については、サポートセッションを参照してください。- Kubernetes
- Linux VM
許可リストはオーバーレイで定義され、チャートがそれを ConfigMap にレンダリングします。変更するには、リストを編集して
helm upgrade を実行します。ネットワークポリシーと egress
Kubernetes では、このチャートは egress の 許可リスト を伴うデフォルト拒否の NetworkPolicy を同梱しています。NetworkPolicy オブジェクトは、CNI がこれを適用する場合にのみ有効になります。適用を行う CNI 配下では、2 つの CIDR リストの両方が入力されるまで、到達できるのはクラスター DNS と ClickHouse Service のネームスペースのみです。それまでは、コネクタから コネクタエンドポイント や Kubernetes API server への egress はありません。init は、コネクタエンドポイント の背後にある CIDR が判明している場合にのみ、ポリシーを enabled の状態でステージングします。
allowEgressCIDRsは利用者側で指定します。コネクタエンドポイントの背後にある範囲を、インストール時に--egress-cidrsで指定するか、プロンプトで入力します。すべてのコンポーネントが、コネクタエンドポイントに到達するためにこれを必要とします。managedモードでプラットフォームのチャートがAmazon ECRに置かれている場合は、対象リージョンのECRおよびSTSの範囲 (あるいは自身のミラーの範囲) を追加してください。これらがないと、ポリシーによってexecutorのチャート取得が失敗します。apiserverCIDRsは、managedモードではEKS clusterのVPC (eks:DescribeClusterおよびec2:DescribeVpcs) からinitが導出します。すべてのコンポーネントがKubernetesのトークンリクエストを発行し、executorはAPI経由でサービスを制御するため、強制適用されるCNIの下では、これが設定されるまですべてブロックされます。ルックアップに失敗した場合、initは警告を出してリストを空のままにするので、利用者がVPCのCIDRブロックを記入してください。
clicklink.clickhouse.com/managed-by: executor というラベルが付与され、ポリシーはそのラベルを基に許可します。そのため、managedインストールでは clickhouseNamespaces を空のままにできます。名前で列挙する必要があるのは、自身で運用するClickHouse向けにexecutor外で作成されたネームスペースのみです。
ポリシーを後から有効化する。 インストール時にエンドポイントのCIDRを省略した場合、init は allowEgressCIDRs: [] とともに enabled: false を設定し、設定を完了するための手順を出力しています。CIDRが判明したら、clicklink-values.yaml で enabled: true と allowEgressCIDRs を設定し、apiserverCIDRs にVPCの範囲が含まれていることを確認したうえで、設定箇所 に示す helm upgrade を実行してください。
セッションゲートウェイを有効にしている場合、もう1つ重要なegressルールがあります。clctl.gateway.jwksEgressCIDRs です。トラブルシューターはoperator tokensを検証するためにidentity providerのJWKSをフェッチするため、default-denyの下でリストが空だと、すべてのトークン検証がブロックされます。
private.googleapis.com の range は、Private Google Access 経由で到達する Google の identity provider をカバーします。それ以外の identity provider を使用する場合は、その range、またはその前段に配置された egress proxy の CIDR を指定してください。
残る ingress 関連のオプションは 2 つです。metricsScrapeSelector は metrics-scrape の ingress を label によって 1 つの Prometheus ネームスペースに限定し、kubeletProbeCIDRs は厳格なデフォルト拒否の下でキューブレットの health probe を明示的に許可します。オプションの完全な一覧については、設定リファレンスを参照してください。
マスキングパターン
トラブルシューター は、出力が境界外に送信される前にマスキングします。組み込みパターンでは、ipv4、ipv6、bearer-token、aws-access-key、email、jwt、ssh-private-key、connection-string-credentials を対象とします。独自のパターンは YAML ファイルに追加してください。独自のパターンはファイル内の記述順に最初に実行され、その後に組み込みパターンが実行されます。また、組み込みパターンと同じ name を使用するエントリは、その組み込みパターンを置き換えます。
各パターンでは、name (必須、一意) 、regex (必須、Go RE2 構文) 、replace (デフォルトは [REDACTED]、$1 のキャプチャ参照をサポート) 、case_insensitive (デフォルトは false) を指定します。
/etc/clicklink/redaction-patterns.yaml にあります。インストーラーは、有効なパターンの初期セット (third-party の API key、AWS のシークレットキーなど) を投入します。このセットは削減または拡張できます。インストーラーはアップグレード時にも独自のバージョンを保持します。Kubernetes では、YAML を redaction-patterns.yaml キーの ConfigMap に格納し、troubleshooter.redaction.patternsConfigMap にその名前を設定します。チャート はこれを同じパスにマウントします。
プライベートミラーと境界内のエンドポイント
公開されているチャートでは、image.repository にパブリックなマルチアーキテクチャ対応のcosign署名済みコネクタイメージが事前設定されているため、通常のインストールではイメージ値を指定する必要はありません。公開されているデフォルトを確認するには:
init の --chart に、--chart-repo を基準に解決されるチャート名、直接指定する oci:// 参照、URL、ローカルのアーカイブまたはディレクトリを指定できます。--chart-version のデフォルトは CLI 自身のバージョンのため、バイナリとチャートのバージョンが連動します。
init に --api-private-ca を渡します。これにより api.tls.caFile: /etc/clicklink/secrets/mtls/ca.crt が設定され、コネクタはシステムルートに加えて登録バンドルの CA チェーンを使用してエンドポイントを検証します。VM では、これに相当する設定は /etc/clicklink/config.yaml の api.tls.ca_file です。init はバンドルのチェーンを /etc/clicklink/tls/ca.crt にインストールし、コネクタは同様にそれをシステムルートへ追加します。完全に air-gapped な環境での登録と証明書署名については、オンボーディングを参照してください。
ストレージ
- Kubernetes
- Linux VM
2つのコンポーネントがPersistentVolumeClaimに状態を保持します。トラブルシューター側のPVCにはセッション状態と監査証跡が格納されます。executor側のPVCにはコマンドデータベースと、管理対象サービスのレジストリが格納されます。
init は両方の storageClass の値を、選択したクラスに設定します。storageClass が空の場合はクラスターのデフォルトStorageClassが使用されます。クラスターにデフォルトが設定されていない場合、init はプロンプトまたは --storage-class での指定を求めます。executorのクレームには helm.sh/resource-policy: keep のアノテーションが付与されているため、helm uninstall を実行してもそのまま残ります。アンインストールを参照してください。