[bookkeeper] branch master updated: ISSUE #355: upgrade guide

[si...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

sijie pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/bookkeeper.git


The following commit(s) were added to refs/heads/master by this push:
     new f90fa78  ISSUE #355: upgrade guide
f90fa78 is described below

commit f90fa787522d59114caa3fe8b70345effb627f8e
Author: Sijie Guo <si...@apache.org>
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 <si...@apache.org>
    
    Reviewers: Luc Perkins <lu...@gmail.com>, Jia Zhai <None>
    
    This closes #403 from sijie/upgrade_guide, closes #355
---
 site/_data/sidebar.yaml           |  2 ++
 site/docs/latest/admin/upgrade.md | 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/upgrade.md b/site/docs/latest/admin/upgrade.md
new file mode 100644
index 0000000..9addee4
--- /dev/null
+++ b/site/docs/latest/admin/upgrade.md
@@ -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 sequence.
+- 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
['"commits@bookkeeper.apache.org" <co...@bookkeeper.apache.org>'].