This is an automated email from the ASF dual-hosted git repository.
morningman pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/doris-website.git
The following commit(s) were added to refs/heads/master by this push:
new f6f061044aa8 [docs](k8s) Explain compute-storage decoupled scaling in
dev and 4.x (#4632)
f6f061044aa8 is described below
commit f6f061044aa8aa4eb25122df99b5b51fd7315ed7
Author: Mingyu Chen (Rayner) <[email protected]>
AuthorDate: Fri Nov 13 08:05:06 2026 +0800
[docs](k8s) Explain compute-storage decoupled scaling in dev and 4.x (#4632)
## Problem and change
The Kubernetes compute-storage decoupled deployment guide lists
`computeGroups.replicas` but does not give users a complete scaling
procedure. Add a linked scaling section to the compute-group
configuration page in dev and 4.x, in English and Chinese. The requested
scope is dev and 4.x only.
The guide covers adding/removing BE nodes, adding/removing complete
compute groups, resource changes, FE scaling constraints, and completion
checks. It explains Operator-managed BE decommission, the default
non-decommission path and its image-dependent graceful flow, PVC cleanup
during scale-in, and the different removal path when a whole
compute-group entry is deleted.
Fixes #2370
## Implementation evidence
Checked Doris `branch-4.0`, `branch-4.1`, and master, and the released
Doris Operator 26.0.1 implementation rather than inferring behavior from
the replica field:
- [Operator's decommission
option](https://github.com/apache/doris-operator/blob/26.0.1/api/disaggregated/v1/types.go)
- [BE decommission and drop
ordering](https://github.com/apache/doris-operator/blob/26.0.1/pkg/controller/sub_controller/disaggregated_cluster/computegroups/prepare_modify.go)
- [Decommission completion
check](https://github.com/apache/doris-operator/blob/26.0.1/pkg/common/utils/resource/decommission.go)
- [Whole-group removal and unused PVC
cleanup](https://github.com/apache/doris-operator/blob/26.0.1/pkg/controller/sub_controller/disaggregated_cluster/computegroups/controller.go)
- [Image capability detection and graceful
scale-in](https://github.com/apache/doris-operator/blob/26.0.1/pkg/controller/sub_controller/disaggregated_cluster/computegroups/graceful_rollout.go)
- [FE replica/election
constraints](https://github.com/apache/doris-operator/blob/26.0.1/pkg/controller/sub_controller/disaggregated_cluster/disaggregated_fe/controller.go)
- [Doris 4.1 cloud BE removal and decommission
operations](https://github.com/apache/doris/blob/df8ed67a8e5dbdc91f1065b50dae23d834117800/fe/fe-core/src/main/java/org/apache/doris/cloud/system/CloudSystemInfoService.java#L918)
## Validation and self-review
- `git diff --check` passed.
- Compiled all eight changed Markdown files with the Docusaurus Markdown
processor; front matter and fenced YAML parse successfully, including
the explicit scaling anchor.
- Checked new relative links and the scaling anchor across all four
version/locale trees. The repository link linter reports 18 pre-existing
missing anchors in the touched pages, all outside the added scaling
instructions; no new internal-link errors were found.
- The i18n checker found both requested language/version pairs. It emits
informational reminders about 3.x, which is outside the requested scope.
- Existing paths, navigation entries, and heading anchors are preserved.
No site configuration or frontend code changes.
- No Kubernetes scaling test or full site build was run. The procedures
and cautions are based on the pinned implementation above; they do not
promise interruption-free scale-in.
Co-authored-by: morningman <[email protected]>
---
.../separating-storage-compute/config-cg.md | 125 ++++++++++++++++++++-
.../install-doris-cluster.md | 1 +
.../separating-storage-compute/config-cg.md | 125 ++++++++++++++++++++-
.../install-doris-cluster.md | 1 +
.../separating-storage-compute/config-cg.md | 125 ++++++++++++++++++++-
.../install-doris-cluster.md | 1 +
.../separating-storage-compute/config-cg.md | 125 ++++++++++++++++++++-
.../install-doris-cluster.md | 1 +
8 files changed, 500 insertions(+), 4 deletions(-)
diff --git
a/docs/install/deploy-on-kubernetes/separating-storage-compute/config-cg.md
b/docs/install/deploy-on-kubernetes/separating-storage-compute/config-cg.md
index ef043a5e7387..7802d7f147ac 100644
--- a/docs/install/deploy-on-kubernetes/separating-storage-compute/config-cg.md
+++ b/docs/install/deploy-on-kubernetes/separating-storage-compute/config-cg.md
@@ -2,7 +2,7 @@
{
"title": "Configuring Compute Groups",
"language": "en",
- "description": "A detailed guide to configuring Compute Groups, including
replica configuration, multi-compute-group configuration, resource
configuration, access mode configuration, startup parameter configuration, and
persistent storage configuration.",
+ "description": "Configure Doris compute groups on Kubernetes: BE replicas,
CPU and memory, service access, startup options, persistent storage, and
scaling operations.",
"keywords": ["Doris", "Storage-Compute Decoupling", "Kubernetes", "Compute
Group", "BE", "NodePort", "LoadBalancer", "Persistent Storage", "ConfigMap"]
}
---
@@ -14,6 +14,7 @@ A Compute Group is a collection of BE nodes that handle the
same task. This docu
- **Access control**: accessing BE services from inside or outside the cluster
through different methods
- **Startup customization**: customizing BE startup parameters through
ConfigMap
- **Data persistence**: persistent storage for cache, logs, and StreamLoad
staging data
+- **Scaling**: add or remove BE nodes and compute groups, with scale-in checks
## Scenario 1: Quickly Set Up a Single Compute Group
@@ -311,3 +312,125 @@ spec:
- uniqueId: cg1
logNotStore: true
```
+
+## Scenario 7: Scale Compute Capacity {#scaling-compute-groups}
+
+Scale a compute group by changing the `DorisDisaggregatedCluster` resource.
Its `replicas` field counts BE nodes, not copies of the data in object storage.
Increasing this value adds compute capacity; reducing it removes BE nodes and
their local cache.
+
+The procedures below follow [Doris Operator
26.0.1](https://github.com/apache/doris-operator/tree/26.0.1). Use the CRDs and
Operator image from the same release. Scale-in behavior also depends on the BE
image; do not assume that every image supports graceful shutdown.
+
+### 7.1 Prepare and Inspect the Cluster
+
+Before changing capacity:
+
+- Confirm that FE, MetaService, FoundationDB, and the current BE nodes are
healthy. The Operator must be able to connect to FE with the management
credentials configured in [Configure Authentication](config-cluster.md).
+- Check Kubernetes CPU, memory, and storage capacity, including whether new
PVCs can be bound. Keep enough ready BE nodes to handle the remaining workload.
+- For scale-in, reduce or redirect traffic first and allow running queries and
load jobs to finish. Check client retries and load-job status after the
operation.
+
+The following examples use namespace `doris`, cluster
`test-disaggregated-cluster`, and compute group `cg1`. Replace these names with
your own:
+
+```shell
+kubectl get ddc test-disaggregated-cluster -n doris -o yaml
+kubectl get pods,sts,pvc -n doris
+```
+
+Connect to the FE SQL endpoint as an administrator and record the current
compute groups and BE nodes:
+
+```sql
+SHOW COMPUTE GROUPS;
+SHOW BACKENDS;
+```
+
+Edit the complete manifest used to deploy the cluster, then apply it:
+
+```shell
+kubectl apply -n doris -f ddc-sample.yaml
+```
+
+The YAML fragments below show only the fields to change. Preserve the other
fields and all other entries in `spec.computeGroups`. Omitting an existing
group requests its removal. Change the Doris custom resource instead of
directly scaling its StatefulSet, so the Operator can coordinate Doris metadata
and Kubernetes resources.
+
+### 7.2 Scale Out an Existing Compute Group
+
+For example, change `cg1` from 2 BE nodes to 3 in the complete manifest:
+
+```yaml
+spec:
+ computeGroups:
+ - uniqueId: cg1
+ image: ${beImage}
+ replicas: 3
+```
+
+Retain the existing `uniqueId`, image, resource settings, ConfigMaps, and
persistent-volume configuration. Apply the manifest. The Operator increases the
StatefulSet replica count, and the new BE registers with the cluster during
startup.
+
+Verify that the group reaches 3 ready Pods and that `SHOW BACKENDS` lists the
new BE with `Alive = true`. New nodes start with a cold cache; adding a node
does not immediately give it the same cache as existing nodes.
+
+### 7.3 Scale In an Existing Compute Group
+
+The cluster-level Boolean `spec.enableDecommission` selects the BE removal
path. Its default is `false`:
+
+| Value | Behavior when reducing a compute group's `replicas` |
+| --- | --- |
+| `true` | Submit Doris BE decommission operations and keep the original
StatefulSet replica count while decommission is in progress. After the selected
nodes are decommissioned, remove them from Doris and reduce the StatefulSet. |
+| `false` | Remove the selected BEs from Doris without the decommission step.
Operator 26.0.1 first uses its graceful scale-in flow when the BE image
supports it; otherwise it falls back to the direct-drop path. |
+
+For example, to reduce `cg1` from 3 nodes to 2 through the decommission path,
update the complete manifest as follows and apply it:
+
+```yaml
+spec:
+ enableDecommission: true
+ computeGroups:
+ - uniqueId: cg1
+ image: ${beImage}
+ replicas: 2
+```
+
+The Operator selects nodes with Pod ordinals greater than or equal to the
target replica count. Do not manually delete those Pods while decommission is
running. Inspect progress with:
+
+```shell
+kubectl describe ddc test-disaggregated-cluster -n doris
+kubectl get sts,pods,pvc -n doris
+```
+
+In Doris, run `SHOW BACKENDS;`. The Operator's decommission check waits until
the selected BEs have `SystemDecommissioned = true` and `TabletNum = 0`, or
have already been removed. A group can remain in `Decommissioning` while this
is in progress. Completion requires both the target number of ready Pods and
the corresponding BE membership in Doris.
+
+:::caution Local storage during scale-in
+Operator 26.0.1 deletes PVCs belonging to removed Pod ordinals after the
StatefulSet is reduced. The underlying PV's reclaim policy determines what
happens to the storage. Persisting cache, logs, or Stream Load staging data
does not guarantee that those volumes survive scale-in. Finish dependent load
jobs and retain any logs you need before removing a BE. Scaling back out does
not guarantee restoration of its previous local data.
+:::
+
+### 7.4 Add or Remove an Entire Compute Group
+
+To add a group, append a new entry with a new `uniqueId` while retaining every
existing group. For example:
+
+```yaml
+spec:
+ computeGroups:
+ - uniqueId: cg1
+ image: ${beImage}
+ replicas: 2
+ - uniqueId: cg2
+ image: ${beImage}
+ replicas: 2
+```
+
+Apply the complete manifest and wait until `cg2` is ready and visible in `SHOW
COMPUTE GROUPS`. Configure user access and workload routing as described in
[Managing Compute
Groups](../../../compute-storage-decoupled/managing-compute-cluster.md) before
sending traffic to it. Adding a group does not automatically move existing
sessions to that group.
+
+To remove a group, first move its queries and loads to another available group
and update any user defaults or application settings that refer to it. Remove
only that group's entry from the complete manifest and apply it. The Operator
removes its BEs from Doris metadata, then removes its managed Service and
StatefulSet.
+
+:::caution Removing a group differs from reducing its replicas
+In Operator 26.0.1, removing an entire `computeGroups` entry uses the BE drop
path, even when `enableDecommission` is `true`. Do not use entry removal to
request gradual decommission. Check for leftover PVCs after deletion and handle
them according to your retention policy; do not assume the cleanup behavior is
the same as scale-in within an existing group.
+:::
+
+### 7.5 Resource Changes and Other Components
+
+| Change | Operation and constraint |
+| --- | --- |
+| Increase or decrease CPU/memory per BE | Change the group's `requests` and
`limits` as described in Scenario 3, then apply the complete manifest. This
changes the Pod template and can restart BEs. Check scheduling capacity before
applying it. |
+| Scale FE | Change `spec.feSpec.replicas`. The value must be at least
`electionNumber`; extra FE nodes are Observers. The Operator removes selected
Observers from Doris before reducing the StatefulSet. Do not change
`electionNumber` on an existing cluster. See [Configure FE](config-fe.md). |
+| Change MetaService, FoundationDB, or Storage Vault capacity | Manage these
independently of compute-group replicas. Preserve their metadata and storage.
BE scale-in is not a reason to delete their resources or object-storage data.
See [Configure MetaService](config-ms.md) and [Deploy
FoundationDB](install-fdb.md). |
+
+### 7.6 Verify and Troubleshoot
+
+After each change, check the compute group's phase in the custom resource, Pod
readiness, and `SHOW BACKENDS` together. Confirm the target node count, `Alive
= true` for retained nodes, removal of retired nodes, and successful queries
and loads through the intended compute group.
+
+If the operation stalls, inspect `kubectl describe ddc`, Pod Events, PVC
binding, and Operator logs. `Pending` Pods often require checking scheduling or
storage; `Decommissioning` requires checking Doris decommission progress;
`ScaleDownFailed` requires checking the Operator's SQL error and FE
connectivity or permissions. Resolve the reported cause before retrying or
forcing resource deletion. See [Status and
Troubleshooting](../doris-operator/status-and-troubleshooting.md).
diff --git
a/docs/install/deploy-on-kubernetes/separating-storage-compute/install-doris-cluster.md
b/docs/install/deploy-on-kubernetes/separating-storage-compute/install-doris-cluster.md
index 1d8096fd2830..19846e3aa259 100644
---
a/docs/install/deploy-on-kubernetes/separating-storage-compute/install-doris-cluster.md
+++
b/docs/install/deploy-on-kubernetes/separating-storage-compute/install-doris-cluster.md
@@ -346,3 +346,4 @@ After completing the 5 steps above, the cluster is ready
for use. In production
| Adjust FE resources, change the number of Followers, customize startup
configuration, configure access mode (NodePort / LoadBalancer), persistent
storage | [Configure FE](config-fe.md) | All fields under `spec.feSpec.*` |
| Single-group / multi-group Compute Groups, resource limits, access mode
configuration, persistence of cache and logs | [Configure Compute
Group](config-cg.md) | All fields under `spec.computeGroups[*]` |
| Set root / non-root admin user passwords, Secret credentials, mount Kerberos
authentication files | [Configure Authentication](config-cluster.md) |
Cluster-level credentials and Kerberos |
+| Scale BE nodes, add or remove compute groups, check scale-in and PVC cleanup
| [Scale Compute Capacity](config-cg.md#scaling-compute-groups) | Operating
steps, decommission behavior, and validation |
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/install/deploy-on-kubernetes/separating-storage-compute/config-cg.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/install/deploy-on-kubernetes/separating-storage-compute/config-cg.md
index cc78c65908cc..d67d2ba41b2b 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/install/deploy-on-kubernetes/separating-storage-compute/config-cg.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/install/deploy-on-kubernetes/separating-storage-compute/config-cg.md
@@ -2,7 +2,7 @@
{
"title": "配置计算组",
"language": "zh-CN",
- "description": "详细介绍计算组（Compute
Group）的配置方法，包括副本配置、多计算组配置、资源配置、访问模式配置、启动参数配置和持久化存储配置。",
+ "description": "介绍 Kubernetes 上 Doris 存算分离计算组的配置与扩缩容方法，包括 BE
节点数量、资源限制、访问模式、启动参数、持久化存储，以及缩容退役、PVC 清理和结果验证。",
"keywords": ["Doris", "存算分离", "Kubernetes", "计算组", "Compute Group", "BE",
"NodePort", "LoadBalancer", "持久化存储", "ConfigMap"]
}
---
@@ -14,6 +14,7 @@
- **访问控制**：集群内、外通过不同方式访问 BE 服务
- **启动定制**：通过 ConfigMap 自定义 BE 启动参数
- **数据持久化**：缓存、日志、StreamLoad 暂存数据的持久化存储
+- **扩缩容**：增减 BE 节点和计算组，并检查缩容结果
## 场景 1：快速搭建单个计算组
@@ -311,3 +312,125 @@ spec:
- uniqueId: cg1
logNotStore: true
```
+
+## 场景 7：调整计算容量 {#scaling-compute-groups}
+
+通过修改 `DorisDisaggregatedCluster` 资源扩缩容计算组。`replicas` 表示 BE
节点数，不是对象存储中数据的副本数。增大该值会增加计算容量，减小该值会移除 BE 节点及其本地缓存。
+
+以下流程以 [Doris Operator
26.0.1](https://github.com/apache/doris-operator/tree/26.0.1) 为依据。请使用同一发行版本的
CRD 和 Operator 镜像。缩容行为也取决于 BE 镜像，不能假定所有镜像都支持优雅退出。
+
+### 7.1 准备并检查集群
+
+调整容量前：
+
+- 确认 FE、MetaService、FoundationDB 和现有 BE 节点健康。Operator
必须能够使用[配置认证](config-cluster.md)中的管理凭证连接 FE。
+- 检查 Kubernetes 的 CPU、内存和存储容量，包括新 PVC 能否绑定。为剩余业务保留足够的就绪 BE 节点。
+- 缩容前先降低或迁移流量，等待正在执行的查询和导入任务完成。操作后检查客户端重试情况和导入任务状态。
+
+以下示例使用命名空间 `doris`、集群 `test-disaggregated-cluster` 和计算组 `cg1`，请替换为实际名称：
+
+```shell
+kubectl get ddc test-disaggregated-cluster -n doris -o yaml
+kubectl get pods,sts,pvc -n doris
+```
+
+以管理员身份连接 FE 的 SQL 端口，记录现有计算组和 BE 节点：
+
+```sql
+SHOW COMPUTE GROUPS;
+SHOW BACKENDS;
+```
+
+修改部署集群时使用的完整清单，然后执行：
+
+```shell
+kubectl apply -n doris -f ddc-sample.yaml
+```
+
+以下 YAML 片段仅展示需要修改的字段。请保留其他字段和 `spec.computeGroups`
中的所有其他计算组。省略已有计算组会请求删除该组。请修改 Doris 自定义资源，由 Operator 协调 Doris 元数据和 Kubernetes
资源，不要直接缩放其 StatefulSet。
+
+### 7.2 扩容已有计算组
+
+例如，将完整清单中 `cg1` 的 BE 节点数从 2 调整为 3：
+
+```yaml
+spec:
+ computeGroups:
+ - uniqueId: cg1
+ image: ${beImage}
+ replicas: 3
+```
+
+保留原有 `uniqueId`、镜像、资源配置、ConfigMap 和持久卷配置。应用清单后，Operator 增加 StatefulSet 副本数，新
BE 在启动时注册到集群。
+
+确认该组有 3 个就绪 Pod，且 `SHOW BACKENDS` 中新增 BE 的 `Alive =
true`。新节点需要逐步建立缓存，增加节点不会立即获得与已有节点相同的缓存。
+
+### 7.3 缩容已有计算组
+
+集群级布尔字段 `spec.enableDecommission` 决定 BE 的移除流程，默认值为 `false`：
+
+| 取值 | 减小计算组 `replicas` 时的行为 |
+| --- | --- |
+| `true` | 先提交 Doris BE 退役操作，退役期间保持 StatefulSet 原有副本数。待选中节点退役完成后，从 Doris
移除节点并缩减 StatefulSet。 |
+| `false` | 不执行退役步骤，直接从 Doris 移除选中的 BE。Operator 26.0.1 在 BE
镜像支持时会先使用优雅缩容流程，否则回退到直接移除流程。 |
+
+例如，通过退役流程将 `cg1` 从 3 个节点缩减为 2 个，在完整清单中进行如下修改并应用：
+
+```yaml
+spec:
+ enableDecommission: true
+ computeGroups:
+ - uniqueId: cg1
+ image: ${beImage}
+ replicas: 2
+```
+
+Operator 选择 Pod 序号大于等于目标副本数的节点。退役过程中不要手动删除这些 Pod。通过以下命令查看进度：
+
+```shell
+kubectl describe ddc test-disaggregated-cluster -n doris
+kubectl get sts,pods,pvc -n doris
+```
+
+在 Doris 中执行 `SHOW BACKENDS;`。Operator 的退役检查会等待选中 BE 的 `SystemDecommissioned =
true` 且 `TabletNum = 0`，或节点已经被移除。期间计算组可能保持 `Decommissioning` 状态。只有就绪 Pod 数量和
Doris 中的 BE 成员均符合目标，才表示缩容完成。
+
+:::caution 缩容时的本地存储
+Operator 26.0.1 在 StatefulSet 缩容后会删除被移除 Pod 序号对应的 PVC。底层 PV
的回收策略决定存储的后续处理。将缓存、日志或 Stream Load 暂存数据持久化，并不保证这些卷会在缩容后保留。移除 BE
前，请完成依赖该节点的导入任务，并保存所需日志。再次扩容不保证恢复原有本地数据。
+:::
+
+### 7.4 新增或移除整个计算组
+
+新增计算组时，保留所有已有组，追加一个具有新 `uniqueId` 的条目。例如：
+
+```yaml
+spec:
+ computeGroups:
+ - uniqueId: cg1
+ image: ${beImage}
+ replicas: 2
+ - uniqueId: cg2
+ image: ${beImage}
+ replicas: 2
+```
+
+应用完整清单，等待 `cg2` 就绪并出现在 `SHOW COMPUTE GROUPS`
中。向新组发送流量前，按照[管理计算组](../../../compute-storage-decoupled/managing-compute-cluster.md)配置用户权限和业务路由。新增计算组不会自动将已有会话迁移到该组。
+
+移除计算组前，先将其查询和导入迁移到其他可用计算组，并更新引用该组的用户默认值或应用配置。仅从完整清单中删除该组条目并应用。Operator 先从
Doris 元数据中移除该组 BE，再移除其管理的 Service 和 StatefulSet。
+
+:::caution 移除整个组与减少组内节点不同
+Operator 26.0.1 在移除整个 `computeGroups` 条目时使用 BE 直接移除流程，即使 `enableDecommission`
为 `true` 也是如此。不要通过删除条目来请求逐步退役。删除后检查是否有残留 PVC，并按保留策略处理，不能假定其清理行为与已有组内的缩容相同。
+:::
+
+### 7.5 调整资源和其他组件
+
+| 调整目标 | 操作与约束 |
+| --- | --- |
+| 增减单个 BE 的 CPU/内存 | 按场景 3 修改该组的 `requests` 和 `limits`，然后应用完整清单。这会改变 Pod
模板，可能导致 BE 重启。应用前确认调度容量。 |
+| FE 扩缩容 | 修改 `spec.feSpec.replicas`，取值必须大于等于 `electionNumber`，超出的 FE 为
Observer。Operator 在缩减 StatefulSet 前，先从 Doris 移除选中的 Observer。不要修改已有集群的
`electionNumber`。参见[配置 FE](config-fe.md)。 |
+| 调整 MetaService、FoundationDB 或 Storage Vault 容量 | 独立于计算组副本数管理，保留其元数据和存储。BE
缩容不需要删除这些组件的资源或对象存储中的数据。参见[配置 MetaService](config-ms.md)和[部署
FoundationDB](install-fdb.md)。 |
+
+### 7.6 验证与排查
+
+每次变更后，结合自定义资源中的计算组阶段、Pod 就绪状态和 `SHOW BACKENDS` 验证结果。确认节点数量符合目标、保留节点的 `Alive =
true`、退役节点已被移除，并通过预期计算组执行查询和导入验证。
+
+如果操作停滞，检查 `kubectl describe ddc`、Pod Events、PVC 绑定状态和 Operator 日志。Pod 为
`Pending` 时通常需要检查调度或存储；`Decommissioning` 需要检查 Doris 退役进度；`ScaleDownFailed` 需要检查
Operator 记录的 SQL 错误以及 FE
连通性和权限。解决报告的原因后再重试，不要直接强制删除资源。参见[状态与故障排查](../doris-operator/status-and-troubleshooting.md)。
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/install/deploy-on-kubernetes/separating-storage-compute/install-doris-cluster.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/install/deploy-on-kubernetes/separating-storage-compute/install-doris-cluster.md
index 24b7ec0577fb..0ed0d2c75339 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/install/deploy-on-kubernetes/separating-storage-compute/install-doris-cluster.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/install/deploy-on-kubernetes/separating-storage-compute/install-doris-cluster.md
@@ -346,3 +346,4 @@ SELECT * FROM hello;
| 调 FE 资源、改 Follower 数量、自定义启动配置、配置访问模式（NodePort / LoadBalancer）、持久化存储 | [配置
FE](config-fe.md) | `spec.feSpec.*` 全量字段 |
| 单组/多组计算组、限制资源、配置访问模式、缓存与日志的持久化 | [配置计算组](config-cg.md) |
`spec.computeGroups[*]` 全量字段 |
| 设置 root / 非 root 管理用户密码、Secret 凭证、挂载 Kerberos 认证文件 |
[配置认证](config-cluster.md) | 集群级凭证与 Kerberos |
+| BE 扩缩容、新增或移除计算组、检查缩容和 PVC 清理 | [调整计算容量](config-cg.md#scaling-compute-groups)
| 操作步骤、退役行为与结果验证 |
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/install/deploy-on-kubernetes/separating-storage-compute/config-cg.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/install/deploy-on-kubernetes/separating-storage-compute/config-cg.md
index cc78c65908cc..d67d2ba41b2b 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/install/deploy-on-kubernetes/separating-storage-compute/config-cg.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/install/deploy-on-kubernetes/separating-storage-compute/config-cg.md
@@ -2,7 +2,7 @@
{
"title": "配置计算组",
"language": "zh-CN",
- "description": "详细介绍计算组（Compute
Group）的配置方法，包括副本配置、多计算组配置、资源配置、访问模式配置、启动参数配置和持久化存储配置。",
+ "description": "介绍 Kubernetes 上 Doris 存算分离计算组的配置与扩缩容方法，包括 BE
节点数量、资源限制、访问模式、启动参数、持久化存储，以及缩容退役、PVC 清理和结果验证。",
"keywords": ["Doris", "存算分离", "Kubernetes", "计算组", "Compute Group", "BE",
"NodePort", "LoadBalancer", "持久化存储", "ConfigMap"]
}
---
@@ -14,6 +14,7 @@
- **访问控制**：集群内、外通过不同方式访问 BE 服务
- **启动定制**：通过 ConfigMap 自定义 BE 启动参数
- **数据持久化**：缓存、日志、StreamLoad 暂存数据的持久化存储
+- **扩缩容**：增减 BE 节点和计算组，并检查缩容结果
## 场景 1：快速搭建单个计算组
@@ -311,3 +312,125 @@ spec:
- uniqueId: cg1
logNotStore: true
```
+
+## 场景 7：调整计算容量 {#scaling-compute-groups}
+
+通过修改 `DorisDisaggregatedCluster` 资源扩缩容计算组。`replicas` 表示 BE
节点数，不是对象存储中数据的副本数。增大该值会增加计算容量，减小该值会移除 BE 节点及其本地缓存。
+
+以下流程以 [Doris Operator
26.0.1](https://github.com/apache/doris-operator/tree/26.0.1) 为依据。请使用同一发行版本的
CRD 和 Operator 镜像。缩容行为也取决于 BE 镜像，不能假定所有镜像都支持优雅退出。
+
+### 7.1 准备并检查集群
+
+调整容量前：
+
+- 确认 FE、MetaService、FoundationDB 和现有 BE 节点健康。Operator
必须能够使用[配置认证](config-cluster.md)中的管理凭证连接 FE。
+- 检查 Kubernetes 的 CPU、内存和存储容量，包括新 PVC 能否绑定。为剩余业务保留足够的就绪 BE 节点。
+- 缩容前先降低或迁移流量，等待正在执行的查询和导入任务完成。操作后检查客户端重试情况和导入任务状态。
+
+以下示例使用命名空间 `doris`、集群 `test-disaggregated-cluster` 和计算组 `cg1`，请替换为实际名称：
+
+```shell
+kubectl get ddc test-disaggregated-cluster -n doris -o yaml
+kubectl get pods,sts,pvc -n doris
+```
+
+以管理员身份连接 FE 的 SQL 端口，记录现有计算组和 BE 节点：
+
+```sql
+SHOW COMPUTE GROUPS;
+SHOW BACKENDS;
+```
+
+修改部署集群时使用的完整清单，然后执行：
+
+```shell
+kubectl apply -n doris -f ddc-sample.yaml
+```
+
+以下 YAML 片段仅展示需要修改的字段。请保留其他字段和 `spec.computeGroups`
中的所有其他计算组。省略已有计算组会请求删除该组。请修改 Doris 自定义资源，由 Operator 协调 Doris 元数据和 Kubernetes
资源，不要直接缩放其 StatefulSet。
+
+### 7.2 扩容已有计算组
+
+例如，将完整清单中 `cg1` 的 BE 节点数从 2 调整为 3：
+
+```yaml
+spec:
+ computeGroups:
+ - uniqueId: cg1
+ image: ${beImage}
+ replicas: 3
+```
+
+保留原有 `uniqueId`、镜像、资源配置、ConfigMap 和持久卷配置。应用清单后，Operator 增加 StatefulSet 副本数，新
BE 在启动时注册到集群。
+
+确认该组有 3 个就绪 Pod，且 `SHOW BACKENDS` 中新增 BE 的 `Alive =
true`。新节点需要逐步建立缓存，增加节点不会立即获得与已有节点相同的缓存。
+
+### 7.3 缩容已有计算组
+
+集群级布尔字段 `spec.enableDecommission` 决定 BE 的移除流程，默认值为 `false`：
+
+| 取值 | 减小计算组 `replicas` 时的行为 |
+| --- | --- |
+| `true` | 先提交 Doris BE 退役操作，退役期间保持 StatefulSet 原有副本数。待选中节点退役完成后，从 Doris
移除节点并缩减 StatefulSet。 |
+| `false` | 不执行退役步骤，直接从 Doris 移除选中的 BE。Operator 26.0.1 在 BE
镜像支持时会先使用优雅缩容流程，否则回退到直接移除流程。 |
+
+例如，通过退役流程将 `cg1` 从 3 个节点缩减为 2 个，在完整清单中进行如下修改并应用：
+
+```yaml
+spec:
+ enableDecommission: true
+ computeGroups:
+ - uniqueId: cg1
+ image: ${beImage}
+ replicas: 2
+```
+
+Operator 选择 Pod 序号大于等于目标副本数的节点。退役过程中不要手动删除这些 Pod。通过以下命令查看进度：
+
+```shell
+kubectl describe ddc test-disaggregated-cluster -n doris
+kubectl get sts,pods,pvc -n doris
+```
+
+在 Doris 中执行 `SHOW BACKENDS;`。Operator 的退役检查会等待选中 BE 的 `SystemDecommissioned =
true` 且 `TabletNum = 0`，或节点已经被移除。期间计算组可能保持 `Decommissioning` 状态。只有就绪 Pod 数量和
Doris 中的 BE 成员均符合目标，才表示缩容完成。
+
+:::caution 缩容时的本地存储
+Operator 26.0.1 在 StatefulSet 缩容后会删除被移除 Pod 序号对应的 PVC。底层 PV
的回收策略决定存储的后续处理。将缓存、日志或 Stream Load 暂存数据持久化，并不保证这些卷会在缩容后保留。移除 BE
前，请完成依赖该节点的导入任务，并保存所需日志。再次扩容不保证恢复原有本地数据。
+:::
+
+### 7.4 新增或移除整个计算组
+
+新增计算组时，保留所有已有组，追加一个具有新 `uniqueId` 的条目。例如：
+
+```yaml
+spec:
+ computeGroups:
+ - uniqueId: cg1
+ image: ${beImage}
+ replicas: 2
+ - uniqueId: cg2
+ image: ${beImage}
+ replicas: 2
+```
+
+应用完整清单，等待 `cg2` 就绪并出现在 `SHOW COMPUTE GROUPS`
中。向新组发送流量前，按照[管理计算组](../../../compute-storage-decoupled/managing-compute-cluster.md)配置用户权限和业务路由。新增计算组不会自动将已有会话迁移到该组。
+
+移除计算组前，先将其查询和导入迁移到其他可用计算组，并更新引用该组的用户默认值或应用配置。仅从完整清单中删除该组条目并应用。Operator 先从
Doris 元数据中移除该组 BE，再移除其管理的 Service 和 StatefulSet。
+
+:::caution 移除整个组与减少组内节点不同
+Operator 26.0.1 在移除整个 `computeGroups` 条目时使用 BE 直接移除流程，即使 `enableDecommission`
为 `true` 也是如此。不要通过删除条目来请求逐步退役。删除后检查是否有残留 PVC，并按保留策略处理，不能假定其清理行为与已有组内的缩容相同。
+:::
+
+### 7.5 调整资源和其他组件
+
+| 调整目标 | 操作与约束 |
+| --- | --- |
+| 增减单个 BE 的 CPU/内存 | 按场景 3 修改该组的 `requests` 和 `limits`，然后应用完整清单。这会改变 Pod
模板，可能导致 BE 重启。应用前确认调度容量。 |
+| FE 扩缩容 | 修改 `spec.feSpec.replicas`，取值必须大于等于 `electionNumber`，超出的 FE 为
Observer。Operator 在缩减 StatefulSet 前，先从 Doris 移除选中的 Observer。不要修改已有集群的
`electionNumber`。参见[配置 FE](config-fe.md)。 |
+| 调整 MetaService、FoundationDB 或 Storage Vault 容量 | 独立于计算组副本数管理，保留其元数据和存储。BE
缩容不需要删除这些组件的资源或对象存储中的数据。参见[配置 MetaService](config-ms.md)和[部署
FoundationDB](install-fdb.md)。 |
+
+### 7.6 验证与排查
+
+每次变更后，结合自定义资源中的计算组阶段、Pod 就绪状态和 `SHOW BACKENDS` 验证结果。确认节点数量符合目标、保留节点的 `Alive =
true`、退役节点已被移除，并通过预期计算组执行查询和导入验证。
+
+如果操作停滞，检查 `kubectl describe ddc`、Pod Events、PVC 绑定状态和 Operator 日志。Pod 为
`Pending` 时通常需要检查调度或存储；`Decommissioning` 需要检查 Doris 退役进度；`ScaleDownFailed` 需要检查
Operator 记录的 SQL 错误以及 FE
连通性和权限。解决报告的原因后再重试，不要直接强制删除资源。参见[状态与故障排查](../doris-operator/status-and-troubleshooting.md)。
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/install/deploy-on-kubernetes/separating-storage-compute/install-doris-cluster.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/install/deploy-on-kubernetes/separating-storage-compute/install-doris-cluster.md
index 24b7ec0577fb..0ed0d2c75339 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/install/deploy-on-kubernetes/separating-storage-compute/install-doris-cluster.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/install/deploy-on-kubernetes/separating-storage-compute/install-doris-cluster.md
@@ -346,3 +346,4 @@ SELECT * FROM hello;
| 调 FE 资源、改 Follower 数量、自定义启动配置、配置访问模式（NodePort / LoadBalancer）、持久化存储 | [配置
FE](config-fe.md) | `spec.feSpec.*` 全量字段 |
| 单组/多组计算组、限制资源、配置访问模式、缓存与日志的持久化 | [配置计算组](config-cg.md) |
`spec.computeGroups[*]` 全量字段 |
| 设置 root / 非 root 管理用户密码、Secret 凭证、挂载 Kerberos 认证文件 |
[配置认证](config-cluster.md) | 集群级凭证与 Kerberos |
+| BE 扩缩容、新增或移除计算组、检查缩容和 PVC 清理 | [调整计算容量](config-cg.md#scaling-compute-groups)
| 操作步骤、退役行为与结果验证 |
diff --git
a/versioned_docs/version-4.x/install/deploy-on-kubernetes/separating-storage-compute/config-cg.md
b/versioned_docs/version-4.x/install/deploy-on-kubernetes/separating-storage-compute/config-cg.md
index ef043a5e7387..7802d7f147ac 100644
---
a/versioned_docs/version-4.x/install/deploy-on-kubernetes/separating-storage-compute/config-cg.md
+++
b/versioned_docs/version-4.x/install/deploy-on-kubernetes/separating-storage-compute/config-cg.md
@@ -2,7 +2,7 @@
{
"title": "Configuring Compute Groups",
"language": "en",
- "description": "A detailed guide to configuring Compute Groups, including
replica configuration, multi-compute-group configuration, resource
configuration, access mode configuration, startup parameter configuration, and
persistent storage configuration.",
+ "description": "Configure Doris compute groups on Kubernetes: BE replicas,
CPU and memory, service access, startup options, persistent storage, and
scaling operations.",
"keywords": ["Doris", "Storage-Compute Decoupling", "Kubernetes", "Compute
Group", "BE", "NodePort", "LoadBalancer", "Persistent Storage", "ConfigMap"]
}
---
@@ -14,6 +14,7 @@ A Compute Group is a collection of BE nodes that handle the
same task. This docu
- **Access control**: accessing BE services from inside or outside the cluster
through different methods
- **Startup customization**: customizing BE startup parameters through
ConfigMap
- **Data persistence**: persistent storage for cache, logs, and StreamLoad
staging data
+- **Scaling**: add or remove BE nodes and compute groups, with scale-in checks
## Scenario 1: Quickly Set Up a Single Compute Group
@@ -311,3 +312,125 @@ spec:
- uniqueId: cg1
logNotStore: true
```
+
+## Scenario 7: Scale Compute Capacity {#scaling-compute-groups}
+
+Scale a compute group by changing the `DorisDisaggregatedCluster` resource.
Its `replicas` field counts BE nodes, not copies of the data in object storage.
Increasing this value adds compute capacity; reducing it removes BE nodes and
their local cache.
+
+The procedures below follow [Doris Operator
26.0.1](https://github.com/apache/doris-operator/tree/26.0.1). Use the CRDs and
Operator image from the same release. Scale-in behavior also depends on the BE
image; do not assume that every image supports graceful shutdown.
+
+### 7.1 Prepare and Inspect the Cluster
+
+Before changing capacity:
+
+- Confirm that FE, MetaService, FoundationDB, and the current BE nodes are
healthy. The Operator must be able to connect to FE with the management
credentials configured in [Configure Authentication](config-cluster.md).
+- Check Kubernetes CPU, memory, and storage capacity, including whether new
PVCs can be bound. Keep enough ready BE nodes to handle the remaining workload.
+- For scale-in, reduce or redirect traffic first and allow running queries and
load jobs to finish. Check client retries and load-job status after the
operation.
+
+The following examples use namespace `doris`, cluster
`test-disaggregated-cluster`, and compute group `cg1`. Replace these names with
your own:
+
+```shell
+kubectl get ddc test-disaggregated-cluster -n doris -o yaml
+kubectl get pods,sts,pvc -n doris
+```
+
+Connect to the FE SQL endpoint as an administrator and record the current
compute groups and BE nodes:
+
+```sql
+SHOW COMPUTE GROUPS;
+SHOW BACKENDS;
+```
+
+Edit the complete manifest used to deploy the cluster, then apply it:
+
+```shell
+kubectl apply -n doris -f ddc-sample.yaml
+```
+
+The YAML fragments below show only the fields to change. Preserve the other
fields and all other entries in `spec.computeGroups`. Omitting an existing
group requests its removal. Change the Doris custom resource instead of
directly scaling its StatefulSet, so the Operator can coordinate Doris metadata
and Kubernetes resources.
+
+### 7.2 Scale Out an Existing Compute Group
+
+For example, change `cg1` from 2 BE nodes to 3 in the complete manifest:
+
+```yaml
+spec:
+ computeGroups:
+ - uniqueId: cg1
+ image: ${beImage}
+ replicas: 3
+```
+
+Retain the existing `uniqueId`, image, resource settings, ConfigMaps, and
persistent-volume configuration. Apply the manifest. The Operator increases the
StatefulSet replica count, and the new BE registers with the cluster during
startup.
+
+Verify that the group reaches 3 ready Pods and that `SHOW BACKENDS` lists the
new BE with `Alive = true`. New nodes start with a cold cache; adding a node
does not immediately give it the same cache as existing nodes.
+
+### 7.3 Scale In an Existing Compute Group
+
+The cluster-level Boolean `spec.enableDecommission` selects the BE removal
path. Its default is `false`:
+
+| Value | Behavior when reducing a compute group's `replicas` |
+| --- | --- |
+| `true` | Submit Doris BE decommission operations and keep the original
StatefulSet replica count while decommission is in progress. After the selected
nodes are decommissioned, remove them from Doris and reduce the StatefulSet. |
+| `false` | Remove the selected BEs from Doris without the decommission step.
Operator 26.0.1 first uses its graceful scale-in flow when the BE image
supports it; otherwise it falls back to the direct-drop path. |
+
+For example, to reduce `cg1` from 3 nodes to 2 through the decommission path,
update the complete manifest as follows and apply it:
+
+```yaml
+spec:
+ enableDecommission: true
+ computeGroups:
+ - uniqueId: cg1
+ image: ${beImage}
+ replicas: 2
+```
+
+The Operator selects nodes with Pod ordinals greater than or equal to the
target replica count. Do not manually delete those Pods while decommission is
running. Inspect progress with:
+
+```shell
+kubectl describe ddc test-disaggregated-cluster -n doris
+kubectl get sts,pods,pvc -n doris
+```
+
+In Doris, run `SHOW BACKENDS;`. The Operator's decommission check waits until
the selected BEs have `SystemDecommissioned = true` and `TabletNum = 0`, or
have already been removed. A group can remain in `Decommissioning` while this
is in progress. Completion requires both the target number of ready Pods and
the corresponding BE membership in Doris.
+
+:::caution Local storage during scale-in
+Operator 26.0.1 deletes PVCs belonging to removed Pod ordinals after the
StatefulSet is reduced. The underlying PV's reclaim policy determines what
happens to the storage. Persisting cache, logs, or Stream Load staging data
does not guarantee that those volumes survive scale-in. Finish dependent load
jobs and retain any logs you need before removing a BE. Scaling back out does
not guarantee restoration of its previous local data.
+:::
+
+### 7.4 Add or Remove an Entire Compute Group
+
+To add a group, append a new entry with a new `uniqueId` while retaining every
existing group. For example:
+
+```yaml
+spec:
+ computeGroups:
+ - uniqueId: cg1
+ image: ${beImage}
+ replicas: 2
+ - uniqueId: cg2
+ image: ${beImage}
+ replicas: 2
+```
+
+Apply the complete manifest and wait until `cg2` is ready and visible in `SHOW
COMPUTE GROUPS`. Configure user access and workload routing as described in
[Managing Compute
Groups](../../../compute-storage-decoupled/managing-compute-cluster.md) before
sending traffic to it. Adding a group does not automatically move existing
sessions to that group.
+
+To remove a group, first move its queries and loads to another available group
and update any user defaults or application settings that refer to it. Remove
only that group's entry from the complete manifest and apply it. The Operator
removes its BEs from Doris metadata, then removes its managed Service and
StatefulSet.
+
+:::caution Removing a group differs from reducing its replicas
+In Operator 26.0.1, removing an entire `computeGroups` entry uses the BE drop
path, even when `enableDecommission` is `true`. Do not use entry removal to
request gradual decommission. Check for leftover PVCs after deletion and handle
them according to your retention policy; do not assume the cleanup behavior is
the same as scale-in within an existing group.
+:::
+
+### 7.5 Resource Changes and Other Components
+
+| Change | Operation and constraint |
+| --- | --- |
+| Increase or decrease CPU/memory per BE | Change the group's `requests` and
`limits` as described in Scenario 3, then apply the complete manifest. This
changes the Pod template and can restart BEs. Check scheduling capacity before
applying it. |
+| Scale FE | Change `spec.feSpec.replicas`. The value must be at least
`electionNumber`; extra FE nodes are Observers. The Operator removes selected
Observers from Doris before reducing the StatefulSet. Do not change
`electionNumber` on an existing cluster. See [Configure FE](config-fe.md). |
+| Change MetaService, FoundationDB, or Storage Vault capacity | Manage these
independently of compute-group replicas. Preserve their metadata and storage.
BE scale-in is not a reason to delete their resources or object-storage data.
See [Configure MetaService](config-ms.md) and [Deploy
FoundationDB](install-fdb.md). |
+
+### 7.6 Verify and Troubleshoot
+
+After each change, check the compute group's phase in the custom resource, Pod
readiness, and `SHOW BACKENDS` together. Confirm the target node count, `Alive
= true` for retained nodes, removal of retired nodes, and successful queries
and loads through the intended compute group.
+
+If the operation stalls, inspect `kubectl describe ddc`, Pod Events, PVC
binding, and Operator logs. `Pending` Pods often require checking scheduling or
storage; `Decommissioning` requires checking Doris decommission progress;
`ScaleDownFailed` requires checking the Operator's SQL error and FE
connectivity or permissions. Resolve the reported cause before retrying or
forcing resource deletion. See [Status and
Troubleshooting](../doris-operator/status-and-troubleshooting.md).
diff --git
a/versioned_docs/version-4.x/install/deploy-on-kubernetes/separating-storage-compute/install-doris-cluster.md
b/versioned_docs/version-4.x/install/deploy-on-kubernetes/separating-storage-compute/install-doris-cluster.md
index 1d8096fd2830..19846e3aa259 100644
---
a/versioned_docs/version-4.x/install/deploy-on-kubernetes/separating-storage-compute/install-doris-cluster.md
+++
b/versioned_docs/version-4.x/install/deploy-on-kubernetes/separating-storage-compute/install-doris-cluster.md
@@ -346,3 +346,4 @@ After completing the 5 steps above, the cluster is ready
for use. In production
| Adjust FE resources, change the number of Followers, customize startup
configuration, configure access mode (NodePort / LoadBalancer), persistent
storage | [Configure FE](config-fe.md) | All fields under `spec.feSpec.*` |
| Single-group / multi-group Compute Groups, resource limits, access mode
configuration, persistence of cache and logs | [Configure Compute
Group](config-cg.md) | All fields under `spec.computeGroups[*]` |
| Set root / non-root admin user passwords, Secret credentials, mount Kerberos
authentication files | [Configure Authentication](config-cluster.md) |
Cluster-level credentials and Kerberos |
+| Scale BE nodes, add or remove compute groups, check scale-in and PVC cleanup
| [Scale Compute Capacity](config-cg.md#scaling-compute-groups) | Operating
steps, decommission behavior, and validation |
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
