Safely upgrade ETCD v3.5 -> v3.6
Upgrade ETCD from v3.5 to v3.6 in vCluster​
In vCluster, etcd can serve as the underlying storage backend, similar to vanilla Kubernetes. Its version can be configured either explicitly using a controlPlane.backingStore.etcd.deploy.statefulSet.image.tag section in the vcluster.yaml or implicitly derived from the vCluster version.
Before upgrading, back up your data. Deployed etcd doesn't support vcluster snapshot create, so back it up with its own tooling instead. For embedded etcd, take a vCluster snapshot. See Back up and restore for details.
etcd has identified and fixed an additional scenario that may cause upgrade failures when moving from etcd v3.5 to v3.6, specifically during rolling replacement upgrades where a new learner may receive an incorrect snapshot from an older member (≤ v3.5.19). This issue, detailed in issue #20793, was addressed in etcd v3.5.24 using PR #20797.
The recommended solution is to first upgrade to etcd v3.5.24 (or higher) before proceeding to v3.6. For users on v3.5.20-v3.5.23 from a fresh install, a direct upgrade to v3.6 is safe.
To safely upgrade etcd in vCluster, continue reading this page for detailed steps.
For more details, refer to the etcd upgrade guide.
Version matrix for embedded ETCD and vCluster​
| vCluster Version | ETCD Version |
|---|---|
| v0.26.4 | v3.5.21 |
| v0.26.5 | v3.5.25 |
| v0.27.2 | v3.5.21 |
| v0.27.3 | v3.5.25 |
| v0.28.1 | v3.5.21 |
| v0.28.2 | v3.5.25 |
| v0.29.*+ | v3.6.* |
Important: Before upgrading, read the ETCD blog post about upgrading from 3.5 to 3.6.
- Embedded ETCD
- Deployed ETCD
- vCluster v0.26.[0-4]
- vCluster v0.27.[0-2]
- vCluster v0.28.[0-1]
First upgrade to v0.26.5, it uses ETCD v3.5.25. Then, your ETCD data will be saved in a format compatible with upgrade to v3.6
First upgrade to v0.27.3, it uses ETCD v3.5.25. Then, your ETCD data will be saved in a format compatible with upgrade to v3.6
First upgrade to v0.28.2, it uses ETCD v3.5.25. Then, your ETCD data will be saved in a format compatible with upgrade to v3.6
Follow the ETCD-recommended upgrade path:
- v3.5.21 → v3.5.25
- v3.5.25 → v3.6.x
You may set ETCD image tag via:
controlPlane:
backingStore:
etcd:
deploy:
statefulSet:
image:
registry: quay.io
repository: coreos/etcd
tag: v3.5.25
Config reference​
For every field under controlPlane.backingStore, see the controlPlane reference.