bookkeeper-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [bookkeeper] branch branch-4.5 updated: ISSUE #355: upgrade guide
Date Mon, 07 Aug 2017 18:42:02 GMT
This is an automated email from the ASF dual-hosted git repository.

sijie pushed a commit to branch branch-4.5
in repository

The following commit(s) were added to refs/heads/branch-4.5 by this push:
     new 9900b3e  ISSUE #355: upgrade guide
9900b3e is described below

commit 9900b3e03486b4c8418dac91b9cfef60c1008343
Author: Sijie Guo <>
AuthorDate: Mon Aug 7 11:41:46 2017 -0700

    ISSUE #355: upgrade guide
    Descriptions of the changes in this PR:
    - provide a general upgrade guide
    - document notes for upgrading from 4.4 to 4.5.
    Author: Sijie Guo <>
    Reviewers: Luc Perkins <>, Jia Zhai <None>
    This closes #403 from sijie/upgrade_guide, closes #355
    (cherry picked from commit f90fa787522d59114caa3fe8b70345effb627f8e)
    Signed-off-by: Sijie Guo <>
 site/_data/sidebar.yaml           |  2 ++
 site/docs/latest/admin/ | 73 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 75 insertions(+)

diff --git a/site/_data/sidebar.yaml b/site/_data/sidebar.yaml
index 0138070..5136df6 100644
--- a/site/_data/sidebar.yaml
+++ b/site/_data/sidebar.yaml
@@ -26,6 +26,8 @@ groups:
     endpoint: autorecovery
   - name: Metric collection
     endpoint: metrics
+  - name: Upgrade
+    endpoint: upgrade
   #- name: Geo-replication
   #  endpoint: geo-replication
   #- name: Customized placement policies
diff --git a/site/docs/latest/admin/ b/site/docs/latest/admin/
new file mode 100644
index 0000000..9addee4
--- /dev/null
+++ b/site/docs/latest/admin/
@@ -0,0 +1,73 @@
+title: Upgrade
+> If you have questions about upgrades (or need help), please feel free to reach out to
us by [mailing list](/community/mailing-lists) or [Slack Channel](/community/slack).
+## Overview
+Consider the below guidelines in preparation for upgrading.
+- Always back up all your configuration files before upgrading.
+- Read through the documentation and draft an upgrade plan that matches your specific requirements
and environment before starting the upgrade process.
+    Put differently, don't start working through the guide on a live cluster. Read guide
entirely, make a plan, then execute the plan.
+- Pay careful consideration to the order in which components are upgraded. In general, you
need to upgrade bookies first and then upgrade your clients.
+- If autorecovery is running along with bookies, you need to pay attention to the upgrade
+- Read the release notes carefully for each release. They contain not only information about
noteworthy features, but also changes to configurations
+    that may impact your upgrade.
+- Always upgrade one or a small set of bookies to canary new version before upgraing all
bookies in your cluster.
+## Canary
+It is wise to canary an upgraded version in one or small set of bookies before upgrading
all bookies in your live cluster.
+You can follow below steps on how to canary a upgraded version:
+1. Stop a Bookie.
+2. Upgrade the binary and configuration.
+3. Start the Bookie in `ReadOnly` mode. This can be used to verify if the Bookie of this
new version can run well for read workload.
+4. Once the Bookie is running at `ReadOnly` mode successfully for a while, restart the Bookie
in `Write/Read` mode.
+5. After step 4, the Bookie will serve both write and read traffic.
+### Rollback Canaries
+If problems occur during canarying an upgraded version, you can simply take down the problematic
Bookie node. The remain bookies in the old cluster
+will repair this problematic bookie node by autorecovery. Nothing needs to be worried about.
+## Upgrade Steps
+Once you determined a version is safe to upgrade in a few nodes in your cluster, you can
perform following steps to upgrade all bookies in your cluster.
+1. Determine if autorecovery is running along with bookies. If yes, check if the clients
(either new clients with new binary or old clients with new configurations)
+are allowed to talk to old bookies; if clients are not allowed to talk to old bookies, please
[disable autorecovery](../../reference/cli/#autorecovery-1) during upgrade.
+2. Decide on performing a rolling upgrade or a downtime upgrade.
+3. Upgrade all Bookies (more below)
+4. If autorecovery was disabled during upgrade, [enable autorecovery](../../reference/cli/#autorecovery-1).
+5. After all bookies are upgraded, build applications that use `BookKeeper client` against
the new bookkeeper libraries and deploy the new versions.
+### Upgrade Bookies
+In a rolling upgrade scenario, upgrade one Bookie at a time. In a downtime upgrade scenario,
take the entire cluster down, upgrade each Bookie, then start the cluster.
+For each Bookie:
+1. Stop the bookie. 
+2. Upgrade the software (either new binary or new configuration)
+2. Start the bookie.
+## Upgrade Guides
+We describes the general upgrade method in Apache BookKeeper as above. We will cover the
details for individual versions.
+### 4.4.x to 4.5.x upgrade
+There isn't any protocol related backward compabilities changes in 4.5.0. So you can follow
the general upgrade sequence to upgrade from 4.4.x to 4.5.x.
+However, we list a list of things that you might want to know.
+1. 4.5.x upgrades netty from 3.x to 4.x. The memory usage pattern might be changed a bit.
Netty 4 uses more direct memory. Please pay attention to your memory usage
+    and adjust the JVM settings accordingly.
+2. `multi journals` is a non-rollbackable feature. If you configure a bookie to use multiple
journals on 4.5.x you can not roll the bookie back to use 4.4.x. You have
+    to take a bookie out and recover it if you want to rollback to 4.4.x.
+If you are planning to upgrade a non-secured cluster to a secured cluster enabling security
features in 4.5.0, please read [BookKeeper Security](../../security) for more details.

To stop receiving notification emails like this one, please contact
['"" <>'].

View raw message