Why is in-place update needed?
In earlier versions, as described in "Taking Specified Instance Offline," KubeBlocks used StatefulSet as the final workload type, inheriting its limitations.
One key drawback of StatefulSet is its update mechanism: changes to the PodTemplate trigger updates to all Pods, using the Recreate strategy. This process deletes and recreates Pods, which is far from ideal for systems like databases that require high availability.
To address this issue, starting from v0.9, KubeBlocks replaced StatefulSet with InstanceSet and introduced the in-place update feature. This feature allows InstanceSet to update instances by in-place Pod update or expand PVC volumes when certain fields in instance templates updates, significantly reducing the impact on system availability.
Which fields support in-place updates?
KubeBlocks leverages Kubernetes' native Pod API for in-place updates. The supported fields include:
annotationslabelsspec.activeDeadlineSecondsspec.initContainers[*].imagespec.containers[*].imagespec.tolerations(only supports adding new Toleration)
Starting from Kubernetes v1.27, the InPlacePodVerticalScaling feature enables in-place updates for CPU and memory resources. KubeBlocks also integrates this feature to further support the following capabilities:
For Kubernetes v1.27 or later, with InPlacePodVerticalScaling enabled, supported fields are as follow:
spec.containers[*].resources.requests["cpu"]spec.containers[*].resources.requests["memory"]spec.containers[*].resources.limits["cpu"]spec.containers[*].resources.limits["memory"]
Note that after resizing resources, some applications may require a restart to detect the updated resource configurations. You can manage this behavior using the container restartPolicy in ClusterDefinition or ComponentDefinition.
For PVCs, KubeBlocks utilizes the PVC API to support volume expansion. If volume expansion fails, the PVC can be reverted to its original size. In contrast, StatefulSet does not allow modifications to the VolumeClaimTemplate after declaration. Although Kubernetes plans to address this limitation, it is expected to be resolved only after v1.32.
Which API fields trigger in-place updates?
The KubeBlocks APIs—Cluster, ClusterDefinition, ClusterVersion, ComponentDefinition, and ComponentVersion—contain fields that may directly or indirectly trigger in-place updates. These fields are used to render instance objects and determine update behavior.
There are plenty of such fields and the table below provides a concise overview. Note that deprecated and immutable fields are excluded.
| API | Fields | Description |
|---|---|---|
| Cluster | annotations,
| Resources related fields means:
limits["memory"] |
| ComponentVersion | spec.releases[*].images | Whether in-place update is triggered depends on whether the corresponding image is changed. |
| KubeBlocks Built-in | annotations, labels |
The IgnorePodVerticalScaling feature switch
Demand for in-place resource updates has been consistently high. In Kubernetes earlier than v1.27, many Kubernetes distributions offer in-place updates for Resources through custom implementations. These methods vary across distributions.
To ensure compatibility, KubeBlocks introduces the IgnorePodVerticalScaling switch. When enabled, KubeBlocks ignores CPU and memory updates in Resources during instance updates, ensuring the running Pod’s Resources configuration remains unchanged. This helps maintain consistency across different Kubernetes distributions.