sijie commented on a change in pull request #4792: [docs] Update the upgrade guide URL: https://github.com/apache/pulsar/pull/4792#discussion_r307587313
########## File path: site2/docs/administration-upgrade.md ########## @@ -1,182 +1,130 @@ --- id: administration-upgrade -title: The Pulsar Upgrade Guide +title: Upgrade Guide sidebar_label: Upgrade --- -<!-- - - 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. - ---> - -## Overview - -Apache Pulsar is comprised of multiple components, zookeeper, bookies and brokers. These components are either -stateful or stateless. They will be taken care of differently. In general, the ZooKeeper nodes don't necessarily -need to be upgraded. Bookies are stateful so that's where you need to take the most care. Brokers and proxies -are stateless so less care is needed. - -This page provides a guideline on upgrading a Pulsar cluster. Please 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. In other words, don't start working through this guide on a live cluster. - Read guide entirely, make a plan, and then execute the plan. -- Pay careful consideration to the order in which components are upgraded. In general, you don't need to upgrade - your zookeeper or configuration store cluster (the global zookeeper cluster). For the remaining components, you - need to upgrade bookies first, upgrade brokers and proxies next, and then upgrade your clients. -- If autorecovery is enabled, you need to disable `autorecovery` during the whole upgrade process, - and re-enable it after the process is finished. -- Read the release notes carefully for each release. Not only do they contain information about noteworthy features, - but also changes to configuration that may impact your upgrade. -- Always upgrade a small subset of nodes of each type to canary test the new version before upgrading all nodes of that type - in the cluster. When you have upgraded the canary nodes, allow them to run for a while to ensure that they are working correctly. -- Always upgrade one datacenter to verify new version before upgrading all datacenters if your cluster is running in multi-clusters - replicated mode. - -Following is the detailed sequence to upgrade an Apache Pulsar cluster. If there is anything specials needed to be taken care, -we will describe the details for individual versions in "Upgrade Guides" section. - -## Sequence - -Follow the sequence below on upgrading an Apache Pulsar cluster - -> Typically you don't need to upgrade zookeeper unless there are strong reasons documented in "Upgrade Guides" section below. - -1. Upgrade ZooKeeper (optionally) - 1. Canary Test: test an upgraded version in one or small set of zookeeper nodes. - 2. Rolling Upgrade: rollout the upgraded version to all zookeeper servers incrementally, one at a time. Don't be too fast and always - monitor your dashboard during the whole rolling upgrade process. -2. Upgrade Bookies - 1. Canary Test: test an upgraded version in one or small set of bookies. - 2. Rolling Upgrade: - 1. Disable *autorecovery* by running the following command: +## Upgrade guidelines + +Apache Pulsar is comprised of multiple components, ZooKeeper, bookies and brokers. These components are either stateful or stateless. You do not have to upgrade ZooKeeper nodes unless you have special requirement. While upgrading, you need to pay attention to bookies (stateful), brokers and proxies (stateless). + +The following are some guidelines on upgrading a Pulsar cluster. Read the guidelines before upgrading. + +- Backup all your configuration files before upgrading. +- Read guide entirely, make a plan, and then execute the plan. When you make upgrade plan, you need to take your specific requirements and environment into consideration. +- Pay attention to the upgrading order of components. In general, you do not need to upgrade + your ZooKeeper or configuration store cluster (the global ZooKeeper cluster). You + need to upgrade bookies first, and then upgrade brokers, proxies, and your clients. +- If `autorecovery` is enabled, you need to disable `autorecovery` in the upgrade process, and re-enable it after completing the process. +- Read the release notes carefully for each release. Release notes contain features, configuration changes that might impact your upgrade. +- Upgrade a small subset of nodes of each type to canary test the new version before upgrading all nodes of that type in the cluster. When you have upgraded the canary nodes, run for a while to ensure that they are working correctly. +- Upgrade one data center to verify new version before upgrading all data centers if your cluster is running in multi-cluster replicated mode. + +> Note: Currently, Apache Pulsar is compatible between versions. + +## Upgrade sequence + +To upgrade an Apache Pulsar cluster, follow the upgrade sequence. + +1. Upgrade ZooKeeper (optional) +- Canary test: test an upgraded version in one or a small set of ZooKeeper nodes. +- Rolling upgrade: rollout the upgraded version to all ZooKeeper servers incrementally, one at a time. Monitor your dashboard during the whole rolling upgrade process. +2. Upgrade bookies +- Canary test: test an upgraded version in one or a small set of bookies. +- Rolling upgrade: + - a. Disable `autorecovery` with the following command. ```shell bin/bookkeeper shell autorecovery -disable - ``` - 2. rollout the upgraded version to all bookies in the cluster once you determined a version is safe after canary. - 3. After all the bookies are upgraded to run the new version, re-enable *autorecovery*: + ``` + - b. Rollout the upgraded version to all bookies in the cluster after you have determined a version is safe after canary. + - c. After all bookies are upgraded, re-enable `autorecovery` with the following command. ```shell bin/bookkeeper shell autorecovery -enable ``` -3. Upgrade Brokers - 1. Canary Test: test an upgraded version in one or small set of brokers. - 2. Rolling Upgrade: rollout the upgraded version to all brokers in the cluster once you determined a version is safe after canary. -4. Upgrade Proxies - 1. Canary Test: test an upgraded version in one or small set of proxies. - 2. Rolling Upgrade: rollout the upgraded version to all proxies in the cluster once you determined a version is safe after canary. +3. Upgrade brokers +- Canary test: test an upgraded version in one or a small set of brokers. +- Rolling upgrade: rollout the upgraded version to all brokers in the cluster after you have determined a version is safe after canary. +4. Upgrade proxies +- Canary test: test an upgraded version in one or a small set of proxies. +- Rolling upgrade: rollout the upgraded version to all proxies in the cluster after you have determined a version is safe after canary. -## Upgrade Bookies +## Upgrade ZooKeeper (optional) Review comment: ``` While upgrading bookies, you can do canary test first, and then upgrade all zookeeper in the cluster. ### Canary test You can test an upgraded version in one of zookeeper servers before upgrading all zookeeper servers in your cluster. To upgrade zookeeper server to a new version, complete the following steps: 1. Stop a zookeeper server. 2. Upgrade the binary and configuration files. 3. Start the zookeeper server with the new binary. 4. Use `pulsar zookeeper-shell` to connect to the newly upgraded zookeeper server and run a few commands to verify if it is working as expected. 5. Let the zookeeper server run for a few days, observe and make sure the zookeeper cluster is running fine without any errors. #### Canary rollback If issues occur during canary test, you can shut down the problematic zookeeper node, revert the binary and configuration, and restart the zookeeper with the reverted binary. ### Upgrade all zookeeper servers After canary test to upgrade one zookeeper in your cluster, you can upgrade all zookeeper servers in your cluster. You can upgrade all the zookeeper servers one by one by following the steps mentioned in canary test. ``` ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected] With regards, Apache Git Services
