loft-sh · Piotr1215 · Dec 19, 2025 · Dec 19, 2025 · Dec 19, 2025 · Dec 19, 2025
@@ -0,0 +1,58 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+
+
+## 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](https://etcd.io/blog/2025/upgrade_from_3.5_to_3.6_issue_followup/).
+
+<Tabs>
+  <TabItem value="embedded" label="Embedded ETCD">
+
+    <Tabs>
+      <TabItem value="v0.26" label="vCluster v0.26.[0-4]">
+        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
+      </TabItem>
+      <TabItem value="v0.27" label="vCluster v0.27.[0-2]">
+        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
+      </TabItem>
+      <TabItem value="v0.28" label="vCluster v0.28.[0-1]">
+        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
+      </TabItem>
+    </Tabs>
+
+  </TabItem>
+
+  <TabItem value="deploy" label="Deployed ETCD">
+
+    Follow the ETCD-recommended upgrade path:
+    1. **v3.5.21 → v3.5.25**
+    2. **v3.5.25 → v3.6.x**
+
+    You may set ETCD image tag via:
+    ```yaml title="vcluster.yaml"
+    controlPlane:
+      backingStore:
+        etcd:
+          deploy:
+            statefulSet:
+              image:
+                registry: quay.io
+                repository: coreos/etcd
+                tag: v3.5.25
+    ```
+
+  </TabItem>
+
+</Tabs>
@@ -26,6 +26,8 @@ An issue exists when upgrading etcd (from version 3.5.1 or later, but earlier th
 
 To avoid this issue, vCluster does not upgrade etcd to version 3.6 until vCluster version 0.29.0.
 
+Follow [vCluster documentation](../../../../../../learn-how-to/control-plane/container/safely-upgrade-etcd) on how to upgrade from v3.5 -> v3.6.
+
 Any vCluster running a version earlier than 0.24.2, must first be upgraded to a version between 0.24.2 and 0.28.x, before upgrading to version 0.29.0.
 
 For more information, see the [official etcd documentation](https://etcd.io/blog/2025/upgrade_from_3.5_to_3.6_issue/).
@@ -66,7 +68,7 @@ Wait at least 10 minutes before deleting the replica pod and PVC. This action ca
 
 #### Recover the entire cluster
 
-In rare cases, the entire etcd cluster requires manual recovery. This occurs when the majority of etcd member replicas become corrupted or deleted simultaneously (such as 2 of 3, 3 of 5, or 4 of 7 replicas). In this scenario, etcd fails to start and vCluster cannot recover automatically.
+In rare cases, the entire etcd cluster requires manual recovery. This occurs when the majority of etcd member replicas become corrupted or deleted simultaneously (such as 2 of 3, 3 of 5, or 4 of 7 replicas). In this scenario, etcd fails to start.
 
 :::note
 Normal pod restarts or terminations do not require manual recovery. These events trigger automatic leader election within the etcd cluster.

@@ -0,0 +1,25 @@
+---
+title: Safely upgrade ETCD v3.5 -> v3.6
+sidebar_label: Upgrade ETCD to v3.6
+sidebar_position: 6
+toc_max_heading_level: 3
+description: Learn how to upgrade ETCD to v3.6 in your virtual cluster.
+---
+
+import EtcdUpgradeGuide from '@site/vcluster/_fragments/safely-upgrade-etcd.mdx'
+import BackingStore from '../../../_partials/config/controlPlane/backingStore.mdx'
+
+## 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 via a `controlPlane.backingStore.etcd.deploy.statefulSet.image.tag` section in the `vcluster.yaml` or implicitly derived from the vCluster version. Before upgrading, we recommend taking an etcd snapshot for safety; the procedure is detailed in the [backup documentation](../../../manage/backup-restore/backup).
+
+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](https://github.com/etcd-io/etcd/issues/20793), was addressed in etcd v3.5.24 via [PR #20797](https://github.com/etcd-io/etcd/pull/20797). <br/>
+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. <br/>
+To safely upgrade etcd in vCluster, continue reading this page for detailed steps.<br/><br/>
+For more details, refer to the [etcd upgrade guide](https://etcd.io/docs/latest/upgrades/upgrade_3_6/).
+
+<EtcdUpgradeGuide />
+
+## Config reference
+
+<BackingStore />