adoroszlai commented on a change in pull request #2056:
URL: https://github.com/apache/ozone/pull/2056#discussion_r609472109
##########
File path: hadoop-ozone/dist/src/main/compose/upgrade/README.md
##########
@@ -12,18 +12,91 @@
limitations under the License. See accompanying LICENSE file.
-->
-# Compose file for upgrade
+# Ozone Upgrade Acceptance Tests
-This directory contains a sample cluster definition and script for
-testing upgrade from previous version to the current one.
+This directory contains cluster definitions and scripts for testing upgrades
from any previous version to another
+previous version, or to the local build of the code. It is designed to catch
backwards incompatible changes made between
+an older release of Ozone and a later release (which may be the local build).
-Data for each container is persisted in mounted volume (by default it's
-`data` under the `compose/upgrade` directory, but can be overridden via
-`OZONE_VOLUME` environment variable).
+## IMPORTANT NOTES
-Prior version is run using an official `apache/ozone` image, while the
-current version is run with the `ozone-runner` image using locally built
-source code.
+1. Backwards Incompatibility
+ - These tests will not catch backwards incompatible changes against
commits in between releases.
+ - Example:
+ 1. After 1.0.0, a change *c1* is made that is backwards compatible
with *1.0.0*.
+ 2. After *c1*, a new change *c2* is made that is also backwards
compatible with 1.0.0 but backwards *incompatible* with *c1*.
-Currently the test script only supports a single version upgrade (eg.
-from 0.5.0 to 1.0.0).
+ - This test suite will not raise an error for *c2*, because it
only tests against the last release
+ (1.0.0), and not the last commit (*c1*).
+
+2. Downgrade Support
+ - Downgrades will not be supported until upgrading from 1.1.0 to 1.2.0
+
+ - Until 1.1.0 is released, downgrades cannot be tested, so they are
commented out of the current non-rolling upgrade tests.
+
+## Directory Layout
+
+### upgrades
+
+Each type of upgrade has a subdirectory under the *upgrades* directory. Each
upgrade's steps are controlled by a *test.sh* script in its
*upgrades/\<upgrade-type>* directory. Callbacks to execute throughout the
upgrade are called by this script and should be placed in a file called
*callback.sh* in the *upgrades/\<upgrade-type>/\<upgrade-from>-\<upgrade-to>*
directory. After the test is run, results and docker volume data for the
upgrade for these versions will also be placed in this directory. The results
of all upgrades run as part of the tests will be placed in a *results* folder
in the top level upgrade directory.
+
+#### manual-upgrade
+
+- Any necessary conversion of on disk structures from the old version to the
new version must be done explicitly.
+
+- This is primarily for testing upgrades from versions before the non-rolling
upgrade framework was introduced.
+
+- Supported Callbacks:
+ 1. `setup_with_old_version`: Run before ozone is started in the old
version.
+ 3. `with_old_version`: Run while ozone is running in the old version.
+ 3. `setup_with_new_version`: Run after ozone is stopped in the old
version, but before it is restarted in the new version.
+ 4. `with_new_version`: Run while ozone is running in the new version.
+
+#### non-rolling-upgrade
+
+- Any necessary conversion of on disk structures from the old version to the
new version are handled by Ozone's non-rolling upgrade framework.
+
+- Supported Callbacks:
+ 1. `setup`: Run before ozone is started in the old version.
+ 3. `with_old_version`: Run while ozone is running in the old version.
+ 3. `with_new_version_pre_finalized`: Run after ozone is stopped in the old
version, and brought back up and running in the new version pre-finalized.
Review comment:
Thanks for the explanation. Then were good, the
`with_new_version_finalized` callback covers the case I had in mind.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
