You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ozone.apache.org by av...@apache.org on 2021/04/13 16:20:12 UTC
[ozone] branch HDDS-3698-nonrolling-upgrade updated: HDDS-5014.
Upgrade usage primer documentation. (#2133)
This is an automated email from the ASF dual-hosted git repository.
avijayan pushed a commit to branch HDDS-3698-nonrolling-upgrade
in repository https://gitbox.apache.org/repos/asf/ozone.git
The following commit(s) were added to refs/heads/HDDS-3698-nonrolling-upgrade by this push:
new 6e027a1 HDDS-5014. Upgrade usage primer documentation. (#2133)
6e027a1 is described below
commit 6e027a1befda1004f81ff1d169ec25f98bd452e0
Author: avijayanhwx <14...@users.noreply.github.com>
AuthorDate: Tue Apr 13 09:19:51 2021 -0700
HDDS-5014. Upgrade usage primer documentation. (#2133)
---
.../design/how-to-do-a-nonrolling-upgrade.md | 49 +++++++++++
hadoop-hdds/docs/content/design/omprepare.md | 15 +++-
.../docs/content/design/upgrade-dev-primer.md | 96 ++++++++++++++++++++++
3 files changed, 159 insertions(+), 1 deletion(-)
diff --git a/hadoop-hdds/docs/content/design/how-to-do-a-nonrolling-upgrade.md b/hadoop-hdds/docs/content/design/how-to-do-a-nonrolling-upgrade.md
new file mode 100644
index 0000000..ece4816
--- /dev/null
+++ b/hadoop-hdds/docs/content/design/how-to-do-a-nonrolling-upgrade.md
@@ -0,0 +1,49 @@
+---
+title: How to do a non-rolling upgrade of Ozone
+summary: Steps to do a non rolling upgrade of Ozone.
+date: 2021-02-15
+author: Aravindan Vijayan
+---
+<!--
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License. See accompanying LICENSE file.
+-->
+
+### Prepare the Ozone Manager.
+
+ ozone admin om -id=<om-sevice-id> prepare
+
+### Stop the components
+Stop all components (OMs, SCMs & DNs) using an appropriate 'stop' command.
+
+### Replace artifacts with newer version.
+Replace artifacts of all components newer version.
+
+### Start the components
+Start the SCM and DNs in a regular way.
+Start the Ozone Manager using the --upgrade flag.
+
+ ozone --deamon om start --upgrade
+
+### Finalize SCM and OM individually.
+
+ ozone admin scm finalizeupgrade
+
+ ozone admin om -id=<service-id> finalizeupgrade
+
+### Downgrade (instead of finalizing)
+ - Stop all components (OMs, SCMs & DNs) using an appropriate 'stop' command.
+ - Replace artifacts of all components newer version.
+ - Start the SCM and DNs in a regular way.
+ - Start the Ozone Manager using the '--downgrade' flag.
+
+
\ No newline at end of file
diff --git a/hadoop-hdds/docs/content/design/omprepare.md b/hadoop-hdds/docs/content/design/omprepare.md
index 194e2ba..79a1743 100644
--- a/hadoop-hdds/docs/content/design/omprepare.md
+++ b/hadoop-hdds/docs/content/design/omprepare.md
@@ -39,7 +39,20 @@ author: Aravindan Vijayan
* For an OM that is not operational during the prepare step, it should get a
Ratis snapshot (entire OM RocksDB) to get up to speed with the rest of the OMs after the upgrade.
-
+# Usage
+
+## How do you prepare an Ozone manager quorum
+ ozone admin om -id=<om-sevice-id> prepare
+
+This leaves the Ozone manager in a state where it cannot accept new writes.
+
+## How do you cancel a "prepared" Ozone manager quorum
+
+In the case of a cancelled upgrade, the OM can be brought out off the
+prepared state by using the following command.
+
+ ozone admin om -id=<om-sevice-id> cancelprepare
+
# Link
https://issues.apache.org/jira/secure/attachment/13015491/OM%20Prepare%20Upgrade.pdf
diff --git a/hadoop-hdds/docs/content/design/upgrade-dev-primer.md b/hadoop-hdds/docs/content/design/upgrade-dev-primer.md
new file mode 100644
index 0000000..de160ea
--- /dev/null
+++ b/hadoop-hdds/docs/content/design/upgrade-dev-primer.md
@@ -0,0 +1,96 @@
+---
+title: Upgrade - Developer Primer
+summary: Helpful resources for those who are bringing layout changes.
+date: 2021-02-15
+author: Aravindan Vijayan
+---
+<!--
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License. See accompanying LICENSE file.
+-->
+
+# Terminologies
+
+## Layout Feature
+A layout feature is any new Ozone feature that makes a backward incompatible change to the on disk layout. Each layout feature is associated with a layout version that it defines. A component has a list of monotonically increasing layout features (versions) that it supports.
+
+## Finalizing & Pre-Finalized State
+When upgrading a component from an older version to a newer version which has a higher layout version, the component automatically goes into a pre-finalized state after which an explicit ‘finalize’ action is required from the user to finalize it. In the pre-finalized state, commands/APIs/on disk structures used and created by newer layout features are meant to be unsupported or unused. After finalizing, the newer layout feature APIs are supported.
+
+## Downgrade
+Downgrade to a lower version is allowed from the pre-finalized state. This involves stopping the component, replacing the artifacts to the older version, and then starting it up again.
+
+# Useful framework tools to use
+
+## LayoutFeature
+ org.apache.hadoop.ozone.om.upgrade.OMLayoutFeature
+ org.apache.hadoop.hdds.upgrade.HDDSLayoutFeature
+Class to add a new layout feature being brought in. Layout version is typically 1 + last layout feature in that catalog.
+
+## LayoutVersionManager
+ org.apache.hadoop.ozone.om.upgrade.OMLayoutVersionManager
+ org.apache.hadoop.hdds.upgrade.HDDSLayoutVersionManager
+Every component carries an instance of this interface, which provides APIs to get runtime layout version, and if a feature is allowed based on that or not.
+
+## @DisallowedUntilLayoutVersion Annotation
+Method level annotation used to "disallow" an API if current layout version does not include the associated layout feature. Currently it is added only to the OM module, but can easily be moved down to a common module based on need on the HDDS layer.
+
+## @BelongsToLayoutVersion Annotation
+Annotation to mark an OM request class that it belongs to a specific Layout Version. Until that version is available post finalize, this request will not be supported. A newer version of an existing OM request can be created (by inheritance or a fully new class) and marked with a newer layout version. Until finalizing this layout version, the older request class is used. Post finalizing, the newer version of the request class is used.
+
+## LayoutVersionInstanceFactory<T>
+Generic factory which stores different instances of Type 'T' sharded by a key & version. A single key can be associated with different versions of 'T'.
+
+### Why does this class exist?
+A typical use case during upgrade is to have multiple versions of a class / method / object and choose them based on the current layout version at runtime. Before finalizing, an older version is typically needed, and after finalization, a newer version is needed. This class serves this purpose in a generic way. For example, we can create a Factory to create multiple versions of OMRequests sharded by Request Type & Layout Version Supported.
+
+## Upgrade Action (UpgradeActionOm & UpgradeActionHdds)
+Annotation to specify upgrade action run during specific upgrade phases. Each layout feature can optionally define an upgrade action for every supported phase. These are the supported phases of action callbacks.
+
+#### UNFINALIZED_STATE_VALIDATION
+A ‘validation’ action run every time a component is started up with this layout feature being unfinalized.
+
+#### ON_FIRST_UPGRADE_START
+A backward compatible action run exactly once when an upgraded cluster is detected with this new layout version.
+
+#### ON_FINALIZE
+An action run exactly once during finalization of layout version (feature).
+
+## ‘Prepare’ the Ozone Manager
+Used to flush all transactions to disk, take a DB snapshot, and purge the logs, leaving Ratis in a clean state without unapplied log entries. This prepares the OM for upgrades/downgrades so that no request in the log is applied to the database in the old version of the code in one OM, and the new version of the code in another OM.
+
+To prepare an OM quorum, run
+
+ ozone admin om -id=<om-sevice-id> prepare
+
+To cancel preparation of an OM quorum, run
+
+ ozone admin om -id=<om-sevice-id> cancelprepare
+
+
+## When do you bring in a change as a Layout feature?
+By using the new feature, if it creates a change in disk layout (RocksDB, HDDS Volume etc) that is incompatible with the older version, then that qualifies as a layout feature.
+
+#### What are some examples of changes that need not be layout features?
+- A feature that creates a table and writes into it. On downgrade, the table
+is no longer accessed (as expected), but does not interfere with the existing
+ functionality.
+- A change to an existing OM request that does not change on disk layout.
+
+## Testing layout feature onboarding
+- Ability to deploy Mini ozone cluster with any layout version
+ - org.apache.hadoop.ozone.MiniOzoneCluster.Builder#setScmLayoutVersion
+ - org.apache.hadoop.ozone.MiniOzoneCluster.Builder#setOmLayoutVersion
+ - org.apache.hadoop.ozone.MiniOzoneCluster.Builder#setDnLayoutVersion
+- Acceptance test framework provides callbacks at various upgrade stages
+ (older, pre-finalize, on downgrade, on finalize) to plug in data ingestion / verification logic.
+ - Please refer to hadoop-ozone/dist/src/main/compose/upgrade/README.md
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@ozone.apache.org
For additional commands, e-mail: commits-help@ozone.apache.org