src/docbkx/upgrading.xml - hbase - Git at Google

 <?xml version="1.0"?>
     <chapter xml:id="upgrading"
       version="5.0" xmlns="http://docbook.org/ns/docbook"
       xmlns:xlink="http://www.w3.org/1999/xlink"
       xmlns:xi="http://www.w3.org/2001/XInclude"
       xmlns:svg="http://www.w3.org/2000/svg"
       xmlns:m="http://www.w3.org/1998/Math/MathML"
       xmlns:html="http://www.w3.org/1999/xhtml"
       xmlns:db="http://docbook.org/ns/docbook">
 <!--
 /**
  * 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.
  */
 -->
     <title>Upgrading</title>
     <para>
         Review <xref linkend="configuration" />, in particular the section on Hadoop version.
     </para>
     <section xml:id="upgrade0.90">
     <title>Upgrading to HBase 0.90.x from 0.20.x or 0.89.x</title>
           <para>This version of 0.90.x HBase can be started on data written by
               HBase 0.20.x or HBase 0.89.x.  There is no need of a migration step.
               HBase 0.89.x and 0.90.x does write out the name of region directories
               differently -- it names them with a md5 hash of the region name rather
               than a jenkins hash -- so this means that once started, there is no
               going back to HBase 0.20.x.
           </para>
           <para>
              Be sure to remove the <filename>hbase-default.xml</filename> from
              your <filename>conf</filename>
              directory on upgrade.  A 0.20.x version of this file will have
              sub-optimal configurations for 0.90.x HBase.  The
              <filename>hbase-default.xml</filename> file is now bundled into the
              HBase jar and read from there.  If you would like to review
              the content of this file, see it in the src tree at
              <filename>src/main/resources/hbase-default.xml</filename> or
              see <xref linkend="hbase_default_configurations" />.
           </para>
           <para>
             Finally, if upgrading from 0.20.x, check your
             <varname>.META.</varname> schema in the shell.  In the past we would
             recommend that users run with a 16kb
             <varname>MEMSTORE_FLUSHSIZE</varname>.
             Run <code>hbase> scan '-ROOT-'</code> in the shell. This will output
             the current <varname>.META.</varname> schema.  Check
             <varname>MEMSTORE_FLUSHSIZE</varname> size.  Is it 16kb (16384)?  If so, you will
             need to change this (The 'normal'/default value is 64MB (67108864)).
             Run the script <filename>bin/set_meta_memstore_size.rb</filename>.
             This will make the necessary edit to your <varname>.META.</varname> schema.
             Failure to run this change will make for a slow cluster <footnote>
             <para>
             See <link xlink:href="https://issues.apache.org/jira/browse/HBASE-3499">HBASE-3499 Users upgrading to 0.90.0 need to have their .META. table updated with the right MEMSTORE_SIZE</link>
             </para>
             </footnote>
             .

           </para>
           </section>
     <section xml:id="upgrade0.92">
       <title>Upgrading from 0.90.x to 0.92.x</title>
       <subtitle>Upgrade Guide</subtitle>
 <para>You will find that 0.92.0 runs a little differently to 0.90.x releases.  Here are a few things to watch out for upgrading from 0.90.x to 0.92.0.
 <note><title>tl;dr</title>
 <para>
 If you've not patience, here are the important things to know upgrading.
 <orderedlist>
 <listitem>Once you upgrade, you can’t go back.
 </listitem>
 <listitem>
 MSLAB is on by default. Watch that heap usage if you have a lot of regions.
 </listitem>
 <listitem>
 Distributed splitting is on by defaul.  It should make region server failover faster.
 </listitem>
 <listitem>
 There’s a separate tarball for security.
 </listitem>
 <listitem>
 If -XX:MaxDirectMemorySize is set in your hbase-env.sh, it’s going to enable the experimental off-heap cache (You may not want this).
 </listitem>
 </orderedlist>
 </para>
 </note>
 </para>

 <section>
 <title>You can’t go back!
 </title>
 <para>To move to 0.92.0, all you need to do is shutdown your cluster, replace your hbase 0.90.x with hbase 0.92.0 binaries (be sure you clear out all 0.90.x instances) and restart (You cannot do a rolling restart from 0.90.x to 0.92.x -- you must restart).
 On startup, the <varname>.META.</varname> table content is rewritten removing the table schema from the <varname>info:regioninfo</varname> column.
 Also, any flushes done post first startup will write out data in the new 0.92.0 file format, <link xlink:href="http://hbase.apache.org/book.html#hfilev2">HFile V2</link>.
 This means you cannot go back to 0.90.x once you’ve started HBase 0.92.0 over your HBase data directory.
 </para>
 </section>

 <section>
 <title>MSLAB is ON by default
 </title>
 <para>In 0.92.0, the <link xlink:href="http://hbase.apache.org/book.html#hbase.hregion.memstore.mslab.enabled">hbase.hregion.memstore.mslab.enabled</link> flag is set to true
 (See <xref linkend="mslab" />).  In 0.90.x it was <constant>false</constant>.  When it is enabled, memstores will step allocate memory in MSLAB 2MB chunks even if the
 memstore has zero or just a few small elements.  This is fine usually but if you had lots of regions per regionserver in a 0.90.x cluster (and MSLAB was off),
 you may find yourself OOME'ing on upgrade because the <mathphrase>thousands of regions * number of column families * 2MB MSLAB (at a minimum)</mathphrase>
 puts your heap over the top.  Set <varname>hbase.hregion.memstore.mslab.enabled</varname> to
 <constant>false</constant> or set the MSLAB size down from 2MB by setting <varname>hbase.hregion.memstore.mslab.chunksize</varname> to something less.
 </para>
 </section>

 <section><title>Distributed splitting is on by default
 </title>
 <para>Previous, WAL logs on crash were split by the Master alone.  In 0.92.0, log splitting is done by the cluster (See See “HBASE-1364 [performance] Distributed splitting of regionserver commit logs”).  This should cut down significantly on the amount of time it takes splitting logs and getting regions back online again.
 </para>
 </section>

 <section><title>Memory accounting is different now
 </title>
 <para>In 0.92.0, <xref linkend="hfilev2" /> indices and bloom filters take up residence in the same LRU used caching blocks that come from the filesystem.
 In 0.90.x, the HFile v1 indices lived outside of the LRU so they took up space even if the index was on a ‘cold’ file, one that wasn’t being actively used.  With the indices now in the LRU, you may find you
 have less space for block caching.  Adjust your block cache accordingly.  See the <xref linkend="block.cache" /> for more detail.
 The block size default size has been changed in 0.92.0 from 0.2 (20 percent of heap) to 0.25.
 </para>
 </section>


 <section><title>On the Hadoop version to use
 </title>
 <para>Run 0.92.0 on Hadoop 1.0.x (or CDH3u3 when it ships).  The performance benefits are worth making the move.  Otherwise, our Hadoop prescription is as it has been; you need an Hadoop that supports a working sync.  See <xref linkend="hadoop" />.
 </para>

 <para>If running on Hadoop 1.0.x (or CDH3u3), enable local read.  See <link xlink:href="http://files.meetup.com/1350427/hug_ebay_jdcryans.pdf">Practical Caching</link> presentation for ruminations on the performance benefits ‘going local’ (and for how to enable local reads).
 </para>
 </section>
 <section><title>HBase 0.92.0 ships with ZooKeeper 3.4.2
 </title>
 <para>If you can, upgrade your zookeeper.  If you can’t, 3.4.2 clients should work against 3.3.X ensembles (HBase makes use of 3.4.2 API).
 </para>
 </section>
 <section>
 <title>Online alter is off by default
 </title>
 <para>In 0.92.0, we’ve added an experimental online schema alter facility  (See <xref linkend="hbase.online.schema.update.enable" />).  Its off by default.  Enable it at your own risk.  Online alter and splitting tables do not play well together so be sure your cluster quiescent using this feature (for now).
 </para>
 </section>
 <section>
 <title>WebUI
 </title>
 <para>The webui has had a few additions made in 0.92.0.  It now shows a list of the regions currently transitioning, recent compactions/flushes, and a process list of running processes (usually empty if all is well and requests are being handled promptly).  Other additions including requests by region, a debugging servlet dump, etc.
 </para>
 </section>
 <section>
 <title>Security tarball
 </title>
 <para>We now ship with two tarballs; secure and insecure HBase.  Documentation on how to setup a secure HBase is on the way.
 </para>
 </section>

 <section><title>Experimental off-heap cache
 </title>
 <para>
 A new cache was contributed to 0.92.0 to act as a solution between using the “on-heap” cache which is the current LRU cache the region servers have and the operating system cache which is out of our control.
 To enable, set “-XX:MaxDirectMemorySize” in hbase-env.sh to the value for maximum direct memory size and specify hbase.offheapcache.percentage in hbase-site.xml with the percentage that you want to dedicate to off-heap cache. This should only be set for servers and not for clients. Use at your own risk.
 See this blog post for additional information on this new experimental feature: http://www.cloudera.com/blog/2012/01/caching-in-hbase-slabcache/
 </para>
 </section>

 <section><title>Changes in HBase replication
 </title>
 <para>0.92.0 adds two new features: multi-slave and multi-master replication. The way to enable this is the same as adding a new peer, so in order to have multi-master you would just run add_peer for each cluster that acts as a master to the other slave clusters. Collisions are handled at the timestamp level which may or may not be what you want, this needs to be evaluated on a per use case basis. Replication is still experimental in 0.92 and is disabled by default, run it at your own risk.
 </para>
 </section>


 <section><title>RegionServer now aborts if OOME
 </title>
 <para>If an OOME, we now have the JVM kill -9 the regionserver process so it goes down fast.  Previous, a RegionServer might stick around after incurring an OOME limping along in some wounded state.  To disable this facility, and recommend you leave it in place, you’d need to edit the bin/hbase file.  Look for the addition of the -XX:OnOutOfMemoryError="kill -9 %p" arguments (See [HBASE-4769] - ‘Abort RegionServer Immediately on OOME’)
 </para>
 </section>


 <section><title>HFile V2 and the “Bigger, Fewer” Tendency
 </title>
 <para>0.92.0 stores data in a new format, <xref linkend="hfilev2" />.   As HBase runs, it will move all your data from HFile v1 to HFile v2 format.  This auto-migration will run in the background as flushes and compactions run.
 HFile V2 allows HBase run with larger regions/files.  In fact, we encourage that all HBasers going forward tend toward Facebook axiom #1, run with larger, fewer regions.
 If you have lots of regions now -- more than 100s per host -- you should look into setting your region size up after you move to 0.92.0 (In 0.92.0, default size is not 1G, up from 256M), and then running online merge tool (See “HBASE-1621 merge tool should work on online cluster, but disabled table”).
 </para>
 </section>
     </section>
     </chapter>
	<?xml version="1.0"?>
	<chapter xml:id="upgrading"
	version="5.0" xmlns="http://docbook.org/ns/docbook"
	xmlns:xlink="http://www.w3.org/1999/xlink"
	xmlns:xi="http://www.w3.org/2001/XInclude"
	xmlns:svg="http://www.w3.org/2000/svg"
	xmlns:m="http://www.w3.org/1998/Math/MathML"
	xmlns:html="http://www.w3.org/1999/xhtml"
	xmlns:db="http://docbook.org/ns/docbook">
	<!--
	/**
	* 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.
	*/
	-->
	<title>Upgrading</title>
	<para>
	Review <xref linkend="configuration" />, in particular the section on Hadoop version.
	</para>
	<section xml:id="upgrade0.90">
	<title>Upgrading to HBase 0.90.x from 0.20.x or 0.89.x</title>
	<para>This version of 0.90.x HBase can be started on data written by
	HBase 0.20.x or HBase 0.89.x. There is no need of a migration step.
	HBase 0.89.x and 0.90.x does write out the name of region directories
	differently -- it names them with a md5 hash of the region name rather
	than a jenkins hash -- so this means that once started, there is no
	going back to HBase 0.20.x.
	</para>
	<para>
	Be sure to remove the <filename>hbase-default.xml</filename> from
	your <filename>conf</filename>
	directory on upgrade. A 0.20.x version of this file will have
	sub-optimal configurations for 0.90.x HBase. The
	<filename>hbase-default.xml</filename> file is now bundled into the
	HBase jar and read from there. If you would like to review
	the content of this file, see it in the src tree at
	<filename>src/main/resources/hbase-default.xml</filename> or
	see <xref linkend="hbase_default_configurations" />.
	</para>
	<para>
	Finally, if upgrading from 0.20.x, check your
	<varname>.META.</varname> schema in the shell. In the past we would
	recommend that users run with a 16kb
	<varname>MEMSTORE_FLUSHSIZE</varname>.
	Run <code>hbase> scan '-ROOT-'</code> in the shell. This will output
	the current <varname>.META.</varname> schema. Check
	<varname>MEMSTORE_FLUSHSIZE</varname> size. Is it 16kb (16384)? If so, you will
	need to change this (The 'normal'/default value is 64MB (67108864)).
	Run the script <filename>bin/set_meta_memstore_size.rb</filename>.
	This will make the necessary edit to your <varname>.META.</varname> schema.
	Failure to run this change will make for a slow cluster <footnote>
	<para>
	See <link xlink:href="https://issues.apache.org/jira/browse/HBASE-3499">HBASE-3499 Users upgrading to 0.90.0 need to have their .META. table updated with the right MEMSTORE_SIZE</link>
	</para>
	</footnote>
	.

	</para>
	</section>
	<section xml:id="upgrade0.92">
	<title>Upgrading from 0.90.x to 0.92.x</title>
	<subtitle>Upgrade Guide</subtitle>
	<para>You will find that 0.92.0 runs a little differently to 0.90.x releases. Here are a few things to watch out for upgrading from 0.90.x to 0.92.0.
	<note><title>tl;dr</title>
	<para>
	If you've not patience, here are the important things to know upgrading.
	<orderedlist>
	<listitem>Once you upgrade, you can’t go back.
	</listitem>
	<listitem>
	MSLAB is on by default. Watch that heap usage if you have a lot of regions.
	</listitem>
	<listitem>
	Distributed splitting is on by defaul. It should make region server failover faster.
	</listitem>
	<listitem>
	There’s a separate tarball for security.
	</listitem>
	<listitem>
	If -XX:MaxDirectMemorySize is set in your hbase-env.sh, it’s going to enable the experimental off-heap cache (You may not want this).
	</listitem>
	</orderedlist>
	</para>
	</note>
	</para>

	<section>
	<title>You can’t go back!
	</title>
	<para>To move to 0.92.0, all you need to do is shutdown your cluster, replace your hbase 0.90.x with hbase 0.92.0 binaries (be sure you clear out all 0.90.x instances) and restart (You cannot do a rolling restart from 0.90.x to 0.92.x -- you must restart).
	On startup, the <varname>.META.</varname> table content is rewritten removing the table schema from the <varname>info:regioninfo</varname> column.
	Also, any flushes done post first startup will write out data in the new 0.92.0 file format, <link xlink:href="http://hbase.apache.org/book.html#hfilev2">HFile V2</link>.
	This means you cannot go back to 0.90.x once you’ve started HBase 0.92.0 over your HBase data directory.
	</para>
	</section>

	<section>
	<title>MSLAB is ON by default
	</title>
	<para>In 0.92.0, the <link xlink:href="http://hbase.apache.org/book.html#hbase.hregion.memstore.mslab.enabled">hbase.hregion.memstore.mslab.enabled</link> flag is set to true
	(See <xref linkend="mslab" />). In 0.90.x it was <constant>false</constant>. When it is enabled, memstores will step allocate memory in MSLAB 2MB chunks even if the
	memstore has zero or just a few small elements. This is fine usually but if you had lots of regions per regionserver in a 0.90.x cluster (and MSLAB was off),
	you may find yourself OOME'ing on upgrade because the <mathphrase>thousands of regions * number of column families * 2MB MSLAB (at a minimum)</mathphrase>
	puts your heap over the top. Set <varname>hbase.hregion.memstore.mslab.enabled</varname> to
	<constant>false</constant> or set the MSLAB size down from 2MB by setting <varname>hbase.hregion.memstore.mslab.chunksize</varname> to something less.
	</para>
	</section>

	<section><title>Distributed splitting is on by default
	</title>
	<para>Previous, WAL logs on crash were split by the Master alone. In 0.92.0, log splitting is done by the cluster (See See “HBASE-1364 [performance] Distributed splitting of regionserver commit logs”). This should cut down significantly on the amount of time it takes splitting logs and getting regions back online again.
	</para>
	</section>

	<section><title>Memory accounting is different now
	</title>
	<para>In 0.92.0, <xref linkend="hfilev2" /> indices and bloom filters take up residence in the same LRU used caching blocks that come from the filesystem.
	In 0.90.x, the HFile v1 indices lived outside of the LRU so they took up space even if the index was on a ‘cold’ file, one that wasn’t being actively used. With the indices now in the LRU, you may find you
	have less space for block caching. Adjust your block cache accordingly. See the <xref linkend="block.cache" /> for more detail.
	The block size default size has been changed in 0.92.0 from 0.2 (20 percent of heap) to 0.25.
	</para>
	</section>


	<section><title>On the Hadoop version to use
	</title>
	<para>Run 0.92.0 on Hadoop 1.0.x (or CDH3u3 when it ships). The performance benefits are worth making the move. Otherwise, our Hadoop prescription is as it has been; you need an Hadoop that supports a working sync. See <xref linkend="hadoop" />.
	</para>

	<para>If running on Hadoop 1.0.x (or CDH3u3), enable local read. See <link xlink:href="http://files.meetup.com/1350427/hug_ebay_jdcryans.pdf">Practical Caching</link> presentation for ruminations on the performance benefits ‘going local’ (and for how to enable local reads).
	</para>
	</section>
	<section><title>HBase 0.92.0 ships with ZooKeeper 3.4.2
	</title>
	<para>If you can, upgrade your zookeeper. If you can’t, 3.4.2 clients should work against 3.3.X ensembles (HBase makes use of 3.4.2 API).
	</para>
	</section>
	<section>
	<title>Online alter is off by default
	</title>
	<para>In 0.92.0, we’ve added an experimental online schema alter facility (See <xref linkend="hbase.online.schema.update.enable" />). Its off by default. Enable it at your own risk. Online alter and splitting tables do not play well together so be sure your cluster quiescent using this feature (for now).
	</para>
	</section>
	<section>
	<title>WebUI
	</title>
	<para>The webui has had a few additions made in 0.92.0. It now shows a list of the regions currently transitioning, recent compactions/flushes, and a process list of running processes (usually empty if all is well and requests are being handled promptly). Other additions including requests by region, a debugging servlet dump, etc.
	</para>
	</section>
	<section>
	<title>Security tarball
	</title>
	<para>We now ship with two tarballs; secure and insecure HBase. Documentation on how to setup a secure HBase is on the way.
	</para>
	</section>

	<section><title>Experimental off-heap cache
	</title>
	<para>
	A new cache was contributed to 0.92.0 to act as a solution between using the “on-heap” cache which is the current LRU cache the region servers have and the operating system cache which is out of our control.
	To enable, set “-XX:MaxDirectMemorySize” in hbase-env.sh to the value for maximum direct memory size and specify hbase.offheapcache.percentage in hbase-site.xml with the percentage that you want to dedicate to off-heap cache. This should only be set for servers and not for clients. Use at your own risk.
	See this blog post for additional information on this new experimental feature: http://www.cloudera.com/blog/2012/01/caching-in-hbase-slabcache/
	</para>
	</section>

	<section><title>Changes in HBase replication
	</title>
	<para>0.92.0 adds two new features: multi-slave and multi-master replication. The way to enable this is the same as adding a new peer, so in order to have multi-master you would just run add_peer for each cluster that acts as a master to the other slave clusters. Collisions are handled at the timestamp level which may or may not be what you want, this needs to be evaluated on a per use case basis. Replication is still experimental in 0.92 and is disabled by default, run it at your own risk.
	</para>
	</section>


	<section><title>RegionServer now aborts if OOME
	</title>
	<para>If an OOME, we now have the JVM kill -9 the regionserver process so it goes down fast. Previous, a RegionServer might stick around after incurring an OOME limping along in some wounded state. To disable this facility, and recommend you leave it in place, you’d need to edit the bin/hbase file. Look for the addition of the -XX:OnOutOfMemoryError="kill -9 %p" arguments (See [HBASE-4769] - ‘Abort RegionServer Immediately on OOME’)
	</para>
	</section>


	<section><title>HFile V2 and the “Bigger, Fewer” Tendency
	</title>
	<para>0.92.0 stores data in a new format, <xref linkend="hfilev2" />. As HBase runs, it will move all your data from HFile v1 to HFile v2 format. This auto-migration will run in the background as flushes and compactions run.
	HFile V2 allows HBase run with larger regions/files. In fact, we encourage that all HBasers going forward tend toward Facebook axiom #1, run with larger, fewer regions.
	If you have lots of regions now -- more than 100s per host -- you should look into setting your region size up after you move to 0.92.0 (In 0.92.0, default size is not 1G, up from 256M), and then running online merge tool (See “HBASE-1621 merge tool should work on online cluster, but disabled table”).
	</para>
	</section>
	</section>
	</chapter>