跳到主要内容
版本:v1.1

CacheRuntime Spec Field Update Capabilities

1. Overview​

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 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.


2. Supported Components​

ComponentWorkload TypeField Update Support
MasterAdvancedStatefulSet✅ Supports runtimeVersion, resources and replicas
WorkerAdvancedStatefulSet✅ Supports runtimeVersion, resources and replicas
ClientDaemonSet❌ Not supported (any changes require redeployment)

Notes:

  • 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.

3. Supported Update Fields​

3.1 Container Image (runtimeVersion)​

Field path: spec.{master,worker}.runtimeVersion

Supported sub-fields:

  • image: Image name
  • imageTag: Image tag

Example:

spec:
worker:
runtimeVersion:
image: fluid-cache
imageTag: v1.1.0

Resolution: on creation and on every reconcile, the image of the component's first container in the CacheRuntimeClass template is the baseline, and the image and imageTag set in the CacheRuntime override it.

Completion rules:

  • image and imageTag may be set on their own. The missing half is taken from the template image. With a template image of fluid-cache:v1.0.0:
    • Only imageTag: v1.1.0: the template's image name is kept, giving fluid-cache:v1.1.0
    • Only image: registry.example.com/fluid-cache: the template's tag is kept (not latest), giving registry.example.com/fluid-cache:v1.0.0
    • Neither: the template image fluid-cache:v1.0.0 is used
  • A runtimeVersion setting both image and imageTag is used as is, even when the template image is pinned by digest.
  • When only one half is set and the other cannot be completed (only image is set and the template image has no tag, or the template image or image is pinned by digest (@sha256:...)), the component uses the template image on creation; on update the edit has no effect and the component keeps its current image. In both cases the controller emits a RuntimeVersionIncomplete Warning event on the CacheRuntime and logs the edit; the client, which is not updated in place, reports it on creation only. runtimeVersion cannot express a digest reference; to pin a digest, put it in the CacheRuntimeClass template.
  • Data operations that name no image of their own (such as DataLoad) use the same completed image as the worker. When the worker's version cannot be completed they use the template image, so they can differ from a worker that kept its current image, for example after the template image is changed to one pinned by digest.

Limitations:

  • ⚠️ In cgroupv1 environments, this field cannot be updated simultaneously with resources (perform step-by-step; see the resource field section below).
  • ⚠️ When setting only image, make sure the template's tag exists in the new repository. Otherwise the pods fail with ImagePullBackOff; on an in-place update the component is unavailable until the new image can be pulled. The same holds the other way round: an instance that sets only imageTag moves to that tag in the new repository when the template's image repository changes, so make sure the tag exists there too.
  • ⚠️ Image edits in the CacheRuntimeClass template reach existing instances: after the template image changes, each enabled master and worker of a CacheRuntime using that CacheRuntimeClass that does not fully set runtimeVersion is re-resolved against the new template image, and rolls only if the resolved image changes (one that sets only imageTag keeps its tag, one that sets only image keeps its image name; an instance that cannot be resolved to a name:tag image keeps its current image, for example when the new template image is pinned by digest). The controller does not watch CacheRuntimeClass, so the change takes effect on each CacheRuntime's next reconcile rather than immediately. The client is not updated.
  • ⚠️ Removing runtimeVersion from a CacheRuntime returns the component to the template image, except when the template image has no tag or is pinned by digest: the component then keeps its current image, and you need to set a full runtimeVersion or recreate the CacheRuntime.

3.2 Resource Limits (resources)​

Field path: spec.{master,worker}.resources

Supported sub-fields:

  • requests.cpu: CPU request
  • requests.memory: Memory request
  • limits.cpu: CPU limit
  • limits.memory: Memory limit
  • claims: Dynamic Resource Allocation (DRA) claims; they can only reference pod-level resourceClaims the template declares, see the limitations below

Example:

spec:
worker:
resources:
requests:
cpu: "4"
memory: 8Gi
limits:
cpu: "8"
memory: 16Gi

Resolution order:

resources is resolved as follows on every reconcile:

  1. the resources declared by the CacheRuntimeClass template form the baseline;
  2. the resources set on the CacheRuntime are overlaid on that baseline key by key — requests and limits merge by resource name, claims by claim name;
  3. a key neither declares is cleared from the workload.

The CacheRuntime therefore expresses only the differences it wants from the template. Naming limits.memory alone moves that one value and leaves the template's requests.cpu, requests.memory and limits.cpu in place.

Removing a key from the CacheRuntime works the same way: it falls back to the template's value, or is cleared from the workload when the template does not declare it. An empty list such as limits: {} names no key, so it reads the same as leaving limits out.

Limitations:

  • ⚠️ Cannot exceed the node's available resources.
  • ⚠️ A key the CacheRuntimeClass template declares can be overridden but not removed: omitting it from the CacheRuntime leaves the template's value in place rather than leaving the component unconstrained. To adjust resource requirements, explicitly set the desired values in the CacheRuntime.
  • ⚠️ How CacheRuntimeClass edits affect existing CacheRuntimes is tracked in #6213; don't rely on them reaching existing instances.
  • ⚠️ The CacheRuntime and its template are the source of truth: resources edited directly on the master or worker AdvancedStatefulSet are reverted on the next reconcile.
  • ⚠️ A request must not exceed its limit after the merge: the template and the CacheRuntime can each be valid and still merge into a request above its limit, for example a template requests.cpu: 1 with a CacheRuntime limits.cpu: 500m. Huge pages (hugepages-*) and extended resources (such as nvidia.com/gpu) are stricter: their request must equal their limit, and a request needs a limit, so a template setting nvidia.com/gpu to 1 for both with a CacheRuntime raising only the limit to 2 conflicts as well. The controller then does not sync that component's resources, keeps the workload's current values and emits a RuntimeResourcesConflict Warning event on the CacheRuntime naming the conflicting keys; a new CacheRuntime with such a pair fails to set up. Set the matching request on the CacheRuntime too (equal to the limit for huge pages and extended resources), or change the template.
  • ⚠️ claims can only reference pod-level resourceClaims the workload declares: the CacheRuntime sets the container's resources.claims but cannot add pod-level spec.resourceClaims, and the sync does not carry pod-level resourceClaims added to the CacheRuntimeClass template after creation to existing workloads either. On creation, a claim name the template does not declare makes the API server reject every master or worker Pod (must be one of the names in pod.spec.resourceClaims), and the component stays NotReady; clusters without DynamicResourceAllocation enabled (off by default before K8s 1.34) drop claims silently instead. On update, a claim that the workload neither declares nor already carries, whether it comes from the CacheRuntime or from a template edit, is not synced: the controller leaves it out, still syncs the rest of resources, and emits a RuntimeResourcesConflict Warning event on the CacheRuntime naming the claim. To use a new claim, recreate the CacheRuntime.
  • ⚠️ Kubernetes version requirement: K8s >= 1.27 with the InPlacePodVerticalScaling Feature Gate enabled.
    # Check if the Feature Gate is enabled
    kubectl get nodes -o jsonpath='{.items[0].status.config.kubeletConfig.featureGates.InPlacePodVerticalScaling}'
  • ⚠️ Cgroupv1 limitation: Cannot be updated simultaneously with the runtimeVersion field.
    • Reason: Cgroupv1 does not support updating container image and resource limits in the same operation.
    • Solution: Perform step-by-step updates — update resources first, wait for completion, then update the image.
    # Step 1: Update resources
    kubectl patch cacheruntime my-cache --type='merge' -p '{"spec":{"worker":{"resources":{"requests":{"cpu":"4","memory":"8Gi"}}}}}'
    kubectl wait pod -l fluid.io/cache-runtime-name=my-cache --for=condition=InPlaceUpdateReady --timeout=300s

    # Step 2: Update image
    kubectl patch cacheruntime my-cache --type='merge' -p '{"spec":{"worker":{"runtimeVersion":{"imageTag":"v1.1.0"}}}}'
    See Kubernetes Issue #127356.

3.3 Replica Count (replicas)​

Field path: spec.{master,worker}.replicas

Example:

spec:
worker:
replicas: 3
kubectl patch cacheruntime my-cache --type='merge' -p '{"spec":{"worker":{"replicas":3}}}'

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. Progress can be observed through status.{master,worker}.{readyReplicas,desiredReplicas} or the controller logs:
    # Current replica status
    kubectl get cacheruntime my-cache -o jsonpath='{.status.worker.readyReplicas}/{.status.worker.desiredReplicas}'

    # Or from the controller logs
    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​

Any field not listed in section 3 cannot be updated in place; changes to it are not propagated to the AdvancedStatefulSet.

Notes:

  • Such a field takes effect only after the CacheRuntime is redeployed.
  • The system does not automatically detect or propagate these changes.

5. Summary​

FieldSupportedUpdate Method
runtimeVersion✅ YesAutomatically synced to AdvancedStatefulSet
resources✅ YesAutomatically synced to AdvancedStatefulSet (requires K8s >= 1.27)
replicas✅ YesAutomatically synced to AdvancedStatefulSet (scaling in discards that Worker's cache)
All other fields❌ NoNot synced; redeployment required

Key Takeaways:

  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.