引导

​

前置条件

​

注册你的环境

• 你的 AWS 账户 ID、region 以及 EKS 集群名称
• 连接器是运行在 Linux VM 上，还是运行在集群中
• 用于平台 components 的 node group
• 服务的命名空间 prefix (默认为 ns-)
• 你的集群以何种方式拉取 ClickHouse 镜像：通过 ClickHouse Cloud 为你的 account 配置的 registry access，还是使用你自己的 mirror

​

所有安装方式通用

• 连接器 v0.17.0 或更高版本。 更早的发行版没有托管模式、platform 命令或 instances create。除非你传入 --version，安装程序会提供最新发行版。
• 你的连接器端点和注册标记，在注册时提供。
• 443 端口出站访问权限，目标为 https://<subdomain>.<connector-domain> 和 https://<subdomain>.enroll.<connector-domain>，以及安装时访问 releases.clicklink.clickhouse.com 和 Amazon ECR Public。在托管模式下，当平台同步或创建操作从 ECR 拉取 chart 时，executor 还会访问 Amazon ECR 和 STS。若其中任何一项无法访问，请参阅隔离网络与 mirror 安装。
• 一个 Amazon EKS 集群，用于托管模式。在其他任何集群上，init 都会拒绝启用托管模式，并提示使用 --no-managed 在不安装 executor 的情况下完成安装。在 AWS 上使用 Terraform 提供了分别适用于新集群和现有集群的根模块，以及在其之上安装平台层的 init 命令。
• 用于 executor 授权的集群管理员权限。 该授权会创建一个集群角色、一个 ClusterRoleBinding 和一个 ValidatingAdmissionPolicy，将 executor 限制在你的前缀下的命名空间内。在 Kubernetes 上，运行 init 时使用的 kubeconfig 需要该权限。在 VM 上，则是主机的 kubeconfig 需要该权限；若主机不具备管理员权限，init 会打印出应在具备该权限的主机上运行的命令。
• 尚未部署 ClickHouse。 托管安装从零个服务开始；由 executor 创建的服务会自行注册。在托管模式下，init 不会注册任何你自行运行的 ClickHouse (在 Kubernetes 上会拒绝 --instance 和 --instance-namespace) 。若要观测这类集群，请使用 --no-managed 单独安装一套连接器部署。借助 --ch-user-suffix，两套部署可以共用同一个实例，而不会在连接器的用户上发生冲突。该部署需要一个可访问的原生监听端口，安全端口 9440 或明文端口 9000，在 Kubernetes 上会自动检测。它还需要用于预配的 ClickHouse 管理员访问权限：一个无密码的 default 用户、通过 --ch-admin-password-stdin 或在提示符处输入的密码，或者对由 operator 管理的实例使用 CR 注入。
• cosign，凡是下载发行制品的位置都需要。安装程序始终会校验 SHA-256 校验和。若已安装 cosign，还会校验发行版签名；设置 CLICKLINK_REQUIRE_COSIGN=1 后，缺少 cosign 时将拒绝继续执行。

​

Kubernetes (Helm) 安装

• 一个 kubeconfig，其当前 context 指向目标 EKS 集群。它必须能够创建和读取连接器命名空间、应用 Secrets、创建 ServiceAccounts、Roles 和 RoleBindings、安装 chart，并为 executor 授权集群级访问权限。
• 工作站上具备 eks:DescribeCluster 和 ec2:DescribeVpcs 权限的 AWS 凭证 (来自环境变量或 profile) 。init 会用它们读取集群 VPC 的 CIDR 块，用于配置 NetworkPolicy。若读取失败，它会发出警告，并将该列表留给你自行填写。
• 连接器端点背后的 CIDR，用于在安装时启用 chart 的默认拒绝 NetworkPolicy。若缺少这些信息，init 会以禁用状态部署该策略，并输出后续启用方法。
• 一个默认存储类，或通过 --storage-class 指定的存储类；故障排查工具和 executor 会将状态保存在 PersistentVolumeClaims 上。
• 镜像拉取权限：集群节点必须能够拉取公共 ECR image，或你自行托管的 mirror。

​

Linux VM (systemd) 安装

• 任意 systemd Linux 主机，amd64 或 arm64。Linux 构建以 FIPS 模式运行。
• 安装程序和 init 需要 root 权限。
• 空闲端口：8082、8084 和 8086 用于健康状况与指标，回环接口上的 9999 用于 executor 的本地 API，启用支持会话网关时还需 8443。
• 对 Kubernetes API server 的管理员访问权限，用于预配以及 executor 的授权：可通过主机上的 kubeconfig、--server 与 --ca-data 参数，或交互式提示提供。访问包在两侧目标上均锚定到 Kubernetes ServiceAccount。在托管模式下，kubeconfig 的当前 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 不会失败。它会暂存该支持包，并打印一条警告，其中给出需要在具备集群管理员权限的 kubeconfig 下执行的准确命令。验证性预检会如实报告 executor 的状态。执行打印出的命令，然后重新运行相同的 init 命令进行验证：

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

• 在 Kubernetes 上，被拒绝的授权会在 chart 部署之前中止 init，因为 executor 需要绑定到已授权的 ServiceAccount，缺少它便无法启动。已暂存的覆盖文件、Secrets 和 CSR 会被保留，init 会打印出两条命令，需在具备集群管理员权限的主机上执行。执行完这两条命令后，再次运行相同的 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>