docs: list the fields CacheRuntime can update in place, and stop enumerating the rest

The spec update doc listed `replicas` under "Unsupported Update Fields" and told
readers a redeploy was required. It is in fact synced on every reconcile:
syncRuntimeSpec passes it into ComponentSpec for Master and Worker, and
SyncComponentSpec applies it through updateReplicas before image and resources.

Give `replicas` its own subsection in section 3, alongside runtimeVersion and
resources, and record the two things worth knowing before scaling: cache on a
removed Worker is discarded rather than migrated, and scaling writes no
RuntimeCondition and emits no Event, so the controller log is the only place to
observe it.

Section 4 used to enumerate the unsupported fields. Keeping that list correct
meant remembering, every time a field became syncable, to delete a line from a
section unrelated to the change, with nothing in the code or CI to prompt for
it — which is how the `replicas` entry survived. It was also labelled
"including but not limited to", so it could not be authoritative anyway.
Section 4 now refers to section 3 instead of repeating it, leaving one place
where a supported field is recorded.

Also drop the TODO above the syncRuntimeSpec call asking for the replica
scaling that the call already does.

Signed-off-by: btxu-db <btxu-db@outlook.com>

Author: btxu-db

docs/en/samples/cacheruntime/cacheruntime_spec_update.md

@@ -4,9 +4,10 @@
 
 This document describes which `spec` fields of the CacheRuntime's Master and Worker components (backed by **AdvancedStatefulSet**) can be updated in-place.
 
-The current version supports in-place updates for only the following two fields:
+The current version supports in-place updates for the following three fields:
 - **Container image** (`runtimeVersion`)
 - **Resource limits** (`resources`)
+- **Replica count** (`replicas`)
 
 Modifications to other fields **will not be propagated to the AdvancedStatefulSet** and require redeployment to take effect.
 
@@ -16,12 +17,12 @@ Modifications to other fields **will not be propagated to the AdvancedStatefulSe
 
 | Component | Workload Type | Field Update Support |
 |-----------|---------------|---------------------|
-| **Master** | AdvancedStatefulSet | ✅ Supports `runtimeVersion` and `resources` |
-| **Worker** | AdvancedStatefulSet | ✅ Supports `runtimeVersion` and `resources` |
+| **Master** | AdvancedStatefulSet | ✅ Supports `runtimeVersion`, `resources` and `replicas` |
+| **Worker** | AdvancedStatefulSet | ✅ Supports `runtimeVersion`, `resources` and `replicas` |
 | **Client** | DaemonSet | ❌ Not supported (any changes require redeployment) |
 
 **Notes**:
-- Modifying `runtimeVersion` and `resources` on Master and Worker components automatically propagates to the underlying AdvancedStatefulSet.
+- Modifying `runtimeVersion`, `resources` and `replicas` on Master and Worker components automatically propagates to the underlying AdvancedStatefulSet.
 - The Client component uses a DaemonSet and does not support dynamic updates.
 
 ---
@@ -104,23 +105,40 @@ spec:
   ```
   See [Kubernetes Issue #127356](https://github.com/kubernetes/kubernetes/issues/127356).
 
-## 4. Unsupported Update Fields
+---
+
+### 3.3 Replica Count (`replicas`)
+
+**Field path**: `spec.{master,worker}.replicas`
+
+**Example**:
+```yaml
+spec:
+  worker:
+    replicas: 3
+```
+
+```bash
+kubectl patch cacheruntime my-cache --type='merge' -p '{"spec":{"worker":{"replicas":3}}}'
+```
 
-Aside from `runtimeVersion` and `resources`, **modifying any other fields in the CacheRuntime spec will not propagate to the AdvancedStatefulSet**, including but not limited to:
+The new value is synced to the AdvancedStatefulSet's `spec.replicas`, which then performs the scaling.
+
+**Limitations**:
+- ⚠️ **Scaling in discards cached data**: the Worker Pods removed are deleted outright, and the data they had cached is not migrated to the remaining Workers — it has to be loaded from the underlying storage again. Scaling out leaves the existing cache untouched.
+- ⚠️ Scaling writes no RuntimeCondition and emits no Kubernetes Event; it can only be observed from the controller logs:
+  ```bash
+  kubectl -n fluid-system logs deploy/cacheruntime-controller | grep "replicas changed"
+  ```
+- ⚠️ If the replica count exceeds the number of schedulable nodes, the surplus Worker Pods stay `Pending`.
+
+## 4. Unsupported Update Fields
 
-- `env`: Environment variables
-- `podMetadata`: Pod metadata (labels/annotations)
-- `args`/`command`: Container startup arguments
-- `ports`: Container ports
-- `volumeMounts`/`volumes`: Storage configuration
-- `nodeSelector`/`tolerations`/`affinity`: Scheduling configuration
-- `securityContext`: Security context
-- `replicas`: Replica count
-- `disabled`: Component enabled/disabled status
+**Any field not listed in section 3 cannot be updated in place**; changes to it are not propagated to the AdvancedStatefulSet.
 
 **Notes**:
-- After modifying these fields, you must redeploy the CacheRuntime for changes to take effect.
-- The system does not automatically detect or propagate changes to these fields.
+- Such a field takes effect only after the CacheRuntime is redeployed.
+- The system does not automatically detect or propagate these changes.
 
 ---
 
@@ -130,9 +148,10 @@ Aside from `runtimeVersion` and `resources`, **modifying any other fields in the
 |-------|-----------|---------------|
 | `runtimeVersion` | ✅ Yes | Automatically synced to AdvancedStatefulSet |
 | `resources` | ✅ Yes | Automatically synced to AdvancedStatefulSet (requires K8s >= 1.27) |
+| `replicas` | ✅ Yes | Automatically synced to AdvancedStatefulSet (scaling in discards that Worker's cache) |
 | All other fields | ❌ No | Not synced; redeployment required |
 
 **Key Takeaways**:
-1. The current version supports dynamic updates for only `runtimeVersion` and `resources`.
-2. In cgroupv1 environments, these two fields must be updated separately (step-by-step).
+1. The current version supports dynamic updates for `runtimeVersion`, `resources` and `replicas`.
+2. In cgroupv1 environments, `runtimeVersion` and `resources` must be updated separately (step-by-step); `replicas` is not subject to this limitation.
 3. Modifications to other fields will not take effect and require redeployment.

docs/zh/samples/cacheruntime/cacheruntime_spec_update.md

@@ -4,9 +4,10 @@
 
 本文档说明 CacheRuntime 的 Master 和 Worker 组件（基于 **AdvancedStatefulSet**）支持的 spec 字段更新能力。
 
-当前版本仅支持以下两个字段的原地更新：
+当前版本支持以下三个字段的原地更新：
 - **容器镜像** (`runtimeVersion`)
 - **资源限制** (`resources`)
+- **副本数** (`replicas`)
 
 其他字段的修改**不会同步到 AdvancedStatefulSet**，需要重新部署才能生效。
 
@@ -16,12 +17,12 @@
 
 | 组件 | 工作负载类型 | 字段更新支持 |
 |------|-------------|------------|
-| **Master** | AdvancedStatefulSet | ✅ 支持 `runtimeVersion` 和 `resources` |
-| **Worker** | AdvancedStatefulSet | ✅ 支持 `runtimeVersion` 和 `resources` |
+| **Master** | AdvancedStatefulSet | ✅ 支持 `runtimeVersion`、`resources` 和 `replicas` |
+| **Worker** | AdvancedStatefulSet | ✅ 支持 `runtimeVersion`、`resources` 和 `replicas` |
 | **Client** | DaemonSet | ❌ 不支持（任何变更都需重新部署） |
 
 **说明**：
-- Master 和 Worker 的 `runtimeVersion` 和 `resources` 字段修改会自动同步到 AdvancedStatefulSet
+- Master 和 Worker 的 `runtimeVersion`、`resources` 和 `replicas` 字段修改会自动同步到 AdvancedStatefulSet
 - Client 组件使用 DaemonSet，不支持动态更新
 
 ---
@@ -103,23 +104,40 @@ spec:
   ```
   详见 [Kubernetes Issue #127356](https://github.com/kubernetes/kubernetes/issues/127356)。
 
-## 4. 不支持更新的字段
+---
+
+### 3.3 副本数 (`replicas`)
+
+**字段路径**: `spec.{master,worker}.replicas`
+
+**示例**:
+```yaml
+spec:
+  worker:
+    replicas: 3
+```
+
+```bash
+kubectl patch cacheruntime my-cache --type='merge' -p '{"spec":{"worker":{"replicas":3}}}'
+```
 
-除 `runtimeVersion` 和 `resources` 外，**修改 CacheRuntime spec 中的其他字段不会同步到 AdvancedStatefulSet**，包括但不限于：
+修改后同步到 AdvancedStatefulSet 的 `spec.replicas`，由其完成扩缩容。
+
+**限制**：
+- ⚠️ **缩容会丢失缓存数据**：被缩掉的 Worker Pod 直接删除，其上已缓存的数据不会迁移到其余 Worker，需要重新从底层存储加载。扩容不影响已有缓存。
+- ⚠️ 扩缩容不会写入 RuntimeCondition，也不会产生 Kubernetes Event，只能从 controller 日志观察：
+  ```bash
+  kubectl -n fluid-system logs deploy/cacheruntime-controller | grep "replicas changed"
+  ```
+- ⚠️ 副本数超过可调度节点数时，多余的 Worker Pod 会一直处于 Pending。
+
+## 4. 不支持更新的字段
 
-- `env`: 环境变量
-- `podMetadata`: Pod 元数据（labels/annotations）
-- `args`/`command`: 容器启动参数
-- `ports`: 容器端口
-- `volumeMounts`/`volumes`: 存储配置
-- `nodeSelector`/`tolerations`/`affinity`: 调度配置
-- `securityContext`: 安全上下文
-- `replicas`: 副本数
-- `disabled`: 组件启用状态
+**第 3 节未列出的字段一律不支持原地更新**，修改后不会同步到 AdvancedStatefulSet。
 
 **说明**：
-- 修改这些字段后，需要重新部署 CacheRuntime 才能生效
-- 系统不会自动检测或同步这些字段的变更
+- 这类字段修改后，需要重新部署 CacheRuntime 才能生效
+- 系统不会自动检测或同步这类变更
 
 ---
 
@@ -129,9 +147,10 @@ spec:
 |------|------------|---------|
 | `runtimeVersion` | ✅ 支持 | 自动同步到 AdvancedStatefulSet |
 | `resources` | ✅ 支持 | 自动同步到 AdvancedStatefulSet（需 K8s >= 1.27） |
+| `replicas` | ✅ 支持 | 自动同步到 AdvancedStatefulSet（缩容会丢失该 Worker 上的缓存） |
 | 其他所有字段 | ❌ 不支持 | 不会同步，需重新部署 |
 
 **关键要点**：
-1. 当前版本仅支持 `runtimeVersion` 和 `resources` 两个字段的动态更新
-2. Cgroupv1 环境需分步更新这两个字段
+1. 当前版本支持 `runtimeVersion`、`resources` 和 `replicas` 三个字段的动态更新
+2. Cgroupv1 环境需分步更新 `runtimeVersion` 和 `resources`，`replicas` 不受此限制
 3. 其他字段的修改不会生效，必须重新部署

pkg/ddc/cache/engine/sync.go

@@ -64,8 +64,6 @@ func (e *CacheEngine) Sync(ctx cruntime.ReconcileRequestContext) (err error) {
 		return err
 	}
 
-	// TODO: implement other logic like inplace update and replica scaling
-
 	// Use lightweight getRuntimeStatusValue instead of full transform for status update
 	statusValue, err := e.getRuntimeStatusValue(runtime, runtimeClass)
 	if err != nil {