オンボーディング

​

前提条件

​

環境を登録する

• AWS アカウント ID、リージョン、EKS クラスター名
• コネクタを Linux VM 上で実行するか、クラスター内で実行するか
• プラットフォームコンポーネント用の node group
• サービス用のネームスペースプレフィックス (デフォルトは ns-)
• クラスターが ClickHouse イメージを取得する方法: ClickHouse Cloud がお客様のアカウント向けに設定するレジストリアクセスを利用するか、独自のミラーを利用するか

​

すべてのインストールで共通

• コネクタ v0.17.0 以降。 それより前のリリースには Managed モード、platform コマンド、instances create がありません。インストーラーは --version を指定しない限り最新のリリースを提供します。
• 登録時に発行されるコネクタエンドポイントと登録トークン。
• ポート 443 での egress。宛先は https://<subdomain>.<connector-domain> と https://<subdomain>.enroll.<connector-domain>、さらにインストール時には releases.clicklink.clickhouse.com と Amazon ECR Public です。Managed モードでは、プラットフォームの同期や作成処理が ECR から チャート を取得する際に、executor が Amazon ECR と STS にも接続します。これらのいずれかに到達できない場合は、エアギャップ and ミラーインストール を参照してください。
• Managed モードには Amazon EKS クラスター が必要です。init はそれ以外のクラスターでは Managed モードを拒否し、executor なしでインストールする方法として --no-managed を案内します。Terraform on AWS では、新規クラスター用と既存クラスター用のルートモジュールに加え、その上にプラットフォームレイヤーをインストールする init コマンドが提供されています。
• executor の 権限 に必要な クラスター admin 権限。 この 権限 では、executor を自身の prefix 配下の ネームスペース に限定する ClusterRole、ClusterRoleBinding、ValidatingAdmissionPolicy が作成されます。Kubernetes では、init の実行に使う kubeconfig にこの権限が必要です。VM ではホストの kubeconfig に必要で、ホストに admin 権限がない場合、init は権限を持つホストで実行すべきコマンドを出力します。
• ClickHouse はまだ不要です。 Managed インストールは サービス が存在しない状態から始まり、executor が作成した サービス が自動的に登録されます。Managed モードの init は、自身で運用している ClickHouse を登録しません (Kubernetes では --instance と --instance-namespace を拒否します) 。そのようなクラスターを監視するには、--no-managed を指定して別の コネクタ デプロイメント をインストールしてください。--ch-user-suffix を使えば、2 つの デプロイメント が コネクタ の user 名を衝突させることなく同一の インスタンス を共有できます。この デプロイメント には到達可能な native listener が必要で、セキュア接続なら 9440、plaintext なら 9000 を使用し、Kubernetes では自動検出されます。さらに、provisioning のために ClickHouse admin アクセスも必要です。パスワードなしの default user、--ch-admin-password-stdin もしくはプロンプトで渡すパスワード、または operator 管理の インスタンス の場合は CR injection のいずれかを利用します。
• リリースアーティファクトをダウンロードするすべての環境での cosign。 インストーラーは常に SHA-256 checksum を検証します。cosign がインストールされていれば リリース の署名も検証し、CLICKLINK_REQUIRE_COSIGN=1 を指定した場合は cosign なしでの処理続行を拒否します。

​

Kubernetes (Helm) インストールの場合

• kubeconfig：現在のコンテキストが EKS クラスターを指していること。コネクタのネームスペースの作成と読み取り、Secrets の適用、ServiceAccounts、Roles、RoleBindings の作成、チャートのインストール、および executor への クラスター-wide なアクセス権の付与が行える必要があります。
• AWS 認証情報：workstation 上 (環境変数または profile) に、eks:DescribeCluster と ec2:DescribeVpcs の権限を持つもの。init はこれらを使用して、NetworkPolicy 用に クラスターの VPC の CIDR ブロックを読み取ります。ルックアップに失敗した場合は警告を表示し、そのリストは手動で入力できるよう空のまま残します。
• コネクタエンドポイントの背後にある CIDR：インストール時にチャートのデフォルト拒否 NetworkPolicy を有効化するために必要です。指定がない場合、init はポリシーを disabled の状態で配置し、後から有効化する方法を表示します。
• デフォルトの StorageClass、または --storage-class で指定するクラス。troubleshooter と executor は PersistentVolumeClaims 上に state を保持します。
• イメージのプルアクセス：クラスターのノードが、パブリック ECR イメージまたは自身でホストする mirror をプルできる必要があります。

​

Linux VM(systemd)へのインストールの場合

• systemd を使用する任意の Linux ホスト(amd64 または arm64)。Linux 向け builds は FIPS モードで動作します。
• インストーラーおよび init のための root アクセス。
• 空きポート:health と metrics 用に 8082、8084、8086、executor のローカル API 用にループバックインターフェイス上の 9999、support-session gateway を有効化する場合はさらに 8443。
• provisioning および executor の 権限 のための Kubernetes API server への Admin アクセス:ホスト上の kubeconfig、--server と --ca-data、またはプロンプトのいずれか。Access bundles は両方の target で Kubernetes ServiceAccount に紐付けられます。Managed モードでは、kubeconfig の current context が管理対象の EKS クラスターを指している必要があります。それ以外の context を経由した 権限 は init が拒否します。

​

インストールと登録

https://<subdomain>.<connector-domain>

curl -fsSL https://releases.clicklink.clickhouse.com/install.sh | bash

curl -fsSL https://releases.clicklink.clickhouse.com/install.sh | sudo bash -s -- --host

clicklink clctl init --enroll https://<subdomain>.<connector-domain> --target helm --managed

clicklink clctl init --handoff handoff.yaml --target helm --managed \
  --egress-cidrs 203.0.113.0/24 \
  --operators '<operator-email-1>,<operator-email-2>' \
  --storage-class <storage-class>

sudo clicklink clctl init --enroll https://<subdomain>.<connector-domain> --managed

CONNECTOR_NAMESPACE='clicklink'   # the connector namespace you chose at init
kubectl get pods -n "${CONNECTOR_NAMESPACE}"

sudo clicklink clctl preflight

rm handoff.yaml        # workstation (Kubernetes installs)
sudo rm handoff.yaml   # VM host (init ran as root, so the file is root-owned)

​

エアギャップ環境とミラーインストール

​

手動でのダウンロードと検証

CLICKLINK_VERSION="$(curl -fsSL https://releases.clicklink.clickhouse.com/latest-version.txt)"
# Or pin a specific release: CLICKLINK_VERSION='v0.17.0'
CLICKLINK_TARBALL="clicklink-${CLICKLINK_VERSION}-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/').tar.gz"
for suffix in '' .sha256 .sig .crt; do
  curl -fsSLO "https://releases.clicklink.clickhouse.com/${CLICKLINK_TARBALL}${suffix}"
done
if command -v sha256sum >/dev/null; then
  sha256sum -c "${CLICKLINK_TARBALL}.sha256"
else
  shasum -a 256 -c "${CLICKLINK_TARBALL}.sha256"
fi

cosign verify-blob \
  --certificate "${CLICKLINK_TARBALL}.crt" \
  --signature "${CLICKLINK_TARBALL}.sig" \
  --certificate-identity-regexp "^https://github\.com/ClickHouse/data-plane-clicklink/\.github/workflows/release\.yaml@refs/tags/v" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  "${CLICKLINK_TARBALL}"

tar -xzf "${CLICKLINK_TARBALL}"
sudo install -m 0755 clicklink /usr/local/bin/clicklink

​

失敗した場合

• VM 上では、init は失敗しません。バンドルをステージしたうえで、cluster admin 権限を持つ kubeconfig から実行すべきコマンドを警告として出力します。検証用の preflight は executor の state をありのままに報告します。出力されたコマンドを実行し、同じ init コマンドを再実行して検証してください:

sudo env KUBECONFIG=<path> clicklink clctl executor access apply --cluster --config /etc/clicklink/config.yaml

• Kubernetes 上では、権限 が拒否されると chart のデプロイ前に init が停止します。executor は 権限を付与された ServiceAccount にバインドするため、それがないと起動できないからです。ステージングされた overlay、Secrets、CSR は保持され、init は cluster admin 権限を持つ host から実行すべき 2 つのコマンドを出力します。それらを実行したうえで、同じ init コマンドを再実行して続行してください:

clicklink clctl executor access grant --cluster --sa-namespace <connector-namespace> --server <kubernetes-api-server-url> --output-dir <dir>
clicklink clctl executor access apply --cluster --output-dir <dir>