diff --git a/vcluster_versioned_docs/version-0.30.0/_fragments/safely-upgrade-etcd.mdx b/vcluster_versioned_docs/version-0.30.0/_fragments/safely-upgrade-etcd.mdx
new file mode 100644
index 000000000..e1a32f3e1
--- /dev/null
+++ b/vcluster_versioned_docs/version-0.30.0/_fragments/safely-upgrade-etcd.mdx
@@ -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/).
+
+
+
+
+
+
+ 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:
+ 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
+ ```
+
+
+
+
diff --git a/vcluster_versioned_docs/version-0.30.0/configure/vcluster-yaml/control-plane/components/backing-store/etcd/embedded.mdx b/vcluster_versioned_docs/version-0.30.0/configure/vcluster-yaml/control-plane/components/backing-store/etcd/embedded.mdx
index 271d46a61..69f3af516 100644
--- a/vcluster_versioned_docs/version-0.30.0/configure/vcluster-yaml/control-plane/components/backing-store/etcd/embedded.mdx
+++ b/vcluster_versioned_docs/version-0.30.0/configure/vcluster-yaml/control-plane/components/backing-store/etcd/embedded.mdx
@@ -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.
diff --git a/vcluster_versioned_docs/version-0.30.0/learn-how-to/control-plane/container/safely-upgrade-etcd.mdx b/vcluster_versioned_docs/version-0.30.0/learn-how-to/control-plane/container/safely-upgrade-etcd.mdx
new file mode 100644
index 000000000..31af6a518
--- /dev/null
+++ b/vcluster_versioned_docs/version-0.30.0/learn-how-to/control-plane/container/safely-upgrade-etcd.mdx
@@ -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).
+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](https://etcd.io/docs/latest/upgrades/upgrade_3_6/).
+
+
+
+## Config reference
+
+