How In‑Place Upgrades Work in Kubernetes with OpenKruise

In‑place upgrade overview

An in‑place upgrade changes the image field of one or more containers inside an existing Pod without deleting the Pod object. The Pod’s IP address, node placement, attached PersistentVolumes and other containers remain unchanged.

Why use in‑place upgrade?

Scheduling latency is avoided because the Pod stays on the same node with the same resource allocation.

The original IP address is retained, eliminating network re‑allocation.

Mounted volumes stay attached, so no extra PV/PVC operations are needed.

Image pull time is reduced; the node already caches most layers of the previous image.

Side‑car containers (e.g., log collectors) continue running, reducing disruption.

Cluster‑level components (apiserver, scheduler, network) experience less load compared with full Pod recreation.

Technical background

1. Kubelet container version management

Kubelet computes a hash for each container image referenced in spec.containers. When the image field is modified, the hash changes, prompting kubelet to stop the old container and start a new one based on the updated image.

2. Pod update restrictions

// validate updateable fields:
// 1. spec.containers[*].image
// 2. spec.initContainers[*].image
// 3. spec.activeDeadlineSeconds

Only the fields listed above can be changed on an existing Pod; any other spec modifications are rejected by the apiserver.

3. containerStatuses reporting

apiVersion: v1
kind: Pod
spec:
  containers:
  - name: nginx
    image: nginx:latest
status:
  containerStatuses:
  - name: nginx
    image: nginx:mainline
    imageID: docker-pullable://nginx@sha256:2f68b9...

The status.containerStatuses[x].image may differ from the spec image when multiple tags resolve to the same imageID. Therefore, comparing spec and status images is unreliable for upgrade verification.

4. ReadinessGate control

apiVersion: v1
kind: Pod
spec:
  readinessGates:
  - conditionType: MyDemo
status:
  conditions:
  - type: MyDemo
    status: "True"
  - type: ContainersReady
    status: "True"
  - type: Ready
    status: "True"

A Pod is considered Ready only when all containers are ready and every custom condition defined in readinessGates is true.

OpenKruise implementation

1. How a single Pod is upgraded in place

OpenKruise updates only spec.containers[x].image. Kubelet detects the hash change, stops the old container, and creates a new container with the new image while keeping the Pod object unchanged.

2. Determining upgrade success

Before the image change, record status.containerStatuses[x].imageID. After the update, a different imageID indicates that the container has been rebuilt. Using a different tag that resolves to the same imageID will not be detected as a successful upgrade.

3. Ensuring zero‑traffic loss

Define a custom condition (e.g., InPlaceUpdateReady) in spec.readinessGates. The upgrade workflow is:

Set the condition to False → Pod becomes NotReady and is removed from Service endpoints.

Optionally wait gracePeriodSeconds for the endpoint controller to observe the change.

Update the container image field, triggering the in‑place upgrade.

After the new container is running, set the condition back to True → Pod returns to Ready state.

4. Combining with rollout strategies

partition : only a subset of replicas (defined by replicas‑partition) are upgraded.

maxUnavailable : limits the number of Pods that may be NotReady simultaneously.

maxSurge : creates extra Pods first; the original Pods are then upgraded in place.

priority / scatter : upgrades follow defined priority or distribution rules.

Reference

OpenKruise project repository: https://github.com/openkruise/kruise