> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-vortex-format.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# managed service

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

export const Image = ({img, alt, size = "lg", background}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  const backgroundColor = background === "white" ? "white" : background === "black" ? "rgb(31 31 28)" : undefined;
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} style={{
    backgroundColor
  }} />
      </Frame>
    </div>;
};

export const PrivatePreviewBadge = () => {
  return <div className="privatePreviewBadge">
            <div className="privatePreviewIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path d="M5.33301 6.66667V4.66667V4.66667C5.33301 3.194 6.52701 2 7.99967 2V2C9.47234 2 10.6663 3.194 10.6663 4.66667V4.66667V6.66667" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path d="M8.00033 9.33337V11.3334" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path fillRule="evenodd" clipRule="evenodd" d="M11.333 14H4.66634C3.92967 14 3.33301 13.4033 3.33301 12.6666V7.99996C3.33301 7.26329 3.92967 6.66663 4.66634 6.66663H11.333C12.0697 6.66663 12.6663 7.26329 12.6663 7.99996V12.6666C12.6663 13.4033 12.0697 14 11.333 14Z" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            {'私有预览'}
        </div>;
};

<PrivatePreviewBadge />

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

<h2 id="what-managed-mode-does">
  managed 模式的作用
</h2>

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。

<h2 id="enable-managed-mode">
  启用 managed 模式
</h2>

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

安装过程本身没有变化。完整流程请参阅 [onboarding](/zh/products/bring-your-own-cloud/connector/onboarding#install-and-enroll)，各命令行参数说明请参阅 [CLI reference](/zh/products/bring-your-own-cloud/connector/reference/cli#init)。

<h2 id="create-a-service">
  创建服务
</h2>

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

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

<Image img="https://mintcdn.com/private-7c7dfe99-vortex-format/wGEkZpH7GS15Wa4H/images/cloud/reference/byoc-connector-service-lifecycle.svg?fit=max&auto=format&n=wGEkZpH7GS15Wa4H&q=85&s=14eac921a706075c4813bdc9b0cc9b45" size="lg" alt="ClickHouse Connector service lifecycle in managed mode" width="1320" height="870" data-path="images/cloud/reference/byoc-connector-service-lifecycle.svg" />

<Steps>
  <Step title="准备服务" id="prepare">
    <Tabs>
      <Tab title="Kubernetes" id="prepare-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` 及任何重试操作都会读取它们。
      </Tab>

      <Tab title="Linux VM" id="prepare-vm">
        ```bash theme={null}
        sudo clicklink clctl executor prepare --config /etc/clicklink/config.yaml
        ```
      </Tab>
    </Tabs>

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

    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 也只会收到其哈希值。请先妥善保存，再继续后续操作。若重新运行时发现已有创建请求正文，则会沿用已写入的哈希值，并给出相应提示。
    </Warning>

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

  <Step title="提交创建请求" id="create">
    <Tabs>
      <Tab title="Kubernetes" id="create-kubernetes">
        ```bash theme={null}
        clicklink clctl instances create \
          --from-prepare ./clicklink-access/_prepare/<name>.create.json \
          --config clicklink-config.yaml \
          --wait
        ```

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

      <Tab title="Linux VM" id="create-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
        ```
      </Tab>
    </Tabs>

    该命令会使用连接器自身的 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。
  </Step>

  <Step title="验证" id="verify">
    ```bash theme={null}
    clicklink clctl instances get --name <name> --cluster <eks-cluster-name>
    ```

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

<h2 id="status">
  状态
</h2>

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` 中包含错误信息：例如某次创建为何未能收敛，或哪个[平台更新](/zh/products/bring-your-own-cloud/connector/platform-updates)正在等待您的批准。

<h2 id="service-lifecycle">
  服务生命周期
</h2>

服务创建后，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 让集群收敛到该定义。
</Warning>

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

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

<h2 id="support-sessions">
  managed service 的 support sessions
</h2>

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

<Tabs>
  <Tab title="Kubernetes" id="troubleshooter-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](/zh/products/bring-your-own-cloud/connector/configuration#clickhouse-instances)。
  </Tab>

  <Tab title="Linux VM" id="troubleshooter-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` 用户密码。
  </Tab>
</Tabs>

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

<h2 id="delete-a-service">
  删除服务
</h2>

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

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

<Tabs>
  <Tab title="Kubernetes" id="teardown-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
    ```
  </Tab>

  <Tab title="Linux VM" id="teardown-vm">
    ```bash theme={null}
    sudo clicklink clctl executor teardown --instance <name>
    ```
  </Tab>
</Tabs>

该命令会读取 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` 之前，请先在记录步骤中核对桶名称。
</Warning>

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

<h2 id="when-the-connector-is-offline">
  当连接器离线时
</h2>

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