KubeBlocks
BlogsEnterprise
⌘K
​
Blogs

Overview
Quickstart
Architecture

Operations

Lifecycle Management
Vertical Scaling
Horizontal Scaling
Volume Expansion
Switchover
Minor Version Upgrade
Manage Services

Backup & Restore

Backup
Restore

Observability

Observability for etcd Clusters
  1. Prerequisites
  2. List Available etcd Versions
  3. Step 1: Check the Current Version
  4. Step 2: Apply the Upgrade
  5. Step 3: Verify the Upgrade
  6. Cleanup

Upgrading the Minor Version of an etcd Cluster in KubeBlocks

This guide walks you through upgrading an etcd cluster to a newer minor version managed by KubeBlocks.

KubeBlocks performs a rolling upgrade: followers are upgraded one by one first, and the leader is upgraded last. This ensures the cluster maintains quorum and client connections are not interrupted during the upgrade.

CAUTION

No Downgrade Support

etcd does not support downgrading between minor versions. Once data is written by a newer version (e.g., 3.6.x), it cannot be read by an older version (e.g., 3.5.x) due to storage format changes. Always test upgrades in a non-production environment first and take a backup before upgrading.

Prerequisites

    Before proceeding, verify your environment meets these requirements:

    • A functional Kubernetes cluster (v1.21+ recommended)
    • kubectl v1.21+ installed and configured with cluster access
    • Helm installed (installation guide)
    • KubeBlocks installed (installation guide)
    • etcd Add-on installed and an etcd cluster running (see Quickstart)

    List Available etcd Versions

    kubectl get componentversion etcd
    Example Output
    NAME   VERSIONS             STATUS      AGE
etcd   3.6.1,3.5.15,3.5.6   Available   6h

    Step 1: Check the Current Version

    kubectl get cluster etcd-cluster -n demo \
  -o jsonpath='{.spec.componentSpecs[0].serviceVersion}' && echo ""
    Example Output
    3.5.15

    Check the current pod roles:

    kubectl get pods -n demo -l app.kubernetes.io/instance=etcd-cluster -L kubeblocks.io/role
    Example Output
    NAME                  READY   STATUS    RESTARTS   AGE   ROLE
etcd-cluster-etcd-0   2/2     Running   0          5m    follower
etcd-cluster-etcd-1   2/2     Running   0          5m    follower
etcd-cluster-etcd-2   2/2     Running   0          5m    leader

    Step 2: Apply the Upgrade

    Upgrade from 3.5.15 to 3.6.1:

    apiVersion: operations.kubeblocks.io/v1alpha1
kind: OpsRequest
metadata:
  name: etcd-upgrade
  namespace: demo
spec:
  clusterName: etcd-cluster
  type: Upgrade
  upgrade:
    components:
    - componentName: etcd
      serviceVersion: "3.6.1"

    Apply it:

    kubectl apply -f https://raw.githubusercontent.com/apecloud/kubeblocks-addons/refs/heads/main/examples/etcd/upgrade.yaml

    Monitor the progress:

    kubectl get ops etcd-upgrade -n demo -w
    Example Output
    NAME           TYPE      CLUSTER        STATUS    PROGRESS   AGE
etcd-upgrade   Upgrade   etcd-cluster   Running   0/3        6s
etcd-upgrade   Upgrade   etcd-cluster   Running   1/3        12s
etcd-upgrade   Upgrade   etcd-cluster   Running   2/3        18s
etcd-upgrade   Upgrade   etcd-cluster   Running   3/3        24s
etcd-upgrade   Upgrade   etcd-cluster   Succeed   3/3        28s

    Update the serviceVersion field in the Cluster resource:

    kubectl patch cluster etcd-cluster -n demo --type=json \
  -p='[{"op": "replace", "path": "/spec/componentSpecs/0/serviceVersion", "value": "3.6.1"}]'

    Monitor the cluster status:

    kubectl get cluster etcd-cluster -n demo -w

    Step 3: Verify the Upgrade

    Check that all pods are running with the new version:

    kubectl get pods -n demo -l app.kubernetes.io/instance=etcd-cluster -L kubeblocks.io/role
    Example Output
    NAME                  READY   STATUS    RESTARTS   AGE   ROLE
etcd-cluster-etcd-0   2/2     Running   0          8m    follower
etcd-cluster-etcd-1   2/2     Running   0          8m    leader
etcd-cluster-etcd-2   2/2     Running   0          8m    follower

    Confirm the image version:

    kubectl get pods -n demo etcd-cluster-etcd-0 \
  -o jsonpath='{.spec.containers[?(@.name=="etcd")].image}' && echo ""
    Example Output
    docker.io/apecloud/etcd:3.6.1

    Cleanup

    kubectl delete cluster etcd-cluster -n demo
kubectl delete ns demo

    © 2026 KUBEBLOCKS INC