etcd compatibility — the K8s minor and the etcd minor

etcd is a separate project with its own versioning. The Kubernetes project’s compatibility matrix maps Kubernetes minor versions to etcd minor versions. This lesson walks the version kubeadm pins for Kubernetes 1.34.x and the upgrade implications.

The version kubeadm ships

kubeadm does not accept a range. It carries a table mapping each Kubernetes minor to exactly one etcd image tag, and kubeadm init and kubeadm upgrade write that tag into the etcd static Pod manifest:

1.34 is the release that moves the default from etcd 3.5 to etcd 3.6. Everything from 1.31 to 1.33 stayed on 3.5.x.

flowchart LR
    A[Kubernetes 1.34.x] --> B[etcd 3.6.5-0]
    C[Kubernetes 1.33.x] --> D[etcd 3.5.24-0]
    E[Kubernetes 1.32.x] --> F[etcd 3.5.24-0]

The etcd upgrade

The etcd upgrade is part of the Kubernetes upgrade:

sudo kubeadm upgrade apply v1.34.1 --etcd-upgrade=true

The flag:

• --etcd-upgrade=true (default): the etcd binary is upgraded to the version this kubeadm ships.
• --etcd-upgrade=false: the etcd binary is left alone; the etcd version stays where it is.

The default is --etcd-upgrade=true, so the etcd upgrade happens unless the operator opts out. On a 1.33 to 1.34 upgrade that default is what moves the cluster from etcd 3.5 to etcd 3.6.

sequenceDiagram
    participant K as kubeadm
    participant FS as /etc/kubernetes/manifests/
    participant KL as kubelet
    participant E as etcd
    K->>FS: write new etcd.yaml (3.6.5-0)
    K->>KL: notify via file watch
    KL->>E: terminate pod
    KL->>E: start new pod (3.6.5-0)
    E-->>K: pod started

The etcd static pod is restarted with the new binary.

The etcd upgrade procedure

The upgrade is in two phases:

1. Snapshot. Before the upgrade, etcd takes a snapshot (the pre-upgrade snapshot; Lesson 3 of Part LXXVII).
2. Binary update. The etcd binary is updated; the static pod is restarted.

The data migration is automatic if the new version requires it. The snapshot is the recovery path if the migration fails.

The validation

# Get the etcd version as reported by the running member
sudo etcdctl version

# Or read the tag kubeadm wrote into the manifest
sudo grep -- 'image:' /etc/kubernetes/manifests/etcd.yaml

etcdctl version reports the client version and the API version it speaks. The image tag in the manifest is the authoritative record of what kubeadm placed on the node.

# Verify the cluster version
kubectl version

Server Version: v1.34.1

The Kubernetes version is reported.

The etcd version skew

The etcd version skew:

Kubernetes 1.34.x
etcd 3.6.x → the version kubeadm ships
etcd 3.5.x → what the cluster ran before the upgrade
etcd 3.4.x → end of life

kubeadm’s supported-versions table is the authoritative record of what it will install. Read it, and the etcd upgrade guide, before upgrading.

The external etcd

For an external etcd cluster — one installed from the release tarball or a distribution package, with its own etcd.service unit — the upgrade is independent of the Kubernetes upgrade. This is the one etcd topology where systemctl applies:

# On the etcd host
sudo systemctl stop etcd
sudo cp /usr/local/bin/etcd /usr/local/bin/etcd.bak
sudo cp /tmp/etcd-v3.6.5 /usr/local/bin/etcd
sudo systemctl start etcd

Each etcd member is upgraded in sequence. The cluster quorum is maintained.

sequenceDiagram
    participant O as Operator
    participant E1 as etcd member 1
    participant E2 as etcd member 2
    participant E3 as etcd member 3
    O->>E1: stop, upgrade, start
    E1-->>O: ready
    O->>E2: stop, upgrade, start
    E2-->>O: ready
    O->>E3: stop, upgrade, start
    E3-->>O: ready

The members are upgraded one at a time. The cluster maintains quorum throughout.

The etcd version in the kubeadm config

The kubeadm config records the etcd version:

apiVersion: kubeadm.k8s.io/v1beta4
kind: ClusterConfiguration
etcd:
  local:
    imageRepository: registry.k8s.io
    imageTag: 3.6.5-0

The image tag is the etcd version, and kubeadm writes it without a v prefix. Setting it here pins etcd independently of the Kubernetes minor; leaving it unset lets kubeadm use the version it ships.

Cross-course references

• The Linux course covers binary version management.
• The Observability course covers etcd metrics and alerting.
• The Terraform course covers etcd version pinning in IaC.

Quiz

Production discipline

• Check the compatibility matrix first. Each Kubernetes minor maps to etcd minors.
• Take a snapshot before the etcd upgrade. The snapshot is the safety net.
• Use —etcd-upgrade=true explicitly. The default is false.
• Upgrade one member at a time. Quorum is maintained as long as majority is running.
• Validate after each restart. etcdctl endpoint health confirms the member.
• Document the etcd version in the runbook. The version, the upgrade procedure, the snapshot ID.

The etcd version is the cluster’s data layer. Operating it well is upgrading with the rest of the cluster and maintaining quorum throughout.