src/main/asciidoc/_chapters/upgrading.adoc - hbase - Git at Google

 ////
 /**
  *
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
  * regarding copyright ownership.  The ASF licenses this file
  * to you 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.
  */
 ////

 [[upgrading]]
 = Upgrading
 :doctype: book
 :numbered:
 :toc: left
 :icons: font
 :experimental:

 You cannot skip major versions when upgrading. If you are upgrading from version 0.98.x to 2.x, you must first go from 0.98.x to 1.2.x and then go from 1.2.x to 2.x.

 Review <<configuration>>, in particular <<hadoop>>. Familiarize yourself with <<hbase_supported_tested_definitions>>.

 [[hbase.versioning]]
 == HBase version number and compatibility

 [[hbase.versioning.post10]]
 === Aspirational Semantic Versioning

 Starting with the 1.0.0 release, HBase is working towards link:http://semver.org/[Semantic Versioning] for its release versioning. In summary:

 .Given a version number MAJOR.MINOR.PATCH, increment the:
 * MAJOR version when you make incompatible API changes,
 * MINOR version when you add functionality in a backwards-compatible manner, and
 * PATCH version when you make backwards-compatible bug fixes.
 * Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

 [[hbase.versioning.compat]]
 .Compatibility Dimensions
 In addition to the usual API versioning considerations HBase has other compatibility dimensions that we need to consider.

 .Client-Server wire protocol compatibility
 * Allows updating client and server out of sync.
 * We could only allow upgrading the server first. I.e. the server would be backward compatible to an old client, that way new APIs are OK.
 * Example: A user should be able to use an old client to connect to an upgraded cluster.

 .Server-Server protocol compatibility
 * Servers of different versions can co-exist in the same cluster.
 * The wire protocol between servers is compatible.
 * Workers for distributed tasks, such as replication and log splitting, can co-exist in the same cluster.
 * Dependent protocols (such as using ZK for coordination) will also not be changed.
 * Example: A user can perform a rolling upgrade.

 .File format compatibility
 * Support file formats backward and forward compatible
 * Example: File, ZK encoding, directory layout is upgraded automatically as part of an HBase upgrade. User can rollback to the older version and everything will continue to work.

 .Client API compatibility
 * Allow changing or removing existing client APIs.
 * An API needs to be deprecated for a whole major version before we will change/remove it.
 ** An example: An API was deprecated in 2.0.1 and will be marked for deletion in 4.0.0. On the other hand, an API deprecated in 2.0.0 can be removed in 3.0.0.
 * APIs available in a patch version will be available in all later patch versions. However, new APIs may be added which will not be available in earlier patch versions.
 * Example: A user using a newly deprecated api does not need to modify application code with hbase api calls until the next major version.

 .Client Binary compatibility
 * Client code written to APIs available in a given patch release can run unchanged (no recompilation needed) against the new jars of later patch versions.
 * Client code written to APIs available in a given patch release might not run against the old jars from an earlier patch version.
 * Example: Old compiled client code will work unchanged with the new jars.

 .Server-Side Limited API compatibility (taken from Hadoop)
 * Internal APIs are marked as Stable, Evolving, or Unstable
 * This implies binary compatibility for coprocessors and plugins (pluggable classes, including replication) as long as these are only using marked interfaces/classes.
 * Example: Old compiled Coprocessor, Filter, or Plugin code will work unchanged with the new jars.

 .Dependency Compatibility
 * An upgrade of HBase will not require an incompatible upgrade of a dependent project, except for Apache Hadoop.
 * An upgrade of HBase will not require an incompatible upgrade of the Java runtime.
 * Example: Upgrading HBase to a version that supports _Dependency Compatibility_ won't require that you upgrade your Apache ZooKeeper service.
 * Example: If your current version of HBase supported running on JDK 8, then an upgrade to a version that supports _Dependency Compatibility_ will also run on JDK 8.

 .Hadoop Versions
 [TIP]
 ====
 Previously, we tried to maintain dependency compatibility for the underly Hadoop service but over the last few years this has proven untenable. While the HBase project attempts to maintain support for older versions of Hadoop, we drop the "supported" designator for minor versions that fail to continue to see releases. Additionally, the Hadoop project has its own set of compatibility guidelines, which means in some cases having to update to a newer supported minor release might break some of our compatibility promises.
 ====

 .Operational Compatibility
 * Metric changes
 * Behavioral changes of services
 * Web page APIs

 .Summary
 * A patch upgrade is a drop-in replacement. Any change that is not Java binary compatible would not be allowed.footnote:[See http://docs.oracle.com/javase/specs/jls/se7/html/jls-13.html.]. Downgrading versions within patch releases may not be compatible.

 * A minor upgrade requires no application/client code modification. Ideally it would be a drop-in replacement but client code, coprocessors, filters, etc might have to be recompiled if new jars are used.

 * A major upgrade allows the HBase community to make breaking changes.

 .Compatibility Matrix footnote:[Note that this indicates what could break, not that it will break. We will/should add specifics in our release notes.]
 [cols="1,1,1,1"]
 |===
 | | Major | Minor | Patch
 |Client-Server wire Compatibility|  N |Y |Y
 |Server-Server Compatibility |N |Y |Y
 |File Format Compatibility | N footnote:[comp_matrix_offline_upgrade_note,Running an offline upgrade tool without rollback might be needed. We will typically only support migrating data from major version X to major version X+1.] | Y |Y
 |Client API Compatibility  | N | Y |Y
 |Client Binary Compatibility | N | N |Y
 4+|Server-Side Limited API Compatibility
 >| Stable | N | Y | Y
 >| Evolving | N |N |Y
 >| Unstable | N |N |N
 |Dependency Compatibility | N |Y |Y
 |Operational Compatibility | N |N |Y
 |===

 [[hbase.client.api.surface]]
 ==== HBase API Surface

 HBase has a lot of API points, but for the compatibility matrix above, we differentiate between Client API, Limited Private API, and Private API. HBase uses a version of link:https://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-common/Compatibility.html[Hadoop's Interface classification]. HBase's Interface classification classes can be found link:https://hbase.apache.org/apidocs/org/apache/hadoop/hbase/classification/package-summary.html[here].

 * InterfaceAudience: captures the intended audience, possible values are Public (for end users and external projects), LimitedPrivate (for other Projects, Coprocessors or other plugin points), and Private (for internal use).
 * InterfaceStability: describes what types of interface changes are permitted. Possible values are Stable, Evolving, Unstable, and Deprecated.

 [[hbase.client.api]]
 HBase Client API::
   HBase Client API consists of all the classes or methods that are marked with InterfaceAudience.Public interface. All main classes in hbase-client and dependent modules have either InterfaceAudience.Public, InterfaceAudience.LimitedPrivate, or InterfaceAudience.Private marker. Not all classes in other modules (hbase-server, etc) have the marker. If a class is not annotated with one of these, it is assumed to be a InterfaceAudience.Private class.

 [[hbase.limitetprivate.api]]
 HBase LimitedPrivate API::
   LimitedPrivate annotation comes with a set of target consumers for the interfaces. Those consumers are coprocessors, phoenix, replication endpoint implemnetations or similar. At this point, HBase only guarantees source and binary compatibility for these interfaces between patch versions.

 [[hbase.private.api]]
 HBase Private API::
   All classes annotated with InterfaceAudience.Private or all classes that do not have the annotation are for HBase internal use only. The interfaces and method signatures can change at any point in time. If you are relying on a particular interface that is marked Private, you should open a jira to propose changing the interface to be Public or LimitedPrivate, or an interface exposed for this purpose.

 [[hbase.binary.compatibility]]
 .Binary Compatibility
 When we say two HBase versions are compatible, we mean that the versions are wire and binary compatible. Compatible HBase versions means that clients can talk to compatible but differently versioned servers. It means too that you can just swap out the jars of one version and replace them with the jars of another, compatible version and all will just work. Unless otherwise specified, HBase point versions are (mostly) binary compatible. You can safely do rolling upgrades between binary compatible versions; i.e. across maintenance releases: e.g. from 1.2.4 to 1.2.6. See link:[Does compatibility between versions also mean binary compatibility?] discussion on the HBase dev mailing list.

 [[hbase.rolling.upgrade]]
 === Rolling Upgrades

 A rolling upgrade is the process by which you update the servers in your cluster a server at a time. You can rolling upgrade across HBase versions if they are binary or wire compatible. See <<hbase.rolling.restart>> for more on what this means. Coarsely, a rolling upgrade is a graceful stop each server, update the software, and then restart. You do this for each server in the cluster. Usually you upgrade the Master first and then the RegionServers. See <<rolling>> for tools that can help use the rolling upgrade process.

 For example, in the below, HBase was symlinked to the actual HBase install. On upgrade, before running a rolling restart over the cluser, we changed the symlink to point at the new HBase software version and then ran

 [source,bash]
 ----
 $ HADOOP_HOME=~/hadoop-2.6.0-CRC-SNAPSHOT ~/hbase/bin/rolling-restart.sh --config ~/conf_hbase
 ----

 The rolling-restart script will first gracefully stop and restart the master, and then each of the RegionServers in turn. Because the symlink was changed, on restart the server will come up using the new HBase version. Check logs for errors as the rolling upgrade proceeds.

 [[hbase.rolling.restart]]
 .Rolling Upgrade Between Versions that are Binary/Wire Compatible
 Unless otherwise specified, HBase minor versions are binary compatible. You can do a <<hbase.rolling.upgrade>> between HBase point versions. For example, you can go to 1.2.4 from 1.2.6 by doing a rolling upgrade across the cluster replacing the 1.2.4 binary with a 1.2.6 binary.

 In the minor version-particular sections below, we call out where the versions are wire/protocol compatible and in this case, it is also possible to do a <<hbase.rolling.upgrade>>.

 == Upgrade Paths

 [[upgrade1.4]]
 === Upgrading to 1.4+

 ==== Replication peer's TableCFs config

 Before 1.4, the table name can't include namespace for replication peer's TableCFs config. It was fixed by add TableCFs to ReplicationPeerConfig which was stored on Zookeeper. So when upgrade to 1.4, you have to update the original ReplicationPeerConfig data on Zookeeper firstly. There are four steps to upgrade when your cluster have a replication peer with TableCFs config.

 * Disable the replication peer.
 * If master has permission to write replication peer znode, then rolling update master directly. If not, use TableCFsUpdater tool to update the replication peer's config.
 [source,bash]
 ----
 $ bin/hbase org.apache.hadoop.hbase.replication.master.TableCFsUpdater update
 ----
 * Rolling update regionservers.
 * Enable the replication peer.

 Notes:

 * Can't use the old client(before 1.4) to change the replication peer's config. Because the client will write config to Zookeeper directly, the old client will miss TableCFs config. And the old client write TableCFs config to the old tablecfs znode, it will not work for new version regionserver.

 [[upgrade1.0]]
 === Upgrading from 0.98.x to 1.x

 In this section we first note the significant changes that come in with 1.0.0+ HBase and then we go over the upgrade process. Be sure to read the significant changes section with care so you avoid surprises.

 ==== Changes of Note!

 In here we list important changes that are in 1.0.0+ since 0.98.x., changes you should be aware that will go into effect once you upgrade.

 [[zookeeper.3.4]]
 .ZooKeeper 3.4 is required in HBase 1.0.0+
 See <<zookeeper.requirements>>.

 [[default.ports.changed]]
 .HBase Default Ports Changed
 The ports used by HBase changed. They used to be in the 600XX range. In HBase 1.0.0 they have been moved up out of the ephemeral port range and are 160XX instead (Master web UI was 60010 and is now 16010; the RegionServer web UI was 60030 and is now 16030, etc.). If you want to keep the old port locations, copy the port setting configs from _hbase-default.xml_ into _hbase-site.xml_, change them back to the old values from the HBase 0.98.x era, and ensure you've distributed your configurations before you restart.

 [[upgrade1.0.hbase.bucketcache.percentage.in.combinedcache]]
 .hbase.bucketcache.percentage.in.combinedcache configuration has been REMOVED
 You may have made use of this configuration if you are using BucketCache. If NOT using BucketCache, this change does not effect you. Its removal means that your L1 LruBlockCache is now sized using `hfile.block.cache.size` -- i.e. the way you would size the on-heap L1 LruBlockCache if you were NOT doing BucketCache -- and the BucketCache size is not whatever the setting for `hbase.bucketcache.size` is. You may need to adjust configs to get the LruBlockCache and BucketCache sizes set to what they were in 0.98.x and previous. If you did not set this config., its default value was 0.9. If you do nothing, your BucketCache will increase in size by 10%. Your L1 LruBlockCache will become `hfile.block.cache.size` times your java heap size (`hfile.block.cache.size` is a float between 0.0 and 1.0). To read more, see link:https://issues.apache.org/jira/browse/HBASE-11520[HBASE-11520 Simplify offheap cache config by removing the confusing "hbase.bucketcache.percentage.in.combinedcache"].

 [[hbase-12068]]
 .If you have your own customer filters.
 See the release notes on the issue link:https://issues.apache.org/jira/browse/HBASE-12068[HBASE-12068 [Branch-1\] Avoid need to always do KeyValueUtil#ensureKeyValue for Filter transformCell]; be sure to follow the recommendations therein.

 [[dlr]]
 .Distributed Log Replay
 <<distributed.log.replay>> is off by default in HBase 1.0.0. Enabling it can make a big difference improving HBase MTTR. Enable this feature if you are doing a clean stop/start when you are upgrading. You cannot rolling upgrade to this feature (caveat if you are running on a version of HBase in excess of HBase 0.98.4 -- see link:https://issues.apache.org/jira/browse/HBASE-12577[HBASE-12577 Disable distributed log replay by default] for more).

 .Availability of Date Tiered Compaction.
 The Date Tiered Compaction feature available as of 0.98.19 is available in the 1.y release line starting in release 1.3.0. If you have enabled this feature for any tables you must upgrade to version 1.3.0 or later. If you attempt to use an earlier 1.y release, any tables configured to use date tiered compaction will fail to have their regions open.

 [[upgrade1.0.rolling.upgrade]]
 ==== Rolling upgrade from 0.98.x to HBase 1.0.0

 There are no known issues running a <<hbase.rolling.upgrade,rolling upgrade>> from HBase 0.98.x to HBase 1.0.0.

 [[upgrade2.0]]
 === Upgrading to 2.x

 Please see the reference guide for the latest 2.x release for guidance on upgrading.
	////
	/**
	*
	* Licensed to the Apache Software Foundation (ASF) under one
	* or more contributor license agreements. See the NOTICE file
	* distributed with this work for additional information
	* regarding copyright ownership. The ASF licenses this file
	* to you 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.
	*/
	////

	[[upgrading]]
	= Upgrading
	:doctype: book
	:numbered:
	:toc: left
	:icons: font
	:experimental:

	You cannot skip major versions when upgrading. If you are upgrading from version 0.98.x to 2.x, you must first go from 0.98.x to 1.2.x and then go from 1.2.x to 2.x.

	Review <<configuration>>, in particular <<hadoop>>. Familiarize yourself with <<hbase_supported_tested_definitions>>.

	[[hbase.versioning]]
	== HBase version number and compatibility

	[[hbase.versioning.post10]]
	=== Aspirational Semantic Versioning

	Starting with the 1.0.0 release, HBase is working towards link:http://semver.org/[Semantic Versioning] for its release versioning. In summary:

	.Given a version number MAJOR.MINOR.PATCH, increment the:
	* MAJOR version when you make incompatible API changes,
	* MINOR version when you add functionality in a backwards-compatible manner, and
	* PATCH version when you make backwards-compatible bug fixes.
	* Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

	[[hbase.versioning.compat]]
	.Compatibility Dimensions
	In addition to the usual API versioning considerations HBase has other compatibility dimensions that we need to consider.

	.Client-Server wire protocol compatibility
	* Allows updating client and server out of sync.
	* We could only allow upgrading the server first. I.e. the server would be backward compatible to an old client, that way new APIs are OK.
	* Example: A user should be able to use an old client to connect to an upgraded cluster.

	.Server-Server protocol compatibility
	* Servers of different versions can co-exist in the same cluster.
	* The wire protocol between servers is compatible.
	* Workers for distributed tasks, such as replication and log splitting, can co-exist in the same cluster.
	* Dependent protocols (such as using ZK for coordination) will also not be changed.
	* Example: A user can perform a rolling upgrade.

	.File format compatibility
	* Support file formats backward and forward compatible
	* Example: File, ZK encoding, directory layout is upgraded automatically as part of an HBase upgrade. User can rollback to the older version and everything will continue to work.

	.Client API compatibility
	* Allow changing or removing existing client APIs.
	* An API needs to be deprecated for a whole major version before we will change/remove it.
	** An example: An API was deprecated in 2.0.1 and will be marked for deletion in 4.0.0. On the other hand, an API deprecated in 2.0.0 can be removed in 3.0.0.
	* APIs available in a patch version will be available in all later patch versions. However, new APIs may be added which will not be available in earlier patch versions.
	* Example: A user using a newly deprecated api does not need to modify application code with hbase api calls until the next major version.

	.Client Binary compatibility
	* Client code written to APIs available in a given patch release can run unchanged (no recompilation needed) against the new jars of later patch versions.
	* Client code written to APIs available in a given patch release might not run against the old jars from an earlier patch version.
	* Example: Old compiled client code will work unchanged with the new jars.

	.Server-Side Limited API compatibility (taken from Hadoop)
	* Internal APIs are marked as Stable, Evolving, or Unstable
	* This implies binary compatibility for coprocessors and plugins (pluggable classes, including replication) as long as these are only using marked interfaces/classes.
	* Example: Old compiled Coprocessor, Filter, or Plugin code will work unchanged with the new jars.

	.Dependency Compatibility
	* An upgrade of HBase will not require an incompatible upgrade of a dependent project, except for Apache Hadoop.
	* An upgrade of HBase will not require an incompatible upgrade of the Java runtime.
	* Example: Upgrading HBase to a version that supports _Dependency Compatibility_ won't require that you upgrade your Apache ZooKeeper service.
	* Example: If your current version of HBase supported running on JDK 8, then an upgrade to a version that supports _Dependency Compatibility_ will also run on JDK 8.

	.Hadoop Versions
	[TIP]
	====
	Previously, we tried to maintain dependency compatibility for the underly Hadoop service but over the last few years this has proven untenable. While the HBase project attempts to maintain support for older versions of Hadoop, we drop the "supported" designator for minor versions that fail to continue to see releases. Additionally, the Hadoop project has its own set of compatibility guidelines, which means in some cases having to update to a newer supported minor release might break some of our compatibility promises.
	====

	.Operational Compatibility
	* Metric changes
	* Behavioral changes of services
	* Web page APIs

	.Summary
	* A patch upgrade is a drop-in replacement. Any change that is not Java binary compatible would not be allowed.footnote:[See http://docs.oracle.com/javase/specs/jls/se7/html/jls-13.html.]. Downgrading versions within patch releases may not be compatible.

	* A minor upgrade requires no application/client code modification. Ideally it would be a drop-in replacement but client code, coprocessors, filters, etc might have to be recompiled if new jars are used.

	* A major upgrade allows the HBase community to make breaking changes.

	.Compatibility Matrix footnote:[Note that this indicates what could break, not that it will break. We will/should add specifics in our release notes.]
	[cols="1,1,1,1"]
	\|===
	\| \| Major \| Minor \| Patch
	\|Client-Server wire Compatibility\| N \|Y \|Y
	\|Server-Server Compatibility \|N \|Y \|Y
	\|File Format Compatibility \| N footnote:[comp_matrix_offline_upgrade_note,Running an offline upgrade tool without rollback might be needed. We will typically only support migrating data from major version X to major version X+1.] \| Y \|Y
	\|Client API Compatibility \| N \| Y \|Y
	\|Client Binary Compatibility \| N \| N \|Y
	4+\|Server-Side Limited API Compatibility
	>\| Stable \| N \| Y \| Y
	>\| Evolving \| N \|N \|Y
	>\| Unstable \| N \|N \|N
	\|Dependency Compatibility \| N \|Y \|Y
	\|Operational Compatibility \| N \|N \|Y
	\|===

	[[hbase.client.api.surface]]
	==== HBase API Surface

	HBase has a lot of API points, but for the compatibility matrix above, we differentiate between Client API, Limited Private API, and Private API. HBase uses a version of link:https://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-common/Compatibility.html[Hadoop's Interface classification]. HBase's Interface classification classes can be found link:https://hbase.apache.org/apidocs/org/apache/hadoop/hbase/classification/package-summary.html[here].

	* InterfaceAudience: captures the intended audience, possible values are Public (for end users and external projects), LimitedPrivate (for other Projects, Coprocessors or other plugin points), and Private (for internal use).
	* InterfaceStability: describes what types of interface changes are permitted. Possible values are Stable, Evolving, Unstable, and Deprecated.

	[[hbase.client.api]]
	HBase Client API::
	HBase Client API consists of all the classes or methods that are marked with InterfaceAudience.Public interface. All main classes in hbase-client and dependent modules have either InterfaceAudience.Public, InterfaceAudience.LimitedPrivate, or InterfaceAudience.Private marker. Not all classes in other modules (hbase-server, etc) have the marker. If a class is not annotated with one of these, it is assumed to be a InterfaceAudience.Private class.

	[[hbase.limitetprivate.api]]
	HBase LimitedPrivate API::
	LimitedPrivate annotation comes with a set of target consumers for the interfaces. Those consumers are coprocessors, phoenix, replication endpoint implemnetations or similar. At this point, HBase only guarantees source and binary compatibility for these interfaces between patch versions.

	[[hbase.private.api]]
	HBase Private API::
	All classes annotated with InterfaceAudience.Private or all classes that do not have the annotation are for HBase internal use only. The interfaces and method signatures can change at any point in time. If you are relying on a particular interface that is marked Private, you should open a jira to propose changing the interface to be Public or LimitedPrivate, or an interface exposed for this purpose.

	[[hbase.binary.compatibility]]
	.Binary Compatibility
	When we say two HBase versions are compatible, we mean that the versions are wire and binary compatible. Compatible HBase versions means that clients can talk to compatible but differently versioned servers. It means too that you can just swap out the jars of one version and replace them with the jars of another, compatible version and all will just work. Unless otherwise specified, HBase point versions are (mostly) binary compatible. You can safely do rolling upgrades between binary compatible versions; i.e. across maintenance releases: e.g. from 1.2.4 to 1.2.6. See link:[Does compatibility between versions also mean binary compatibility?] discussion on the HBase dev mailing list.

	[[hbase.rolling.upgrade]]
	=== Rolling Upgrades

	A rolling upgrade is the process by which you update the servers in your cluster a server at a time. You can rolling upgrade across HBase versions if they are binary or wire compatible. See <<hbase.rolling.restart>> for more on what this means. Coarsely, a rolling upgrade is a graceful stop each server, update the software, and then restart. You do this for each server in the cluster. Usually you upgrade the Master first and then the RegionServers. See <<rolling>> for tools that can help use the rolling upgrade process.

	For example, in the below, HBase was symlinked to the actual HBase install. On upgrade, before running a rolling restart over the cluser, we changed the symlink to point at the new HBase software version and then ran

	[source,bash]
	----
	$ HADOOP_HOME=~/hadoop-2.6.0-CRC-SNAPSHOT ~/hbase/bin/rolling-restart.sh --config ~/conf_hbase
	----

	The rolling-restart script will first gracefully stop and restart the master, and then each of the RegionServers in turn. Because the symlink was changed, on restart the server will come up using the new HBase version. Check logs for errors as the rolling upgrade proceeds.

	[[hbase.rolling.restart]]
	.Rolling Upgrade Between Versions that are Binary/Wire Compatible
	Unless otherwise specified, HBase minor versions are binary compatible. You can do a <<hbase.rolling.upgrade>> between HBase point versions. For example, you can go to 1.2.4 from 1.2.6 by doing a rolling upgrade across the cluster replacing the 1.2.4 binary with a 1.2.6 binary.

	In the minor version-particular sections below, we call out where the versions are wire/protocol compatible and in this case, it is also possible to do a <<hbase.rolling.upgrade>>.

	== Upgrade Paths

	[[upgrade1.4]]
	=== Upgrading to 1.4+

	==== Replication peer's TableCFs config

	Before 1.4, the table name can't include namespace for replication peer's TableCFs config. It was fixed by add TableCFs to ReplicationPeerConfig which was stored on Zookeeper. So when upgrade to 1.4, you have to update the original ReplicationPeerConfig data on Zookeeper firstly. There are four steps to upgrade when your cluster have a replication peer with TableCFs config.

	* Disable the replication peer.
	* If master has permission to write replication peer znode, then rolling update master directly. If not, use TableCFsUpdater tool to update the replication peer's config.
	[source,bash]
	----
	$ bin/hbase org.apache.hadoop.hbase.replication.master.TableCFsUpdater update
	----
	* Rolling update regionservers.
	* Enable the replication peer.

	Notes:

	* Can't use the old client(before 1.4) to change the replication peer's config. Because the client will write config to Zookeeper directly, the old client will miss TableCFs config. And the old client write TableCFs config to the old tablecfs znode, it will not work for new version regionserver.

	[[upgrade1.0]]
	=== Upgrading from 0.98.x to 1.x

	In this section we first note the significant changes that come in with 1.0.0+ HBase and then we go over the upgrade process. Be sure to read the significant changes section with care so you avoid surprises.

	==== Changes of Note!

	In here we list important changes that are in 1.0.0+ since 0.98.x., changes you should be aware that will go into effect once you upgrade.

	[[zookeeper.3.4]]
	.ZooKeeper 3.4 is required in HBase 1.0.0+
	See <<zookeeper.requirements>>.

	[[default.ports.changed]]
	.HBase Default Ports Changed
	The ports used by HBase changed. They used to be in the 600XX range. In HBase 1.0.0 they have been moved up out of the ephemeral port range and are 160XX instead (Master web UI was 60010 and is now 16010; the RegionServer web UI was 60030 and is now 16030, etc.). If you want to keep the old port locations, copy the port setting configs from _hbase-default.xml_ into _hbase-site.xml_, change them back to the old values from the HBase 0.98.x era, and ensure you've distributed your configurations before you restart.

	[[upgrade1.0.hbase.bucketcache.percentage.in.combinedcache]]
	.hbase.bucketcache.percentage.in.combinedcache configuration has been REMOVED
	You may have made use of this configuration if you are using BucketCache. If NOT using BucketCache, this change does not effect you. Its removal means that your L1 LruBlockCache is now sized using `hfile.block.cache.size` -- i.e. the way you would size the on-heap L1 LruBlockCache if you were NOT doing BucketCache -- and the BucketCache size is not whatever the setting for `hbase.bucketcache.size` is. You may need to adjust configs to get the LruBlockCache and BucketCache sizes set to what they were in 0.98.x and previous. If you did not set this config., its default value was 0.9. If you do nothing, your BucketCache will increase in size by 10%. Your L1 LruBlockCache will become `hfile.block.cache.size` times your java heap size (`hfile.block.cache.size` is a float between 0.0 and 1.0). To read more, see link:https://issues.apache.org/jira/browse/HBASE-11520[HBASE-11520 Simplify offheap cache config by removing the confusing "hbase.bucketcache.percentage.in.combinedcache"].

	[[hbase-12068]]
	.If you have your own customer filters.
	See the release notes on the issue link:https://issues.apache.org/jira/browse/HBASE-12068[HBASE-12068 [Branch-1\] Avoid need to always do KeyValueUtil#ensureKeyValue for Filter transformCell]; be sure to follow the recommendations therein.

	[[dlr]]
	.Distributed Log Replay
	<<distributed.log.replay>> is off by default in HBase 1.0.0. Enabling it can make a big difference improving HBase MTTR. Enable this feature if you are doing a clean stop/start when you are upgrading. You cannot rolling upgrade to this feature (caveat if you are running on a version of HBase in excess of HBase 0.98.4 -- see link:https://issues.apache.org/jira/browse/HBASE-12577[HBASE-12577 Disable distributed log replay by default] for more).

	.Availability of Date Tiered Compaction.
	The Date Tiered Compaction feature available as of 0.98.19 is available in the 1.y release line starting in release 1.3.0. If you have enabled this feature for any tables you must upgrade to version 1.3.0 or later. If you attempt to use an earlier 1.y release, any tables configured to use date tiered compaction will fail to have their regions open.

	[[upgrade1.0.rolling.upgrade]]
	==== Rolling upgrade from 0.98.x to HBase 1.0.0

	There are no known issues running a <<hbase.rolling.upgrade,rolling upgrade>> from HBase 0.98.x to HBase 1.0.0.

	[[upgrade2.0]]
	=== Upgrading to 2.x

	Please see the reference guide for the latest 2.x release for guidance on upgrading.