StarRocks Kubernetes Operator
使用 StarRocks Kubernetes Operator 在 Kubernetes 集群上自动化部署和管理 StarRocks 集群。
StarRocks k8s operator 被设计为一个二级 (level 2) Operator。请参阅 https://sdk.operatorframework.io/docs/overview/operator-capabilities/ 以了解有关二级 Operator 功能的更多信息。
工作原理
开始之前
创建 Kubernetes 集群
您可以使用云托管的 Kubernetes 服务，例如 Amazon Elastic Kubernetes Service (EKS) 或 Google Kubernetes Engine (GKE) 集群，或自托管的 Kubernetes 集群。
-
创建 Amazon EKS 集群
- 确认 您的环境中已安装以下命令行工具
- 安装并配置 AWS 命令行工具 AWS CLI。
- 安装 EKS 集群命令行工具 eksctl。
- 安装 Kubernetes 集群命令行工具 kubectl。
- 使用以下任一方法创建 EKS 集群
- 确认 您的环境中已安装以下命令行工具
-
创建 GKE 集群
在开始创建 GKE 集群之前，请确保您已完成所有 先决条件。然后按照 创建 GKE 集群 中提供的说明创建 GKE 集群。
-
创建自托管的 Kubernetes 集群
按照 使用 kubeadm 引导集群 中的说明创建自托管的 Kubernetes 集群。您可以使用 Minikube 和 Docker Desktop 以最少的步骤创建单节点私有 Kubernetes 集群。
部署 StarRocks Kubernetes Operator
-
添加自定义资源 StarRocksCluster。
kubectl apply -f https://raw.githubusercontent.com/StarRocks/starrocks-kubernetes-operator/main/deploy/starrocks.com_starrocksclusters.yaml -
部署 StarRocks Operator。您可以选择使用默认配置文件或自定义配置文件来部署 StarRocks Operator。
-
使用默认配置文件部署 StarRocks Operator。
kubectl apply -f https://raw.githubusercontent.com/StarRocks/starrocks-kubernetes-operator/main/deploy/operator.yamlStarRocks Operator 部署到
starrocks命名空间中，并管理所有命名空间下的所有 StarRocks 集群。 -
使用自定义配置文件部署 StarRocks Operator。
-
下载用于部署 StarRocks Operator 的配置文件 operator.yaml。
curl -O https://raw.githubusercontent.com/StarRocks/starrocks-kubernetes-operator/main/deploy/operator.yaml -
修改配置文件 operator.yaml 以满足您的需求。
-
部署 StarRocks Operator。
kubectl apply -f operator.yaml
-
-
-
检查 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 所在的命名空间，则需要将
starrocks替换为您自定义的命名空间名称。
部署 StarRocks 集群
您可以直接使用 StarRocks 提供的 示例配置文件 来部署 StarRocks 集群（使用自定义资源 StarRocks Cluster 实例化的对象）。例如，您可以使用 starrocks-fe-and-be.yaml 部署一个包含三个 FE 节点和三个 BE 节点的 StarRocks 集群。
kubectl apply -f https://raw.githubusercontent.com/StarRocks/starrocks-kubernetes-operator/main/examples/starrocks/starrocks-fe-and-be.yaml
下表描述了 starrocks-fe-and-be.yaml 文件中一些重要字段的含义。
| 字段 | 描述 |
|---|---|
| Kind | 对象的资源类型。值必须为 StarRocksCluster。 |
| 元数据 | Metadata，其中嵌套以下子字段
|
| Spec | 对象的期望状态。有效值包括 starRocksFeSpec、starRocksBeSpec 和 starRocksCnSpec。 |
您也可以使用修改后的配置文件部署 StarRocks 集群。有关支持的字段和详细说明，请参阅 api.md。
部署 StarRocks 集群需要一段时间。在此期间，您可以使用命令 kubectl -n starrocks get pods 检查 StarRocks 集群的启动状态。如果所有 Pod 都处于 Running 状态，并且 Pod 内的所有容器都处于 READY 状态，则 StarRocks 集群正在按预期运行。
注意
如果您自定义了 StarRocks 集群所在的命名空间，则需要将
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 无法启动，您可以使用 kubectl logs -n starrocks <pod_name> 查看日志信息，或使用 kubectl -n starrocks describe pod <pod_name> 查看事件信息以定位问题。
管理 StarRocks 集群
访问 StarRocks 集群
可以通过与组件关联的 Service（例如 FE Service）访问 StarRocks 集群的组件。有关 Service 及其访问地址的详细说明，请参阅 api.md 和 Services。
- 默认情况下只部署 FE Service。如果您需要部署 BE Service 和 CN Service，则需要在 StarRocks 集群配置文件中配置
starRocksBeSpec和starRocksCnSpec。 - Service 的名称默认为
<cluster name>-<component name>-service，例如starrockscluster-sample-fe-service。您也可以在每个组件的 spec 中指定 Service 名称。
从 Kubernetes 集群内部访问 StarRocks 集群
从 Kubernetes 集群内部，可以通过 FE Service 的 ClusterIP 访问 StarRocks 集群。
-
获取 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 -
从 Kubernetes 集群内部使用 MySQL 客户端访问 StarRocks 集群。
mysql -h 10.100.162.xxx -P 9030 -uroot
从 Kubernetes 集群外部访问 StarRocks 集群
从 Kubernetes 集群外部，可以通过 FE Service 的 LoadBalancer 或 NodePort 访问 StarRocks 集群。本主题以 LoadBalancer 为例
-
运行命令
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 # specified as LoadBalancer -
获取 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 -
登录到您的机器宿主机，并使用 MySQL 客户端访问 StarRocks 集群。
mysql -h a7509284bf3784983a596c6eec7fc212-618xxxxxx.us-west-2.elb.amazonaws.com -P9030 -uroot
升级 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 集群
运行以下命令将 BE 集群扩容到 9 个节点
kubectl -n starrocks patch starrockscluster starrockscluster-sample --type='merge' -p '{"spec":{"starRocksBeSpec":{"replicas":9}}}'
缩容 BE 集群
缩容 BE 节点时，需要逐个缩容，并等待 BE 上的 Tablet 分布后再进行下一步操作。如果存在只有单个副本的表，将一个 BE 节点下线可能会导致数据丢失，如果 Tablet 未能重新分配。
执行以下命令将拥有 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}}}'
扩容过程需要一段时间。您可以使用命令 kubectl -n starrocks get pods 查看扩容进度。
CN 集群的自动扩缩容
运行命令 kubectl -n starrocks edit src starrockscluster-sample 配置 CN 集群的自动扩缩容策略。您可以指定 CN 的资源指标作为平均 CPU 利用率、平均内存使用率、弹性扩缩容阈值、弹性扩缩容上限和弹性扩缩容下限。弹性扩缩容上限和弹性扩缩容下限分别指定弹性扩缩容允许的最大 CN 数量和最小数量。
如果配置了 CN 集群的自动扩缩容策略，请从 StarRocks 集群配置文件的 starRocksCnSpec 中删除 replicas 字段。
Kubernetes 还支持使用 behavior 根据业务场景自定义扩缩容行为，帮助您实现快速或慢速扩缩容或禁用扩缩容。有关自动扩缩容策略的更多信息，请参阅 水平 Pod 扩缩容。
以下是 StarRocks 提供的 模板，以帮助您配置自动扩缩容策略
starRocksCnSpec:
image: starrocks/cn-ubuntu:latest
limits:
cpu: 16
memory: 64Gi
requests:
cpu: 16
memory: 64Gi
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.ac.cn/docs/tasks/run-application/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: # The scaling behavior is customized according to business scenarios, helping you achieve rapid or slow scaling or disable scaling.
scaleUp:
policies:
- type: Pods
value: 1
periodSeconds: 10
scaleDown:
selectPolicy: Disabled
下表描述了一些重要字段
- 弹性扩缩容的上限和下限。
maxReplicas: 10 # The maximum number of CNs is set to 10.
minReplicas: 1 # The minimum number of CNs is set to 1.
- 弹性扩缩容阈值。
# For example, the average CPU utilization of CNs is specified as a resource metric.
# 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.
- type: Resource
resource:
name: cpu
target:
averageUtilization: 60
常见问题解答 (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 创建或更新资源时，都会添加一个元数据注释 kubectl.kubernetes.io/last-applied-configuration。此元数据注释为 JSON 格式，记录了最后应用的配置。kubectl apply -f xxx 适用于大多数情况，但在极少数情况下，例如自定义资源配置文件过大时，可能会导致元数据注释的大小超过限制。
解决方案： 如果您首次安装自定义资源 StarRocksCluster，建议使用 kubectl create -f xxx。如果环境中已安装自定义资源 StarRocksCluster，并且需要更新其配置，建议使用 kubectl replace -f xxx。
