dumpling-firefly-x: document structure of suite

Hopefully this makes it easier to digest and maintain
than reading yaml fragments.

Signed-off-by: Josh Durgin <josh.durgin@inktank.com>
Signed-off-by: Yuri Weintstein <yuri.weinstein@inktank.com>

diff --git a/suites/upgrade/dumpling-firefly-x/parallel/README b/suites/upgrade/dumpling-firefly-x/parallel/README
new file mode 100644 (file)
index 0000000..4a15527
--- /dev/null
+++ b/suites/upgrade/dumpling-firefly-x/parallel/README
@@ -0,0 +1,72 @@
+Purpose
+=======
+
+This suite tests upgrades of a ceph cluster from dumpling (current
+branch) to firefly (current branch), and then to a later specified
+version (version x, e.g. for example ‘next’ or ‘master’). It runs the
+last upgrade (steps in 3-firefly-upgrade) in parallel with firefly
+client tests.
+
+
+Structure
+=========
+
+Generally the flow is:
+- install dumpling
+- test it
+- upgrade cluster and clients to firefly
+- test firefly while upgrading cluster to version x
+- upgrade clients
+- test with version x clients
+
+0-cluster
+---------
+
+Defines the cluster layout - two nodes run ceph daemons, and a third
+acts as a client.
+
+1-dumpling-install
+------------------
+
+Installs dumpling and runs correctness tests from the 'workload' section
+
+2-workload
+----------
+
+Defines the 'workload' section - correctness tests to run on dumpling
+“+” is used to construct a single yaml load from all tests in this directory
+
+3-firefly-upgrade
+-----------------
+
+First upgrades everything to firefly. Then upgrades the cluster to
+version x while running correctness tests (from the 'workload2'
+section) on firefly clients in parallel. This upgrade is done by the
+'upgrade-sequence' section, defined later. Once the cluster is
+upgraded and these tests complete, upgrades the clients to version x
+as well.
+
+Clients are upgraded last to avoid running newer tests that don't work
+against firefly, and to verify that firefly clients can continue
+working with a newer cluster.
+
+4-workload
+----------
+
+Defines the 'workload2' section - correctness tests to run during the
+upgrade from firefly to version x.
+“+” is used to construct a single yaml load from all tests in this directory
+
+5-upgrade-sequence
+------------------
+
+Defines the 'upgrade-sequence' section - the order in which the
+upgrade from firefly to version x is done. Note that leaving the
+version unspecified here is what makes it upgrade to version x,
+which is set as an override when this suite is scheduled.
+
+6-final-workload
+----------------
+
+Runs some final correctness tests of version x clients.
+“+” is used to construct a single yaml load from all tests in this directory