Add note on downgrades

stackabletech · Aug 9, 2024 · b24c25f · b24c25f
1 parent 49cf9d9
commit b24c25f
Showing 1 changed file with 20 additions and 0 deletions.
diff --git a/docs/modules/hdfs/pages/usage-guide/upgrading.adoc b/docs/modules/hdfs/pages/usage-guide/upgrading.adoc
@@ -4,6 +4,25 @@ IMPORTANT: HDFS upgrades are experimental, and details may change at any time
 
 HDFS currently requires a manual process to upgrade. This guide will take you through an example case, upgrading an example cluster (from our xref:getting_started/index.adoc[Getting Started] guide) from HDFS 3.3.6 to 3.4.0.
 
+== Preparing for the worst
+
+Upgrades can fail, and it is important to prepare for when that happens. Apache HDFS supports https://hadoop.apache.org/docs/r3.4.0/hadoop-project-dist/hadoop-hdfs/HdfsRollingUpgrade.html#Downgrade_and_Rollback[two ways to revert an upgrade]:
+
+Rollback:: Reverts all user data to the pre-upgrade state. Requires taking the cluster offline.
+Downgrade:: Downgrades the HDFS software but preserves all changes made by users. Can be performed as a rolling change, keeping the cluster online.
+
+The Stackable Operator for HDFS supports downgrading but not rollbacks.
+
+In order to downgrade, revert the `.spec.image.productVersion` field, and then proceed to xref:#finalize[finalizing] once the cluster is downgraded:
+
+[source,shell]
+----
+$ kubectl patch hdfs/simple-hdfs --patch '{"spec": {"image": {"productVersion": "3.3.6"}}}' --type=merge
+hdfscluster.hdfs.stackable.tech/simple-hdfs patched
+----
+
+WARNING: The Stackable Operator for HDFS will _not_ currently roll downgrades in order, they will incur some downtime.
+
 == Preparing HDFS
 
 HDFS must be configured to initiate the upgrade process. To do this, put the cluster into upgrade mode by running the following commands in an HDFS superuser environment
@@ -58,6 +77,7 @@ NOTE: This will automatically enable the NameNodes' compatibility mode, allowing
 
 NOTE: Services will be upgraded in order: JournalNodes, then NameNodes, then DataNodes.
 
+[#finalize]
 == Finalizing the upgrade
 
 Once all HDFS pods are running the new version, the HDFS upgrade can be finalized (from the HDFS superuser environment as described in the preparation step):