使用 StarRocks Kubernetes Operator 在 Kubernetes 上自动化部署与管理 StarRocks 集群

使用 StarRocks Kubernetes Operator 在 Kubernetes 上自动化部署与管理 StarRocks 集群

【免费下载链接】starrocksThe world's fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks

本文以 StarRocks 官方提供的 Kubernetes Operator 为核心，系统讲解如何在 Kubernetes 集群中自动化部署、升级、扩缩容并运维 StarRocks 集群。读者将掌握通过自定义资源（CRD）StarRocksCluster一键拉起 FE/BE/CN 节点、通过 Service 实现集群内外访问、使用kubectl patch完成滚动升级与扩缩容，以及基于 HPA 为 CN 节点配置自动弹性伸缩的完整实战方案。

Operator 的能力定位与工作原理

StarRocks Kubernetes Operator 是一个Level 2 级别的 Kubernetes Operator（参照 Operator Framework 对 Operator 能力的五级划分，Level 2 意味着 Operator 能够独立完成应用的安装、配置和生命周期管理，而不再依赖人工逐项操作 Kubernetes 对象）。它通过监听自定义资源（Custom Resource）StarRocksCluster的期望状态（Spec），自动创建并持续调和（reconcile）对应的 Kubernetes 工作负载，把"部署与管理一个多节点 StarRocks 集群"这一复杂过程封装为一条简单的kubectl apply命令。

从整体架构上看，Operator 的工作方式如下：

• Deploy（部署）：用户提交StarRocksCluster自定义资源后，Operator 按starRocksFeSpec、starRocksBeSpec、starRocksCnSpec三类期望状态，分别创建FE StatefulSet、BE StatefulSet、CN StatefulSet来管理有状态的 Pod（图中Fpod1~3、Bpod1~3、Cpod1~3）。
• Service（服务暴露）：每个组件配套生成对应的 Service。默认只生成 FE Service 作为统一入口；如需 BE Service 和 CN Service，必须在配置文件的starRocksBeSpec、starRocksCnSpec中显式声明。
• Autoscaler（自动扩缩容）：Operator 根据starRocksCnSpec.autoScalingPolicy配置自动创建 Kubernetes HPA（Horizontal Pod Autoscaler），HPA 通过watch持续观测 CN 的 CPU/内存平均利用率，通过operate对 CN StatefulSet 下发scale指令，动态增减 CN Pod（图中新增的Cpod4）。

集群中的三类节点各司其职（该角色划分在 部署总览 与 共享数据集群部署指南 中亦有印证）：

• FE（Frontend）：负责元数据管理、客户端连接管理、查询规划与查询调度，每个 FE 在内存中维护一份完整元数据副本；
• BE（Backend）：负责数据存储与查询计划执行（shared-nothing 架构）；
• CN（Compute Node）：在存算分离的 shared-data 架构中取代 BE 承担计算职责，数据不落本地，因此可以无数据迁移地进行弹性伸缩。

说明：Kubernetes Operator 方式部署的是使用本地存储的 shared-nothing StarRocks 集群；若需要存算分离架构，可参考 手动部署共享数据集群。

准备工作：创建 Kubernetes 集群

Operator 运行在 Kubernetes 之上，因此第一步是准备一个可用的 Kubernetes 集群。官方支持三类集群来源，读者可根据自身环境任选其一：

使用云托管的 Kubernetes 服务

创建 Amazon EKS 集群

1. 确保环境已安装以下命令行工具：
   • AWS 命令行工具AWS CLI；
   • EKS 集群命令行工具eksctl；
   • Kubernetes 集群命令行工具kubectl。
2. 通过以下任一方式创建 EKS 集群：
   • 使用 eksctl 快速创建 EKS 集群（eksctl create cluster等命令）；
   • 通过 AWS 控制台与 AWS CLI 手动创建 EKS 集群。

创建 Google GKE 集群

开始创建前，先完成 GKE 的账号、项目与计费等前置条件检查，然后按照 GKE 控制台引导创建集群即可。

使用自建 Kubernetes 集群

可以参考 kubeadm 官方文档自建集群；如需最小步骤搭建单节点私有 Kubernetes 集群，可以使用Minikube或Docker Desktop自带的 Kubernetes 功能。

版本要求

根据仓库中 Operator 发布说明 的记录，Operator 对运行环境的要求为：

• Kubernetes：1.18 及以上版本；
• Go：1.19 及以上版本（仅在使用源码自行编译 Operator 时需要，纯部署场景无需关心）。

部署 StarRocks Kubernetes Operator

集群就绪后，依次执行以下三步完成 Operator 的部署。

第 1 步：注册 StarRocksCluster 自定义资源

kubectl apply -f https://raw.githubusercontent.com/StarRocks/starrocks-kubernetes-operator/main/deploy/starrocks.com_starrocksclusters.yaml

该命令会把StarRocksCluster的 CRD（CustomResourceDefinition）安装进集群。执行后，kubectl就认识StarRocksCluster这一资源类型了。CRD 的独立下载路径为starrocks.com_starrocksclusters.yaml，该资源文件同时也会随 Operator 版本发布。

第 2 步：部署 Operator 本体

可以选用默认配置文件或自定义配置文件两种方式。

方式一：使用默认配置文件部署

kubectl apply -f https://raw.githubusercontent.com/StarRocks/starrocks-kubernetes-operator/main/deploy/operator.yaml

默认情况下，Operator 会被部署到starrocks命名空间，并监听（watch）集群中所有命名空间下的 StarRocks 集群。如果你的 Kubernetes 集群规模很大、希望节省 Operator 的内存占用，也可以在 Helm 部署场景中通过watchNamespace字段将监听范围限定到单一命名空间（该能力在 Operator 发布说明 的 v1.8.3 中引入）。

方式二：使用自定义配置文件部署

# 1. 下载 operator.yaml 配置文件 curl -O https://raw.githubusercontent.com/StarRocks/starrocks-kubernetes-operator/main/deploy/operator.yaml # 2. 按需修改配置文件（如调整镜像、副本数、资源配额、namespace 等） # 3. 部署 Operator kubectl apply -f operator.yaml

第 3 步：确认 Operator 运行状态

$ kubectl -n starrocks get pods NAME READY STATUS RESTARTS AGE starrocks-controller-65bb8679-jkbtg 1/1 Running 0 5m6s

当starrocks-controllerPod 的STATUS为Running、且容器READY列为1/1时，说明 Operator 已正常运行。

注意：如果你自定义了 Operator 所在的命名空间，请把上述命令中的starrocks替换为你自定义的命名空间名。

部署 StarRocks 集群

Operator 就绪后，就可以通过自定义资源StarRocksCluster来声明并创建 StarRocks 集群。StarRocks 官方在 operator 仓库的examples/starrocks目录下提供了多份可直接使用的示例配置，例如starrocks-fe-and-be.yaml可以部署一个包含3 个 FE 节点和 3 个 BE 节点的集群：

kubectl apply -f https://raw.githubusercontent.com/StarRocks/starrocks-kubernetes-operator/main/examples/starrocks/starrocks-fe-and-be.yaml

配置文件的三个关键字段

StarRocksCluster配置文件的顶层结构如下表所示：

spec中每个组件可配置的字段非常丰富，例如镜像、副本数、资源请求与限制（requests/limits）、Service 类型等。完整的受支持字段与详细说明参见 Operator 仓库中的api.md（Operator 发布说明 中也有对部分字段演进历史的记录，如storageVolumes挂载、探针超时字段livenessProbeFailureSeconds/readinessProbeFailureSeconds/startupProbeFailureSeconds、terminationGracePeriodSeconds等）。

验证集群启动状态

StarRocks 集群的启动需要一段时间。期间可以用以下命令观察进度：

$ kubectl -n starrocks get pods NAME READY STATUS RESTARTS AGE starrocks-controller-65bb8679-jkbtg 1/1 Running 0 22h starrockscluster-sample-be-0 1/1 Running 0 23h starrockscluster-sample-be-1 1/1 Running 0 23h starrockscluster-sample-be-2 1/1 Running 0 22h starrockscluster-sample-fe-0 1/1 Running 0 21h starrockscluster-sample-fe-1 1/1 Running 0 21h starrockscluster-sample-fe-2 1/1 Running 0 22h

当所有 Pod 的STATUS均为Running、且容器READY均为1/1时，集群即运行正常。

注意：同样地，如果你自定义了集群所在命名空间，请相应替换命令中的starrocks。

排查提示：如果某些 Pod 长时间无法启动，可以用kubectl logs -n starrocks <pod_name>查看日志，或用kubectl -n starrocks describe pod <pod_name>查看事件信息来定位问题。此外，Operator 在集群部署失败时会把错误信息写入StarRocksCluster对象的status.reason字段，可以执行kubectl get starrockscluster <对象名> -oyaml查看该字段获取更直接的失败原因。

管理 StarRocks 集群

集群部署完成后，日常运维主要围绕访问、升级、扩缩容与自动弹性伸缩四个方面展开。

访问 StarRocks 集群

StarRocks 集群的各组件通过关联的 Service 对外暴露。默认情况下只部署 FE Service，BE Service 与 CN Service 需要在配置文件的starRocksBeSpec、starRocksCnSpec中配置后才创建。Service 的命名规则为<集群名>-<组件名>-service，例如starrockscluster-sample-fe-service；也可以在各个组件的spec中自定义 Service 名称。

从 Kubernetes 集群内部访问

集群内部可通过 FE Service 的 ClusterIP 访问：

1. 获取 FE Service 的CLUSTER-IP与端口PORT(S)：

   $ kubectl -n starrocks get svc NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE be-domain-search ClusterIP None <none> 9050/TCP 23m fe-domain-search ClusterIP None <none> 9030/TCP 25m starrockscluster-sample-fe-service ClusterIP 10.100.162.xxx <none> 8030/TCP,9020/TCP,9030/TCP,9010/TCP 25m

   可以看到 FE Service 对外暴露的四个端口，与仓库中 FE 配置文件 的端口定义一一对应：

   FE 端口	对应配置文件参数	用途
   8030	http_port	FE HTTP 服务（Web UI、RESTful API）
   9020	rpc_port	FE 与 FE、BE 之间的 RPC 通信
   9030	query_port	MySQL 协议查询端口
   9010	edit_log_port	FE 元数据 edit log 通信端口

   其中xxx-domain-search是 Operator 为组件内部寻址创建的 Headless Service（ClusterIP: None），用于 StatefulSet 的 Pod 间域名解析。

2. 在集群内部用 MySQL 客户端连接：

   mysql -h 10.100.162.xxx -P 9030 -uroot

从 Kubernetes 集群外部访问

集群外部可以通过 FE Service 的LoadBalancer或NodePort类型访问。下面以 LoadBalancer 为例：

1. 修改集群配置，将starRocksFeSpec的 Service 类型改为LoadBalancer：

   kubectl -n starrocks edit src starrockscluster-sample

   starRocksFeSpec: image: starrocks/fe-ubuntu:3.0-latest replicas: 3 requests: cpu: 4 memory: 16Gi service: type: LoadBalancer # specified as LoadBalancer

2. 获取 FE Service 对外暴露的EXTERNAL-IP与端口：

   $ kubectl -n starrocks get svc NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE be-domain-search ClusterIP None <none> 9050/TCP 127m fe-domain-search ClusterIP None <none> 9030/TCP 129m starrockscluster-sample-fe-service LoadBalancer 10.100.162.xxx a7509284bf3784983a596c6eec7fc212-618xxxxxx.us-west-2.elb.amazonaws.com 8030:30629/TCP,9020:32544/TCP,9030:32244/TCP,9010:32024/TCP 129m

   此时四个 FE 端口都被映射为<NodePort>形式，外部 IP 为云厂商自动分配的负载均衡地址（本例为 AWS ELB）。

3. 在本地宿主机上用 MySQL 客户端连接：

   mysql -h a7509284bf3784983a596c6eec7fc212-618xxxxxx.us-west-2.elb.amazonaws.com -P9030 -uroot

升级 StarRocks 集群

升级的本质是替换组件镜像。Operator 会监听StarRocksCluster中镜像字段的变化，并自动对 StatefulSet 执行滚动更新。可通过kubectl patch命令完成，且无需手动编辑整个配置文件。

升级 BE 节点（指定新的 BE 镜像，例如starrocks/be-ubuntu:latest）：

kubectl -n starrocks patch starrockscluster starrockscluster-sample --type='merge' -p '{"spec":{"starRocksBeSpec":{"image":"starrocks/be-ubuntu:latest"}}}'

升级 FE 节点（指定新的 FE 镜像，例如starrocks/fe-ubuntu:latest）：

kubectl -n starrocks patch starrockscluster starrockscluster-sample --type='merge' -p '{"spec":{"starRocksFeSpec":{"image":"starrocks/fe-ubuntu:latest"}}}'

升级过程会持续一段时间，期间可用kubectl -n starrocks get pods观察滚动更新的进度。

扩缩容 StarRocks 集群

BE 集群扩容

将 BE 集群从当前规模扩容到 9 个节点：

kubectl -n starrocks patch starrockscluster starrockscluster-sample --type='merge' -p '{"spec":{"starRocksBeSpec":{"replicas":9}}}'

BE 集群缩容

缩容 BE 节点时需要逐个进行：每次只减少一个节点，并等待该 BE 上的 tablet 完成重新分布后再进行下一步。如果存在单副本（single replica）的表，且 tablet 未能成功重新分布，则下线该 BE 节点可能导致数据丢失，务必谨慎。

以将 10 个 BE 节点缩容到 9 个为例：

kubectl -n starrocks patch starrockscluster starrockscluster-sample --type='merge' -p '{"spec":{"starRocksBeSpec":{"replicas":9}}}'

缩容完成后，还需要手动下线那些alive状态为false的节点。tablet 重新分布需要一定时间，可以通过执行SHOW PROC '/statistic';查看进度。

FE 集群扩容

将 FE 集群扩容到 4 个节点：

kubectl -n starrocks patch starrockscluster starrockscluster-sample --type='merge' -p '{"spec":{"starRocksFeSpec":{"replicas":4}}}'

从 Operator 的演进记录看（见 Operator 发布说明 v1.9.1），FE 节点数量不能被缩容到 1，这保证了元数据高可用的最低冗余要求。另外，scale-in 与扩容同样可以通过修改配置文件中对应组件的replicas字段后kubectl apply完成，效果与kubectl patch等价。

缩放过程会持续一段时间，可用kubectl -n starrocks get pods观察进度。

CN 集群自动弹性伸缩

CN 节点是存算分离架构下的计算节点，天然适合按负载弹性伸缩。Operator 支持在starRocksCnSpec中配置autoScalingPolicy，由 Operator 自动创建对应的HPA（Horizontal Pod Autoscaler）资源来驱动 CN 扩缩容。

执行以下命令编辑集群配置：

kubectl -n starrocks edit src starrockscluster-sample

可配置的弹性伸缩指标包括：CN 的平均 CPU 利用率、平均内存使用率、弹性伸缩阈值、扩容上限与缩容下限。其中上限与下限通过maxReplicas与minReplicas指定。

注意：配置了 CN 自动伸缩策略后，必须删除starRocksCnSpec中的replicas字段，否则会与 HPA 的副本管理产生冲突。

Kubernetes 还支持通过behavior字段按业务场景自定义伸缩行为（例如快速伸缩、慢速伸缩或完全禁用缩容）。关于 HPA 策略的更多细节可参考 Kubernetes 官方 Horizontal Pod Autoscaling 文档。

StarRocks 官方提供的自动伸缩配置模板（来自 operator 仓库examples/starrocks目录）如下：

starRocksCnSpec: image: starrocks/cn-ubuntu:latest limits: cpu: 16 memory: 64Gi requests: cpu: 16 memory: 64Gi autoScalingPolicy: # 自动伸缩策略 maxReplicas: 10 # CN 最大节点数 minReplicas: 1 # CN 最小节点数 # Operator 会根据以下字段创建 HPA 资源 hpaPolicy: metrics: # 资源指标 - type: Resource resource: name: memory # 以 CN 平均内存使用率作为指标 target: # 弹性伸缩阈值为 60% # CN 平均内存利用率超过 60% 时，增加 CN 数量实现扩容 # CN 平均内存利用率低于 60% 时，减少 CN 数量实现缩容 averageUtilization: 60 type: Utilization - type: Resource resource: name: cpu # 以 CN 平均 CPU 利用率作为指标 target: # 弹性伸缩阈值为 60% averageUtilization: 60 type: Utilization behavior: # 按业务场景自定义伸缩行为，可实现快速/慢速伸缩或禁用伸缩 scaleUp: policies: - type: Pods value: 1 periodSeconds: 10 scaleDown: selectPolicy: Disabled

模板中的关键字段说明如下：

• 弹性伸缩上下限

  maxReplicas: 10 # CN 最大节点数 minReplicas: 1 # CN 最小节点数

  这是 HPA 的maxReplicas/minReplicas，直接限定 CN 副本数的伸缩范围。

• 弹性伸缩阈值

  # 以 CN 平均 CPU 利用率作为资源指标 # 弹性伸缩阈值为 60% # 当 CN 平均 CPU 利用率超过 60% 时，增加 CN 数量进行扩容 # 当 CN 平均 CPU 利用率低于 60% 时，减少 CN 数量进行缩容 - type: Resource resource: name: cpu target: averageUtilization: 60

  多个metrics条目可以同时指定 CPU 与内存两个指标，HPA 将综合判断触发条件。

• behavior 伸缩行为：scaleUp.policies定义了每次扩容在periodSeconds（10 秒）周期内最多新增的 Pod 数（本例为 1 个）；scaleDown.selectPolicy: Disabled则完全禁用了自动缩容。实际部署中可根据业务对弹性的敏感程度调整这些值。

FAQ：安装自定义资源报错处理

问题描述：使用kubectl apply -f xxx安装StarRocksCluster自定义资源时报错：

The CustomResourceDefinition 'starrocksclusters.starrocks.com' is invalid: metadata.annotations: Too long: must have at most 262144 bytes

原因分析：每次使用kubectl apply -f xxx创建或更新资源时，Kubernetes 都会在资源对象上追加一条 JSON 格式的元数据注解kubectl.kubernetes.io/last-applied-configuration，用于记录上一次应用的配置。kubectl apply适用于大多数场景，但在极少数情况下——例如自定义资源配置文件过大——会导致该注解的体积超过 262144 字节（256 KiB）的上限。

解决方案：

• 如果环境中首次安装StarRocksCluster自定义资源，推荐使用kubectl create -f xxx；
• 如果环境中已经安装过该自定义资源、需要更新其配置，推荐使用kubectl replace -f xxx。

延伸：与 Helm 部署方式的关系

除了直接使用 CRD，官方还提供了Helm Chart（kube-starrocks）这一更高层级的部署方式，详细步骤见 使用 Helm 部署 StarRocks。两者的关系是：

• Helm Chart 的底层本质仍是「Operator + StarRocksCluster 自定义资源」，它把 Operator 与 StarRocks 集群的部署打包为kube-starrocks一个 Chart（内含operator与starrocks两个子 Chart），并通过values.yaml暴露常用配置项；
• 通过helm install -f my-values.yaml starrocks starrocks/kube-starrocks可一键同时部署 Operator 与集群（默认 1 FE + 1 BE），并支持在 values 中配置 root 密码初始化、持久化存储（storageSpec）、LoadBalancer 外部访问、FE Proxy（用于集群外 Stream Load 导入）等能力，具体示例可参考 Helm 快速入门；
• 无论采用哪种方式安装，部署完成后的集群对象都是StarRocksCluster，本文介绍的所有管理操作（升级、扩缩容、自动弹性伸缩）同样适用。

如果计划在生产环境长期运行，建议结合 部署总览 了解完整的部署、升级与降级流程，并在部署后参考 集群部署后设置 完成初始账号加固等收尾工作。

【免费下载链接】starrocksThe world's fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks