managed service

通过连接器 executor 创建、监控并下线由 ClickHouse Cloud 在您的 Kubernetes 集群 中运维的 ClickHouse 服务

在 managed 模式下，连接器会运行第三个组件 executor。ClickHouse Cloud 正是通过它在你的 Kubernetes 集群中运维 ClickHouse 服务。本页介绍如何创建服务、如何查看服务的 status、ClickHouse Cloud 会对其执行哪些操作，以及它如何退役。

​

managed 模式的作用

executor 是一个守护进程，与 scraper、troubleshooter 一同包含在 clicklink 二进制文件中。它与你的连接器端点之间维持一条出站 WebSocket 通道，并从 ClickHouse Cloud 接收生命周期命令。它会将每条命令应用到为其配置的那一个 Kubernetes 集群上，并通过该通道回报执行结果。与其他组件一样，它只发起出站连接：ClickHouse Cloud 绝不会主动连入你的集群，executor 的本地 API 也仅绑定在回环地址上。

managed 模式在私有预览期间，在使用 S3 存储的 Amazon EKS 上提供。客户团队会在注册你的环境时为你启用。如果 kube context 未指向 EKS 集群，init 会拒绝执行。

每个服务需要三项由你自己拥有的云资源：一个数据桶、一个备份桶，以及一个供 ClickHouse pod (容器组) 承担 (assume) 以访问它们的 IAM role。你需要在服务创建之前用自己的凭证创建这些资源，并在服务删除之后移除它们。executor 不持有你的桶或 IAM 的任何凭证，也绝不会删除数据。它唯一的云端调用面向 Amazon ECR 和 STS：当平台同步或创建操作需要拉取 chart 时，它会登录 registry；在平台更新期间，它会使用只读拉取角色检查镜像。它不会发起任何 S3 或 IAM 调用。它会为每个服务创建一个 LoadBalancer 类型的 Kubernetes Service，由集群的负载均衡控制器在你的账户中落地为一个内部 NLB。

在虚拟机上，executor 以 clicklink-executor systemd 单元的形式与另外两个组件一同运行。在 Kubernetes 上，它是连接器命名空间中的单副本 Deployment。它在端口 8086 上提供健康检查和指标，并在 127.0.0.1:9999 上提供本地 API。

​

启用 managed 模式

managed 模式在 enroll 时选定：向 clicklink clctl init 传入 --managed，或在终端中响应提示。在 VM 上，init 会从当前主机的 kubeconfig 中读取集群 (若其中包含多个 EKS 集群，则通过 --cluster-name 指定) ，并以 Inline 方式授予 executor 的集群级访问权限。在 Kubernetes 上，请通过 --egress-cidrs 传入连接器端点的 CIDR，使 chart 在部署时默认启用其 default-deny NetworkPolicy。

安装过程本身没有变化。完整流程请参阅 onboarding，各命令行参数说明请参阅 CLI reference。

​

创建服务

通过连接器端点创建服务的功能按环境逐一启用；开始之前请与你的客户团队确认。

创建服务需要两条命令。prepare 负责在你这一侧创建所有资源；instances create 则通过你的连接器端点将创建请求提交给 ClickHouse Cloud。ClickHouse Cloud 会生成服务定义，并通过其出站通道将创建请求下发给 executor。executor 将其应用到你的 集群 并回报结果。

只有 prepare 需要 AWS 凭证：它会创建 S3 桶 和 IAM role。instances create 需要连接器的配置和 凭证，且仅在使用 --wait 时才会访问 executor 的本地 API。在 VM 上，请在连接器主机上以 root 身份运行这两条命令。在 Kubernetes 上，请在配置了该 Managed 集群 的 kube context 的工作机上运行这两条命令：

• prepare 需要一份连接器配置的副本 (--config) 、一个指向 executor 本地 API 的 kubectl port-forward，以及一个可写的 --output-dir。它会向 executor 核对 服务 name，若无法连接到 executor 则拒绝运行。
• 当本机缺少配置中所指定的 凭证 文件时，instances create 会从 clicklink-hmac 和 clicklink-mtls Secrets 中读取这些文件，并在每次读取时给出提示。若连接器所在命名空间不是 clicklink，请添加 --connector-namespace。只有 instances create 具备这一 fallback 行为。

1. 准备服务

   Kubernetes

   CONNECTOR_NAMESPACE='clicklink'   # 在 init 时选择的连接器命名空间
   kubectl -n "${CONNECTOR_NAMESPACE}" get configmap clicklink-connector-executor \
     -o jsonpath='{.data.config\.yaml}' > clicklink-config.yaml
   kubectl -n "${CONNECTOR_NAMESPACE}" port-forward deployment/clicklink-connector-executor 9999:9999 &
   clicklink clctl executor prepare --config clicklink-config.yaml --output-dir ./clicklink-access
   

   请保留该输出目录：其中存放着创建请求正文和名称记录，instances create 及任何重试操作都会读取它们。

   Linux VM

   sudo clicklink clctl executor prepare --config /etc/clicklink/config.yaml
   

   该命令按顺序执行四个步骤，并在第一个失败处停止：

   1. 名称。 选取一个服务名称，或校验你通过 --instance <name> 传入的名称。生成的名称会记录在 <output-dir>/_prepare/<eks-cluster-name>.name 中，并在下次运行时沿用，因此重试会复用首次运行的桶和 role。使用 --new-name 可另选一个名称。若某个名称仍被 executor 占用，或其命名空间中已存在 ClickHouse cluster，该命令会拒绝使用该名称。
   2. 存储。 创建数据桶和 backup 桶，以及 IAM role CH-S3-<name>-<region>-00-Role。默认桶名为 <cluster>-clickhouse-data-<rand> 和 <cluster>-clickhouse-backup-<rand>，可通过 --data-bucket 和 --backup-bucket 覆盖。若使用 --role-arn，则只校验你自带的 role，不写入任何 IAM。
   3. 授权与应用。 在 VM 上，为服务命名空间 (ns-<name>) 渲染 executor 的访问支持包，应用其 RBAC，并在 executor 的 registry 中注册该 service。在 Kubernetes 上会跳过此步骤：executor 以其 Pod 的 ServiceAccount 身份运行，并在创建请求到达时自行注册该 service。
   4. 摘要。 生成 default USER 的密码，并将创建请求正文写入 <output-dir>/_prepare/<name>.create.json (mode 为 0600，其中仅包含该密码的哈希值) ，同时在 Next: 行打印下一条应执行的命令。

   prepare 只会在 stderr 上打印一次 default USER 的密码。创建请求正文和 --output json 均不包含该密码，ClickHouse Cloud 也只会收到其哈希值。请先妥善保存，再继续后续操作。若重新运行时发现已有创建请求正文，则会沿用已写入的哈希值，并给出相应提示。

   当 kubeconfig 中包含多个 context 时，请传入 --context <name>；该 context 必须指向配置中 executor.cluster 所指定的 EKS cluster。--dry-run 会执行所有步骤，但不创建或写入任何内容。哈希步骤使用 SHA-1，而 Go 在 GODEBUG=fips140=only 下会拒绝该算法，因此请在未设置该选项的主机上运行 prepare。

2. 提交创建请求

   Kubernetes

   clicklink clctl instances create \
     --from-prepare ./clicklink-access/_prepare/<name>.create.json \
     --config clicklink-config.yaml \
     --wait
   

   请保持 prepare 阶段建立的端口转发处于开启状态：--wait 会通过它轮询 executor。

   Linux VM

   sudo clicklink clctl instances create \
     --from-prepare /etc/clicklink/access/executor/_prepare/<name>.create.json \
     --config /etc/clicklink/config.yaml \
     --wait
   

   该命令会使用连接器自身的 credentials，将准备好的请求正文发送到你的连接器端点，并输出 created <spoken-name> (state provisioning) 以及一条 watch: 提示。<spoken-name> 是 ClickHouse Cloud 分配的名称 (例如 amberaws-kq-42) ，而非你在准备阶段指定的 service name。watch: 提示和所有 clctl 命令使用的都是你的 service name。

   使用相同输入重试是安全的。幂等性 key 默认由你的环境和 service name 派生而来，因此重新提交只会返回首次创建的结果。

   --wait 会每 10 秒轮询一次 executor 的本地 API，直到 service 进入 running 状态，最长等待 --wait-timeout (默认 30m) 。若 executor 记录到该名称的创建失败，或 service 变为 terminating、terminated 或 stale，命令会立即失败并输出所记录的 error。

3. 验证

   clicklink clctl instances get --name <name> --cluster <eks-cluster-name>
   

   当 service 的 status 变为 running 时，表示该 service 已就绪。其 default 用户的密码即为 prepare 输出的密码。--cluster 也可以通过 CLCTL_CLUSTER 环境变量指定。

​

状态

executor 通过其本地 API 响应状态查询，该 API 绑定在 127.0.0.1:9999 上，自身不提供任何身份验证。在 VM 上，直接在主机上运行以下命令；在 Kubernetes 上，请先开启端口转发，再让命令指向转发地址：

kubectl -n <connector-namespace> port-forward deployment/clicklink-connector-executor 9999:9999
clicklink clctl instances list --endpoint http://127.0.0.1:9999

clicklink clctl instances list 会以 JSON 格式输出 executor 已知的所有 服务。clicklink clctl instances get --name <name> --cluster <eks-cluster-name> 则输出其中某一个，并附带其创建时所用的 storage。executor 会根据 服务 的 ClickHouseCluster resource 推导状态 (已就绪的服务器副本数与预期副本数的对比) ，并每隔 sync_interval (默认 30 秒) 刷新一次：

• provisioning：尚无服务器副本就绪，或 ClickHouseCluster 尚不存在
• running：所有预期的服务器副本均已就绪
• degraded：部分 (但非全部) 服务器副本已就绪
• terminating：executor 正在卸载该 服务
• terminated：该 服务 的命名空间已不存在
• stale：该 服务 未经删除操作便已从 executor 的 registry 中移除；--wait 和 teardown 会将其视同 terminated

已终止的 服务 及其 storage 仍会显示在列表中，直到 teardown 移除其云资源为止。

executor 会记录 ClickHouse Cloud 下发的每一条命令。clicklink clctl commands list 可输出这些命令，并支持通过 --status (pending、running、completed、failed) 、--action (例如 create_instance) 或 --cluster 进行过滤。clicklink clctl commands get <id> 会输出单条命令及其 stage 和结果。失败命令的 result 中包含错误信息：例如某次创建为何未能收敛，或哪个平台更新正在等待您的批准。

​

服务生命周期

服务创建后，ClickHouse Cloud 会通过 executor 对其进行运维，所下发的命令包括：

• Scale。 ClickHouse Cloud 设定固定的副本数，并受一项 ClickHouse Cloud 设置的上限限制 (默认配置为 20) 。不支持 autoscaling。
• Stop 与 start。 停止会将服务器缩容至零，但保留 Keeper；启动则恢复原有副本数。整个过程中，数据始终留存在你的桶中。
• Restart。 可针对整个服务、其 Keeper，或单个 pod (容器组) 。
• 备份。 由 ClickHouse Cloud 触发；备份写入你的备份桶，删除备份即会将其移除。
• 版本升级与配置变更。 ClickHouse Cloud 会基于新版本或新设置重新渲染服务定义，并以 create_instance 命令的形式下发，因此 commands list --action create_instance 同样会列出升级操作。executor 应用该定义，并等待副本重新就绪。
• Delete。 详见删除服务。

版本升级与配置变更不设客户审批环节。ClickHouse Cloud 对 managed service 应用这些变更的方式，与执行扩缩容或重启并无二致：重新下发定义，由 executor 让集群收敛到该定义。

创建、扩缩容和启动均以异步方式完成。executor 一旦应用定义，就会将命令报告为运行中，并每 2 分钟发送一次进度报告；待服务器副本就绪后，再报告最终结果。如果副本在 2 小时内仍未就绪，则会将命令报告为失败；若副本之后启动成功，则会将服务重新置为 running。

instances scale、instances patch 和 instances delete 子命令会绕过 ClickHouse Cloud，直接向 executor 的本地 API 提交命令。仅在客户团队要求时才执行这些命令；CLI reference 说明了各个命令的作用。

​

managed service 的 support sessions

executor 会将 scraper 接入它创建的每个 服务，但不会 provision troubleshooter，因此在你完成该操作之前，support session 无法对 managed service 运行诊断。请为每个 服务 各 provision 一次，使用 服务 命名空间 ns-<name>，方式与自行注册的 instance 相同：

Kubernetes

printf '%s\n' "$CH_DEFAULT_PASSWORD" | clicklink clctl troubleshoot access provision --target helm \
  --target-namespace "${CONNECTOR_NAMESPACE}" \
  --instance <name> --instance-namespace ns-<name> \
  --server <kubernetes-api-server-url> --ch-admin-password-stdin \
  --apply-ch-grants --ch-pod <clickhouse-pod-or-label-selector> --ch-pod-namespace ns-<name>

$CH_DEFAULT_PASSWORD 是 prepare 输出的 default 用户密码。该 command 会用它进行身份验证以应用 SQL 授权，并且不会提示输入该密码。然后将 Secret 与 ServiceAccount 这一对资源添加到 troubleshooter.accessBundles，并运行 helm upgrade，具体参见添加 ClickHouse instance。

Linux VM

printf '%s\n' "$CH_DEFAULT_PASSWORD" | sudo clicklink clctl troubleshoot access provision --provider local \
  --instance <name> --instance-namespace ns-<name> \
  --server <kubernetes-api-server-url> --ch-admin-password-stdin

$CH_DEFAULT_PASSWORD 是 prepare 输出的 default 用户密码。

请按上文所示使用 SQL 为 ClickHouse 用户 授权。通过 --ch-user-via cr 添加的用户无法保留：服务 定义归 ClickHouse Cloud 所有，并会被其重新应用。删除 服务 时，executor 会移除 VM 上 troubleshooter 的 bundle；而在 Kubernetes 上，bundle 对应的 Secret 和 ServiceAccount 会一直保留，需要你手动删除，详见卸载。

​

删除服务

连接器端点并未提供面向客户的删除命令：请联系您的客户团队删除该服务。ClickHouse Cloud 会终止该服务，executor 随即删除 workload 及其命名空间 (状态先变为 terminating，再变为 terminated) 。AWS 侧不会有任何改动：桶、桶中的数据以及 IAM role 都会保留，直到您自行删除。

当服务状态变为 terminated 后，即可拆除 prepare 所创建的资源。请在运行 prepare 的同一环境中、使用相同的 AWS 凭证执行 teardown。在 Kubernetes 上，这意味着同一台 workstation、同一份配置副本和输出目录，以及一个已打开的、指向 executor 的端口转发：

Kubernetes

kubectl -n "${CONNECTOR_NAMESPACE}" port-forward deployment/clicklink-connector-executor 9999:9999 &
clicklink clctl executor teardown --instance <name> --config clicklink-config.yaml --output-dir ./clicklink-access

Linux VM

sudo clicklink clctl executor teardown --instance <name>

该命令会读取 executor 中关于该服务的记录：数据存放位置以及它使用的 role。命令会删除 prepare 创建的 IAM role，并让 executor 不再记录该服务，从而释放该名称。在 VM 上，它还会移除该服务的集群级 RBAC 对象、本地访问支持包以及 registry entry。

默认情况下，该服务的数据和备份会被保留。命令会将保留下来的桶的标签由 clicklink:deployed-name 改为 clicklink:retained-from=<name>，以确保同名的新建服务不会继承这些数据，并在摘要中给出数据所在位置。若要一并删除，请在同一命令中添加 --delete-data --delete-backups --yes。

--delete-data 和 --delete-backups 会清空并删除其指定的桶，之后无法恢复。在添加 --yes 之前，请先在记录步骤中核对桶名称。

若不加 --yes，命令会在记录步骤后停止，并列出将被清空的桶名称。--dry-run 只读取，不做任何写入。对于您通过 --role-arn 自带的 role，或并非由 prepare 创建的桶，命令会将其报告为保留，并且不会做任何改动。若该服务的命名空间中仍存在 ClickHouse 集群，命令会拒绝执行。由于它会在删除任何内容之前先读取全部信息，被拒绝的执行不会造成任何更改。

​

当连接器离线时

正在运行的 服务 并不依赖 executor。集群中的 ClickHouse operator 会维持它们继续运行，连接器断开不会中断任何正在提供查询服务的负载。

在没有 executor 连接期间，ClickHouse Cloud 无法向其派发新任务。已经接受的 create、delete 或平台同步会被保留并重试：create 自最后一次进度上报起重试 30 分钟，delete 为 2 小时，平台同步最多重试 10 次。超出该限额后，你的连接器端点会将该命令标记为失败。其余所有生命周期命令 (scale、stop、start、restart、backup、备份删除) 都会被直接拒绝，而不会排队。在没有 executor 连接期间提交的 create 或 delete 同样会被拒绝；只有此前已接受的命令才会重试。

executor 已接受的命令会继续执行直至完成；此前未能上报的结果会在下一次建立连接时发送。

instances create 要求从其运行所在的主机能够访问你的连接器端点。--wait、instances list、instances get 和 commands list 依赖 executor 的本地 API，因此 executor 必须处于运行状态。平台批准的令牌按自身的时钟过期，与连接状态无关；参见批准窗口。