> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/docs/zh/products/bring-your-own-cloud/connector/onboarding#install-and-enroll)，各命令行参数说明请参阅 [CLI reference](/docs/zh/products/bring-your-own-cloud/connector/reference/cli#init)。

## 创建服务

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

创建服务需要两条命令。`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 行为。

![ClickHouse Connector service lifecycle in managed mode](https://mintcdn.com/private-7c7dfe99/ACBXAWMKzsxeynH5/images/cloud/reference/byoc-connector-service-lifecycle.svg?fit=max\&auto=format\&n=ACBXAWMKzsxeynH5\&q=85\&s=d48f7a4f937db45e469acb110bd41b37)

**1. 准备服务**

**Kubernetes**

```bash theme={null}
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**

```bash theme={null}
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:` 行打印下一条应执行的命令。

> [!WARNING]
>
> `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**

```bash theme={null}
clicklink clctl instances create \
  --from-prepare ./clicklink-access/_prepare/<name>.create.json \
  --config clicklink-config.yaml \
  --wait
```

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

**Linux VM**

```bash theme={null}
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. 验证**

```bash theme={null}
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 上，请先开启端口转发，再让命令指向转发地址：

```bash theme={null}
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](#delete-a-service) 移除其云资源为止。

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

## 服务生命周期

服务创建后，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。** 详见[删除服务](#delete-a-service)。

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

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

`instances scale`、`instances patch` 和 `instances delete` 子命令会绕过 ClickHouse Cloud，直接向 executor 的本地 API 提交命令。仅在客户团队要求时才执行这些命令；[CLI reference](/docs/zh/products/bring-your-own-cloud/connector/reference/cli#instances-scale) 说明了各个命令的作用。

## managed service 的 support sessions

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

**Kubernetes**

```bash theme={null}
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](/docs/zh/products/bring-your-own-cloud/connector/configuration#clickhouse-instances)。

**Linux VM**

```bash theme={null}
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 会一直保留，需要你手动删除，详见[卸载](/docs/zh/products/bring-your-own-cloud/connector/operations#uninstall-kubernetes)。

## 删除服务

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

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

**Kubernetes**

```bash theme={null}
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**

```bash theme={null}
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`。

> [!WARNING]
>
> `--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 必须处于运行状态。平台批准的令牌按自身的时钟过期，与连接状态无关；参见[批准窗口](/docs/zh/products/bring-your-own-cloud/connector/platform-updates#the-approval-window)。