大网数据广告活动
数据库部署与 SQL 参考

使用 Operator 部署 StarRocks 集群

· 52CE 我爱测

1. 创建 EKS 集群前,请确保环境中已安装如下命令行工具。 - 安装并配置 AWS 的命令行工具 AWS CLI。 - 安装 EKS 集群命令行工具 eksctl。 - 安装 Kubernetes 集群命令行工具 kubectl。 2. 创建 EKS 集群。支持以下两种方式: - 使用 eksctl 快速创建 EKS 集群。 - 使用 AWS 控制台和 AWS CLI 手动创建 EKS 集群。

使用 Operator 部署 StarRocks 集群

本文介绍如何在 Kubernetes 集群上通过 StarRocks Operator 自动化部署和管理 StarRocks 集群。

工作原理

[图示请参阅官方原文]

环境准备

创建 Kubernetes 集群

您可以使用云托管的 Kubernetes 服务,例如 Amazon Elastic Kubernetes Service (EKS) 或者 Google Kubernetes Engine (GKE) 集群,或者私有 Kubernetes 集群。

创建 Amazon EKS 集群

  1. 创建 EKS 集群前,请确保环境中已安装如下命令行工具。
    • 安装并配置 AWS 的命令行工具 AWS CLI。
    • 安装 EKS 集群命令行工具 eksctl。
    • 安装 Kubernetes 集群命令行工具 kubectl。
  2. 创建 EKS 集群。支持以下两种方式:

创建 GKE 集群

创建前,请确保已经完成所有前置工作。创建步骤,请参考创建 GKE 集群。

创建私有 Kubernetes 集群

创建 Kubernetes 集群。如需快速体验本特性,则可以使用 Minikube 创建单节点 Kubernetes 集群。

部署 StarRocks Operator

  1. 添加定制资源 StarRocksCluster。

    kubectl apply -f https://raw.githubusercontent.com/StarRocks/starrocks-kubernetes-operator/main/deploy/starrocks.com_starrocksclusters.yaml
    
  2. 部署 StarRocks Operator。您可以选择使用默认配置文件或者自定义配置文件部署 StarRocks Operator。

    1. 使用默认配置文件部署 StarRocks Operator:

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

      StarRocks Operator 会部署至 Namespace starrocks,并且管理所有 Namespace 下的 StarRocks 集群。

    2. 使用自定义配置文件部署 StarRocks Operator:

      1. 下载用于部署 StarRocks Operator 的配置文件。

        curl -O https://raw.githubusercontent.com/StarRocks/starrocks-kubernetes-operator/main/deploy/operator.yaml
        
      2. 根据您的实际需要,修改配置文件 operator.yaml。

      3. 部署 StarRocks Operator。

        kubectl apply -f operator.yaml
        
  3. 检查 StarRocks Operator 的运行状态。如果 Pod 处于 Running 状态且 Pod 内所有容器都 READY,则表示 StarRocks Operator 成功运行。

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

说明

如果您自定义 StarRocks Operator 所在 Namespace,则需要修改 starrocks 为自定义的 Namespace。

部署 StarRocks 集群

您可以直接使用 StarRocks 提供的配置文件范例,部署 StarRocks 集群(定制资源 StarRocks Cluster 实例化的对象)。例如使用 starrocks-fe-and-be.yaml,部署一个 StarRocks 集群,包含三个 FE 和三个 BE 节点。

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

主要字段说明:

字段 说明
Kind 对象所属资源类型。取值必须为 StarRocksCluster。
Metadata 元数据。内嵌二级字段和说明如下:
  • name:对象名称。同类资源中对象的唯一性标识。
  • namespace:对象所属 Namespace。
Spec 对象的期望状态,包含 starRocksFeSpec、starRocksBeSpec、starRocksCnSpec。

您也可以根据需要修改配置文件,部署 StarRocks 集群。 支持的字段和详细说明,请参见 api.md 。

部署 StarRocks 集群需要一定时间,期间,您可以执行 kubectl -n starrocks get pods 查看 StarRocks 集群启动状态。如果 Pod 处于 Running 状态且 Pod 内所有容器都 READY,则表示 StarRocks 集群已经成功运行。

说明

如果您自定义 StarRocks 集群所在 Namespace,则需要修改 starrocks 为自定义的 Namespace。

$ 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 长时间仍无法启动,您可以通过 kubectl logs -n starrocks <pod_name> 查看日志信息或者通过 kubectl -n starrocks describe pod <pod_name> 查看 Event 信息,以定位问题。

配置 BE 和 CN Core Dump 收集与重启行为

BE 和 CN 容器入口脚本可以监控、压缩并上传 Core Dump,也支持为了调试而重启组件。请在 BE 或 CN 容器中配置以下环境变量:

变量 可选值和默认值 说明
COREDUMP_ENABLED 设置为 true 时启用。其他值(包括未设置)均表示禁用。 启动 Core Dump 上传进程。当组件因 SIGABRT(退出状态码 134)或 SIGSEGV(退出状态码 139)退出时,入口脚本会重启组件,使上传进程继续运行。
DEBUG_MODE 设置为 true 时启用。其他值(包括未设置)均表示禁用调试重启行为。 组件每次退出后都会重启。此行为仅用于调试。
BE_RESTART_WAIT_SECONDS 正整数。默认值:5。 BE 重启前等待的秒数。在 COREDUMP_ENABLED=true 或 DEBUG_MODE=true 时使用。
CN_RESTART_WAIT_SECONDS 正整数。默认值:5。 CN 重启前等待的秒数。在 COREDUMP_ENABLED=true 或 DEBUG_MODE=true 时使用。

Core Dump 收集要求容器镜像中包含 inotifywait、pigz 和 rclone。标准非精简版 Ubuntu BE/CN 镜像包含这些命令;精简版 Ubuntu 镜像和 UBI 镜像不包含。如果启用了 Core Dump 收集但缺少必需命令,BE 或 CN 将拒绝启动,并在容器日志中报告缺少的命令。

访问 StarRocks 集群

访问 StarRocks 集群的各个组件可以通过其关联的 Service 实现,比如 FE Service。Service 的详细说明和访问地址查看,请参考 api.md 和 Service。

说明

  • 默认情况下,仅部署 FE Service。如需部署 BE Service 和 CN Service,则您需要在 StarRocks 集群配置文件 starRocksBeSpec、starRocksCnSpec 中增加配置。
  • Service 的名称默认为 <集群名称>-<组件名称>-service,例如 starrockscluster-sample-fe-service,您也可以在每个组件的 spec 中进行指定 Service 名称。

集群内访问 StarRocks 集群

在 Kubernetes 集群内,通过 FE Service 的 ClusterIP 访问 StarRocks 集群。

  1. 查看 FE Service 内部虚拟 IP 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
    
  2. 在 Kubernetes 集群内通过 MySQL 客户端访问 StarRocks 集群。

    mysql -h 10.100.162.xxx -P 9030 -uroot
    

集群外访问 StarRocks 集群

在 Kubernetes 集群外,支持通过 FE Service 的 LoadBalancer 和 NodePort 访问 StarRocks 集群。本文以 LoadBalancer 为例:

  1. 执行命令 kubectl -n starrocks edit src starrockscluster-sample 更新 StarRocks 集群配置文件,修改 starRocksFeSpec 的 Service 类型为 LoadBalancer。

    starRocksFeSpec:
      image: starrocks/fe-ubuntu:3.0-latest
      replicas: 3
      requests:
        cpu: 4
        memory: 16Gi
      service:            
        type: LoadBalancer # 指定为 LoadBalancer
    
  2. 查询 FE Service 向外部暴露的 IP 地址 EXTERNAL-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                                                      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               ClusterIP      None            <none>                                                                   9030/TCP                                                      23h
    
  3. 登陆您的机器,通过 MySQL 客户端访问 StarRocks 集群。

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

管理 StarRocks 集群

您可以执行命令 kubectl edit 或者 kubectl patch 更新 StarRocks 集群配置文件,来管理 StarRocks 集群。

升级 StarRocks 集群

升级 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 集群和 FE 集群为例。

扩容 BE 集群

执行如下命令,扩容 BE 集群至 9 个节点。

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

缩容 BE 集群

BE 缩容时需要逐个缩容,每次缩容一个 BE 节点, 等待 BE 的 Tablet 在剩余 BE 节点上补齐后再继续扩容。如果存在单副本的表,BE 下线有可能造成数据丢失。 执行如下命令,将有 10 个 BE 节点的集群,缩容至 9 个节点。

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

节点缩容后需要通过 SQL 命令手动 DROP alive 状态为 false 的节点。

下线的 BE 节点的 Tablet 自动补齐需要一些时间,可以通过执行 show proc '/statistic'; 命令查询副本修复进度。

扩容 FE 集群

执行如下命令,扩容 FE 集群至 4 个节点。

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

扩容过程会持续一段时间,您可以通过 kubectl -n starrocks get pods 命令观察扩容进度。

自动扩缩容 CN 集群

执行命令 kubectl -n starrocks edit src starrockscluster-sample 配置 CN 自动扩缩策略。您可以指定资源指标为 CN 的内存和 CPU 平均使用率、触发弹性伸缩的阈值、弹性伸缩上限和下限(即 CN 数量的上下限)。

注意

如果配置了 CN 自动扩缩容策略,则请删除 CN 的 replicas 字段。

Kubernetes 还支持使用 behavior,根据业务场景定制扩缩容行为,实现快速扩容,缓慢缩容,禁用缩容等。更多自动扩容容策略的说明,请参见 Pod 水平自动扩缩。

如下是 StarRocks 提供的 CN 自动扩缩策略模版。

  starRocksCnSpec:
    image: starrocks/cn-ubuntu:latest
    limits:
      cpu: 16
      memory: 64Gi
    requests:
      cpu: 16
      memory: 64Gi
    # when you use autoscalingPolicy, it is recommended that replicas removed from manifests.
    autoScalingPolicy: # Automatic scaling policy of the CN cluster.
      maxReplicas: 10 # The maximum number of CNs is set to 10.
      minReplicas: 1 # The minimum number of CNs is set to 1.
      # operator creates an HPA resource based on the following field.
      # see https://kubernetes.io/docs/concepts/workloads/autoscaling/horizontal-pod-autoscale/ for more information.
      hpaPolicy:
        metrics: # Resource metrics
          - type: Resource
            resource:
              name: memory  # The average memory usage of CNs is specified as a resource metric.
              target:
                # The elastic scaling threshold is 60%.
                # When the average memory utilization of CNs exceeds 60%, the number of CNs increases for scale-out.
                # When the average memory utilization of CNs is below 60%, the number of CNs decreases for scale-in.
                averageUtilization: 60
                type: Utilization
          - type: Resource
            resource:
              name: cpu # The average CPU utilization of CNs is specified as a resource metric.
              target:
                # The elastic scaling threshold is 60%.
                # When the average CPU utilization of CNs exceeds 60%, the number of CNs increases for scale-out.
                # When the average CPU utilization of CNs is below 60%, the number of CNs decreases for scale-in.
                averageUtilization: 60
                type: Utilization
        behavior: # 根据业务场景定制扩缩容行为,实现快速扩容、缓慢缩容、禁用缩容等。
          scaleUp:
            policies:
              - type: Pods
                value: 1
                periodSeconds: 10
          scaleDown:
            selectPolicy: Disabled

主要字段以及说明如下:

  • 水平扩缩时 CN 数量的上限和下限。

    maxReplicas: 10 # CN 数量上限为 10
    minReplicas: 1  # CN 数量下限为 1
    
  • 触发水平扩缩的阈值。

    # 触发水平扩缩容的阈值,例如资源指标为 Kubernetes 集群中 CN CPU 使用率。当 CPU 使用率超过 60% 时,增加 CN 数量进行扩容,低于 60% 时,减少 CN 数量进行缩容。
    - type: Resource
      resource:
        name: cpu
        target:
          averageUtilization: 60
    

常见问题

  • 问题描述:执行 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 创建或者更新资源时,都会添加一个名为 kubectl.kubernetes.io/last-applied-configuration 的 metadata 注解。该 metadata 注解为 JSON 格式,注解值包含了用来创建对象的配置文件的内容。kubectl apply -f xxx 适用于大部分情况,但在极少数情况下,例如定制资源的配置文件过大,则可能会导致 metadata 注解的大小超出上限。
  • 解决措施:如果您是第一次部署定制资源 StarRocksCluster,则建议您使用 kubectl create -f xxx。如果环境中已经部署定制资源,您需要更新定制资源的配置,则建议您使用 kubectl replace -f xxx。

本文来自 StarRocks 文档贡献者,按 Apache 2.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。

资料来源与适用范围

资料来源
StarRocks 文档贡献者
适用范围
main 文档快照(2026-11-16)
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
Apache 2.0

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。