doc: add notes about upgrading cephfs

This is part of the run-up to removing all
TMAP code in the Jewel+1 cycle.

Signed-off-by: John Spray <john.spray@redhat.com>

diff --git a/PendingReleaseNotes b/PendingReleaseNotes
index c4140307b7030592cdfae60d79b1c16bcfb14e84..79b9cf0ce0376496061dd0cee154f082fcb8bdae 100644 (file)
--- a/PendingReleaseNotes
+++ b/PendingReleaseNotes
@@ -12,6 +12,10 @@ v10.0.0
   limit max waiting time of monitor election process, which was previously
   restricted by 'mon_lease'.
 
+* CephFS filesystems created using versions older than Firefly (0.80) must
+  use the new "cephfs-data-scan tmap_upgrade" command after upgrading to
+  Jewel.  See 'Upgrading' in the CephFS documentation for more information.
+
 v9.3.0
 ======
 * Some symbols wrongly exposed by librados in v9.1.0 and v9.2.0 were removed.

diff --git a/doc/cephfs/index.rst b/doc/cephfs/index.rst
index ad30220b06728efa26f43ba818854f76ccc64924..316db1d452e91f6e347d89da613093a99e6c72d3 100644 (file)
--- a/doc/cephfs/index.rst
+++ b/doc/cephfs/index.rst
@@ -92,6 +92,7 @@ authentication keyring.
        Troubleshooting <troubleshooting>
        Disaster recovery <disaster-recovery>
        Client authentication <client-auth>
+       Upgrading old filesystems <upgrading>
 
 .. raw:: html
 

diff --git a/doc/cephfs/upgrading.rst b/doc/cephfs/upgrading.rst
new file mode 100644 (file)
index 0000000..7ee3f09
--- /dev/null
+++ b/doc/cephfs/upgrading.rst
@@ -0,0 +1,34 @@
+
+Upgrading pre-Firefly filesystems past Jewel
+============================================
+
+.. tip::
+
+    This advice only applies to users with filesystems
+    created using versions of Ceph older than *Firefly* (0.80).
+    Users creating new filesystems may disregard this advice.
+
+Pre-firefly versions of Ceph used a now-deprecated format
+for storing CephFS directory objects, called TMAPs.  Support
+for reading these in RADOS will be removed after the Jewel
+release of Ceph, so for upgrading CephFS users it is important
+to ensure that any old directory objects have been converted.
+
+After installing Jewel on all your MDS and OSD servers, and restarting
+the services, run the following command:
+
+::
+    
+    cephfs-data-scan tmap_upgrade <metadata pool name>
+
+This only needs to be run once, and it is not necessary to
+stop any other services while it runs.  The command may take some
+time to execute, as it iterates overall objects in your metadata
+pool.  It is safe to continue using your filesystem as normal while
+it executes.  If the command aborts for any reason, it is safe
+to simply run it again.
+
+If you are upgrading a pre-Firefly CephFS filesystem to a newer Ceph version
+than Jewel, you must first upgrade to Jewel and run the ``tmap_upgrade``
+command before completing your upgrade to the latest version.
+