[GitHub] ivankelly commented on a change in pull request #2048: Add Upgrade Guide to Apache Pulsar

2018-07-11 Thread GitBox
ivankelly commented on a change in pull request #2048: Add Upgrade Guide to 
Apache Pulsar
URL: https://github.com/apache/incubator-pulsar/pull/2048#discussion_r201637787
 
 

 ##
 File path: site/docs/latest/admin/Upgrade.md
 ##
 @@ -0,0 +1,152 @@
+---
+title: Upgrade
+---
+
+
+
+> If you have questions about upgrades (or need help), please feel free to 
reach out to us by [mailing list]({{ site.baseurl }}/contact) or [Slack 
Channel]({{ site.baseurl }}/contact).
+
+## 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, upgrade brokers next 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/brokers to canary new version 
before upgraing all bookies/brokers in your cluster.
+- Always upgrade one datacenter to canry new version before upgrading all 
datacenters if your cluster is running in multi-clusters replicated mode.
+
+Following is the general guide 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
+
+1. Upgrade Bookies
+  1. Canary: canary an upgraded version in one or small set of bookies.
+  2. Rolling Upgrade: rollout the upgraded version to all bookies in the 
cluster once you determined a version is safe after canary.
+2. Upgrade Brokers
+  1. Canary: canary 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.
+3. Upgrade Proxies
+  1. Canary: canary 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.
+
+Typically you don't need to upgrade zookeeper unless there are strong reasons 
documented in "Upgrade Guides" section below.
+But if you would like to keep your zookeeper cluster consistent with other 
components, follows the general upgrade guideline as others.
+
+1. Canary: canary an upgraded version in one of the zookeeper servers.
+2. Rolling Upgrade: rollout the upgraded version to all zookeeper servers 
incrementally, one at a time.
+
+## Upgrade Bookies
+
+> You can also read Apache BookKeeper [Upgrade 
Guide](http://bookkeeper.apache.org/docs/latest/admin/upgrade) for more details.
+
+### 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.
+   ```shell
+   bin/pulsar bookie --readOnly
+   ```
+4. Once the Bookie is running at `ReadOnly` mode successfully for a while, 
restart the Bookie in `Write/Read` mode.
+   ```shell
+   bin/pulsar bookie
+   ```
+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 bookies in your 
cluster, you can perform following steps to upgrade all bookies in your cluster.
+
+1. Decide on performing a rolling upgrade or a downtime upgrade.
+2. Upgrade all Bookies (more below)
+
+ 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 Brokers / Proxies
+
+Brokers and Proxies are almost same. They are `stateless` comparing to 
Bookies. so it is very straightforward on upgrading these two 

[GitHub] ivankelly commented on a change in pull request #2048: Add Upgrade Guide to Apache Pulsar

2018-07-11 Thread GitBox
ivankelly commented on a change in pull request #2048: Add Upgrade Guide to 
Apache Pulsar
URL: https://github.com/apache/incubator-pulsar/pull/2048#discussion_r201638762
 
 

 ##
 File path: site/docs/latest/admin/Upgrade.md
 ##
 @@ -0,0 +1,152 @@
+---
+title: Upgrade
+---
+
+
+
+> If you have questions about upgrades (or need help), please feel free to 
reach out to us by [mailing list]({{ site.baseurl }}/contact) or [Slack 
Channel]({{ site.baseurl }}/contact).
+
+## 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, upgrade brokers next 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/brokers to canary new version 
before upgraing all bookies/brokers in your cluster.
+- Always upgrade one datacenter to canry new version before upgrading all 
datacenters if your cluster is running in multi-clusters replicated mode.
+
+Following is the general guide 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
+
+1. Upgrade Bookies
+  1. Canary: canary an upgraded version in one or small set of bookies.
+  2. Rolling Upgrade: rollout the upgraded version to all bookies in the 
cluster once you determined a version is safe after canary.
+2. Upgrade Brokers
+  1. Canary: canary 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.
+3. Upgrade Proxies
+  1. Canary: canary 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.
+
+Typically you don't need to upgrade zookeeper unless there are strong reasons 
documented in "Upgrade Guides" section below.
+But if you would like to keep your zookeeper cluster consistent with other 
components, follows the general upgrade guideline as others.
+
+1. Canary: canary an upgraded version in one of the zookeeper servers.
+2. Rolling Upgrade: rollout the upgraded version to all zookeeper servers 
incrementally, one at a time.
+
+## Upgrade Bookies
+
+> You can also read Apache BookKeeper [Upgrade 
Guide](http://bookkeeper.apache.org/docs/latest/admin/upgrade) for more details.
+
+### 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.
+   ```shell
+   bin/pulsar bookie --readOnly
+   ```
+4. Once the Bookie is running at `ReadOnly` mode successfully for a while, 
restart the Bookie in `Write/Read` mode.
+   ```shell
+   bin/pulsar bookie
+   ```
+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 bookies in your 
cluster, you can perform following steps to upgrade all bookies in your cluster.
+
+1. Decide on performing a rolling upgrade or a downtime upgrade.
+2. Upgrade all Bookies (more below)
+
+ 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 Brokers / Proxies
+
+Brokers and Proxies are almost same. They are `stateless` comparing to 
Bookies. so it is very straightforward on upgrading these two 

[GitHub] ivankelly commented on a change in pull request #2048: Add Upgrade Guide to Apache Pulsar

2018-07-11 Thread GitBox
ivankelly commented on a change in pull request #2048: Add Upgrade Guide to 
Apache Pulsar
URL: https://github.com/apache/incubator-pulsar/pull/2048#discussion_r201636750
 
 

 ##
 File path: site/docs/latest/admin/Upgrade.md
 ##
 @@ -0,0 +1,152 @@
+---
+title: Upgrade
+---
+
+
+
+> If you have questions about upgrades (or need help), please feel free to 
reach out to us by [mailing list]({{ site.baseurl }}/contact) or [Slack 
Channel]({{ site.baseurl }}/contact).
+
+## 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, upgrade brokers next 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/brokers to canary new version 
before upgraing all bookies/brokers in your cluster.
+- Always upgrade one datacenter to canry new version before upgrading all 
datacenters if your cluster is running in multi-clusters replicated mode.
+
+Following is the general guide 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
+
+1. Upgrade Bookies
+  1. Canary: canary an upgraded version in one or small set of bookies.
+  2. Rolling Upgrade: rollout the upgraded version to all bookies in the 
cluster once you determined a version is safe after canary.
+2. Upgrade Brokers
+  1. Canary: canary 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.
+3. Upgrade Proxies
+  1. Canary: canary 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.
+
+Typically you don't need to upgrade zookeeper unless there are strong reasons 
documented in "Upgrade Guides" section below.
+But if you would like to keep your zookeeper cluster consistent with other 
components, follows the general upgrade guideline as others.
+
+1. Canary: canary an upgraded version in one of the zookeeper servers.
+2. Rolling Upgrade: rollout the upgraded version to all zookeeper servers 
incrementally, one at a time.
+
+## Upgrade Bookies
+
+> You can also read Apache BookKeeper [Upgrade 
Guide](http://bookkeeper.apache.org/docs/latest/admin/upgrade) for more details.
+
+### 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.
+   ```shell
+   bin/pulsar bookie --readOnly
+   ```
+4. Once the Bookie is running at `ReadOnly` mode successfully for a while, 
restart the Bookie in `Write/Read` mode.
+   ```shell
+   bin/pulsar bookie
+   ```
+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 bookies in your 
cluster, you can perform following steps to upgrade all bookies in your cluster.
+
+1. Decide on performing a rolling upgrade or a downtime upgrade.
 
 Review comment:
   is "downtime upgrade" common terminology. I understand what it means, but 
there's probably a better way to phrase it.
   
   "Decide whether you want to upgrade the whole cluster at once, implying 
downtime, or do a rolling upgrade."


This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact 

[GitHub] ivankelly commented on a change in pull request #2048: Add Upgrade Guide to Apache Pulsar

2018-07-11 Thread GitBox
ivankelly commented on a change in pull request #2048: Add Upgrade Guide to 
Apache Pulsar
URL: https://github.com/apache/incubator-pulsar/pull/2048#discussion_r201635600
 
 

 ##
 File path: site/docs/latest/admin/Upgrade.md
 ##
 @@ -0,0 +1,152 @@
+---
+title: Upgrade
+---
+
+
+
+> If you have questions about upgrades (or need help), please feel free to 
reach out to us by [mailing list]({{ site.baseurl }}/contact) or [Slack 
Channel]({{ site.baseurl }}/contact).
+
+## 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, upgrade brokers next 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/brokers to canary new version 
before upgraing all bookies/brokers in your cluster.
 
 Review comment:
   A general comment, not for this change, but I've been thinking we should 
stop calling them bookies in the context of pulsar, but rather call the pulsar 
storage nodes. bookie isn't very descriptive to the end user. 


This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org


With regards,
Apache Git Services


[GitHub] ivankelly commented on a change in pull request #2048: Add Upgrade Guide to Apache Pulsar

2018-07-11 Thread GitBox
ivankelly commented on a change in pull request #2048: Add Upgrade Guide to 
Apache Pulsar
URL: https://github.com/apache/incubator-pulsar/pull/2048#discussion_r201638086
 
 

 ##
 File path: site/docs/latest/admin/Upgrade.md
 ##
 @@ -0,0 +1,152 @@
+---
+title: Upgrade
+---
+
+
+
+> If you have questions about upgrades (or need help), please feel free to 
reach out to us by [mailing list]({{ site.baseurl }}/contact) or [Slack 
Channel]({{ site.baseurl }}/contact).
+
+## 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, upgrade brokers next 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/brokers to canary new version 
before upgraing all bookies/brokers in your cluster.
+- Always upgrade one datacenter to canry new version before upgrading all 
datacenters if your cluster is running in multi-clusters replicated mode.
+
+Following is the general guide 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
+
+1. Upgrade Bookies
+  1. Canary: canary an upgraded version in one or small set of bookies.
+  2. Rolling Upgrade: rollout the upgraded version to all bookies in the 
cluster once you determined a version is safe after canary.
+2. Upgrade Brokers
+  1. Canary: canary 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.
+3. Upgrade Proxies
+  1. Canary: canary 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.
+
+Typically you don't need to upgrade zookeeper unless there are strong reasons 
documented in "Upgrade Guides" section below.
+But if you would like to keep your zookeeper cluster consistent with other 
components, follows the general upgrade guideline as others.
+
+1. Canary: canary an upgraded version in one of the zookeeper servers.
+2. Rolling Upgrade: rollout the upgraded version to all zookeeper servers 
incrementally, one at a time.
+
+## Upgrade Bookies
+
+> You can also read Apache BookKeeper [Upgrade 
Guide](http://bookkeeper.apache.org/docs/latest/admin/upgrade) for more details.
+
+### 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.
+   ```shell
+   bin/pulsar bookie --readOnly
+   ```
+4. Once the Bookie is running at `ReadOnly` mode successfully for a while, 
restart the Bookie in `Write/Read` mode.
+   ```shell
+   bin/pulsar bookie
+   ```
+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 bookies in your 
cluster, you can perform following steps to upgrade all bookies in your cluster.
+
+1. Decide on performing a rolling upgrade or a downtime upgrade.
+2. Upgrade all Bookies (more below)
+
+ 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 Brokers / Proxies
+
+Brokers and Proxies are almost same. They are `stateless` comparing to 
Bookies. so it is very straightforward on upgrading these two 

[GitHub] ivankelly commented on a change in pull request #2048: Add Upgrade Guide to Apache Pulsar

2018-07-11 Thread GitBox
ivankelly commented on a change in pull request #2048: Add Upgrade Guide to 
Apache Pulsar
URL: https://github.com/apache/incubator-pulsar/pull/2048#discussion_r201627055
 
 

 ##
 File path: site/docs/latest/admin/Upgrade.md
 ##
 @@ -0,0 +1,152 @@
+---
+title: Upgrade
+---
+
+
+
+> If you have questions about upgrades (or need help), please feel free to 
reach out to us by [mailing list]({{ site.baseurl }}/contact) or [Slack 
Channel]({{ site.baseurl }}/contact).
+
+## 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, upgrade brokers next 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/brokers to canary new version 
before upgraing all bookies/brokers in your cluster.
+- Always upgrade one datacenter to canry new version before upgrading all 
datacenters if your cluster is running in multi-clusters replicated mode.
+
+Following is the general guide 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
+
+1. Upgrade Bookies
+  1. Canary: canary an upgraded version in one or small set of bookies.
+  2. Rolling Upgrade: rollout the upgraded version to all bookies in the 
cluster once you determined a version is safe after canary.
+2. Upgrade Brokers
+  1. Canary: canary 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.
+3. Upgrade Proxies
+  1. Canary: canary 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.
+
+Typically you don't need to upgrade zookeeper unless there are strong reasons 
documented in "Upgrade Guides" section below.
+But if you would like to keep your zookeeper cluster consistent with other 
components, follows the general upgrade guideline as others.
+
+1. Canary: canary an upgraded version in one of the zookeeper servers.
+2. Rolling Upgrade: rollout the upgraded version to all zookeeper servers 
incrementally, one at a time.
+
+## Upgrade Bookies
+
+> You can also read Apache BookKeeper [Upgrade 
Guide](http://bookkeeper.apache.org/docs/latest/admin/upgrade) for more details.
+
+### Canary
+
+It is wise to canary an upgraded version in one or small set of bookies before 
upgrading all bookies in your live cluster.
 
 Review comment:
   canary -> canary test
   in one or small set -> on a small subset
   
   Put in admonishment box.


This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org


With regards,
Apache Git Services


[GitHub] ivankelly commented on a change in pull request #2048: Add Upgrade Guide to Apache Pulsar

2018-07-11 Thread GitBox
ivankelly commented on a change in pull request #2048: Add Upgrade Guide to 
Apache Pulsar
URL: https://github.com/apache/incubator-pulsar/pull/2048#discussion_r201634904
 
 

 ##
 File path: site/docs/latest/admin/Upgrade.md
 ##
 @@ -0,0 +1,152 @@
+---
+title: Upgrade
+---
+
+
+
+> If you have questions about upgrades (or need help), please feel free to 
reach out to us by [mailing list]({{ site.baseurl }}/contact) or [Slack 
Channel]({{ site.baseurl }}/contact).
+
+## 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, upgrade brokers next 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/brokers to canary new version 
before upgraing all bookies/brokers in your cluster.
+- Always upgrade one datacenter to canry new version before upgrading all 
datacenters if your cluster is running in multi-clusters replicated mode.
+
+Following is the general guide 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
+
+1. Upgrade Bookies
+  1. Canary: canary an upgraded version in one or small set of bookies.
+  2. Rolling Upgrade: rollout the upgraded version to all bookies in the 
cluster once you determined a version is safe after canary.
+2. Upgrade Brokers
+  1. Canary: canary 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.
+3. Upgrade Proxies
+  1. Canary: canary 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.
+
+Typically you don't need to upgrade zookeeper unless there are strong reasons 
documented in "Upgrade Guides" section below.
+But if you would like to keep your zookeeper cluster consistent with other 
components, follows the general upgrade guideline as others.
+
+1. Canary: canary an upgraded version in one of the zookeeper servers.
+2. Rolling Upgrade: rollout the upgraded version to all zookeeper servers 
incrementally, one at a time.
+
+## Upgrade Bookies
+
+> You can also read Apache BookKeeper [Upgrade 
Guide](http://bookkeeper.apache.org/docs/latest/admin/upgrade) for more details.
+
+### 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.
+   ```shell
+   bin/pulsar bookie --readOnly
+   ```
+4. Once the Bookie is running at `ReadOnly` mode successfully for a while, 
restart the Bookie in `Write/Read` mode.
+   ```shell
+   bin/pulsar bookie
+   ```
+5. After step 4, the Bookie will serve both write and read traffic.
+
+ Rollback Canaries
 
 Review comment:
   Rollback Canaries -> Canary rollback


This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org


With regards,
Apache Git Services


[GitHub] ivankelly commented on a change in pull request #2048: Add Upgrade Guide to Apache Pulsar

2018-07-11 Thread GitBox
ivankelly commented on a change in pull request #2048: Add Upgrade Guide to 
Apache Pulsar
URL: https://github.com/apache/incubator-pulsar/pull/2048#discussion_r201618522
 
 

 ##
 File path: site/docs/latest/admin/Upgrade.md
 ##
 @@ -0,0 +1,152 @@
+---
+title: Upgrade
+---
+
+
+
+> If you have questions about upgrades (or need help), please feel free to 
reach out to us by [mailing list]({{ site.baseurl }}/contact) or [Slack 
Channel]({{ site.baseurl }}/contact).
+
+## 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, upgrade brokers next and then 
upgrade your clients.
 
 Review comment:
   Remove "In general".
   
   What about configuration store? zookeeper? proxies?


This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org


With regards,
Apache Git Services


[GitHub] ivankelly commented on a change in pull request #2048: Add Upgrade Guide to Apache Pulsar

2018-07-11 Thread GitBox
ivankelly commented on a change in pull request #2048: Add Upgrade Guide to 
Apache Pulsar
URL: https://github.com/apache/incubator-pulsar/pull/2048#discussion_r201623711
 
 

 ##
 File path: site/docs/latest/admin/Upgrade.md
 ##
 @@ -0,0 +1,152 @@
+---
+title: Upgrade
+---
+
+
+
+> If you have questions about upgrades (or need help), please feel free to 
reach out to us by [mailing list]({{ site.baseurl }}/contact) or [Slack 
Channel]({{ site.baseurl }}/contact).
+
+## 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, upgrade brokers next 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/brokers to canary new version 
before upgraing all bookies/brokers in your cluster.
+- Always upgrade one datacenter to canry new version before upgrading all 
datacenters if your cluster is running in multi-clusters replicated mode.
+
+Following is the general guide to upgrade an Apache Pulsar cluster. If there 
is anything specials needed to be taken care, we will describe the details
 
 Review comment:
   "If there ..." -> 'The "Upgrade Guides" section covers any specific 
differences for the different deployment environments (k8s, aws, etc).'
   
   Is there going to be anything in "Upgrade Guides"?


This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org


With regards,
Apache Git Services


[GitHub] ivankelly commented on a change in pull request #2048: Add Upgrade Guide to Apache Pulsar

2018-07-11 Thread GitBox
ivankelly commented on a change in pull request #2048: Add Upgrade Guide to 
Apache Pulsar
URL: https://github.com/apache/incubator-pulsar/pull/2048#discussion_r201496085
 
 

 ##
 File path: site/docs/latest/admin/Upgrade.md
 ##
 @@ -0,0 +1,152 @@
+---
+title: Upgrade
+---
+
+
+
+> If you have questions about upgrades (or need help), please feel free to 
reach out to us by [mailing list]({{ site.baseurl }}/contact) or [Slack 
Channel]({{ site.baseurl }}/contact).
+
+## 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, upgrade brokers next 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/brokers to canary new version 
before upgraing all bookies/brokers in your cluster.
+- Always upgrade one datacenter to canry new version before upgrading all 
datacenters if your cluster is running in multi-clusters replicated mode.
 
 Review comment:
   I wouldn't call it canary if the whole DC is upgraded. I'd say "to verify 
the new version"


This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org


With regards,
Apache Git Services


[GitHub] ivankelly commented on a change in pull request #2048: Add Upgrade Guide to Apache Pulsar

2018-07-11 Thread GitBox
ivankelly commented on a change in pull request #2048: Add Upgrade Guide to 
Apache Pulsar
URL: https://github.com/apache/incubator-pulsar/pull/2048#discussion_r201624141
 
 

 ##
 File path: site/docs/latest/admin/Upgrade.md
 ##
 @@ -0,0 +1,152 @@
+---
+title: Upgrade
+---
+
+
+
+> If you have questions about upgrades (or need help), please feel free to 
reach out to us by [mailing list]({{ site.baseurl }}/contact) or [Slack 
Channel]({{ site.baseurl }}/contact).
+
+## 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, upgrade brokers next 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/brokers to canary new version 
before upgraing all bookies/brokers in your cluster.
+- Always upgrade one datacenter to canry new version before upgrading all 
datacenters if your cluster is running in multi-clusters replicated mode.
+
+Following is the general guide 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
+
+1. Upgrade Bookies
+  1. Canary: canary an upgraded version in one or small set of bookies.
+  2. Rolling Upgrade: rollout the upgraded version to all bookies in the 
cluster once you determined a version is safe after canary.
+2. Upgrade Brokers
+  1. Canary: canary 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.
+3. Upgrade Proxies
+  1. Canary: canary 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.
+
+Typically you don't need to upgrade zookeeper unless there are strong reasons 
documented in "Upgrade Guides" section below.
+But if you would like to keep your zookeeper cluster consistent with other 
components, follows the general upgrade guideline as others.
 
 Review comment:
   Generally, I think they will want to keep the same version of the software 
on all machines.


This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org


With regards,
Apache Git Services


[GitHub] ivankelly commented on a change in pull request #2048: Add Upgrade Guide to Apache Pulsar

2018-07-11 Thread GitBox
ivankelly commented on a change in pull request #2048: Add Upgrade Guide to 
Apache Pulsar
URL: https://github.com/apache/incubator-pulsar/pull/2048#discussion_r201619275
 
 

 ##
 File path: site/docs/latest/admin/Upgrade.md
 ##
 @@ -0,0 +1,152 @@
+---
+title: Upgrade
+---
+
+
+
+> If you have questions about upgrades (or need help), please feel free to 
reach out to us by [mailing list]({{ site.baseurl }}/contact) or [Slack 
Channel]({{ site.baseurl }}/contact).
+
+## 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, upgrade brokers next and then 
upgrade your clients.
+- If autorecovery is running along with bookies, you need to pay attention to 
the upgrade sequence.
 
 Review comment:
   running along with bookies -> running on bookies
   
   > you need to pay attention to the upgrade sequence
   
   You always need to pay attention to the sequence. Are you saying to pay 
attention to the sequence of bookies upgrades? What does pay attention mean? 
Since bookies are stateful, and data is distributed at random, the 
recommendation should really be to upgrade one bookie at a time to avoid topics 
becoming unavailable.


This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org


With regards,
Apache Git Services


[GitHub] ivankelly commented on a change in pull request #2048: Add Upgrade Guide to Apache Pulsar

2018-07-11 Thread GitBox
ivankelly commented on a change in pull request #2048: Add Upgrade Guide to 
Apache Pulsar
URL: https://github.com/apache/incubator-pulsar/pull/2048#discussion_r201625356
 
 

 ##
 File path: site/docs/latest/admin/Upgrade.md
 ##
 @@ -0,0 +1,152 @@
+---
+title: Upgrade
+---
+
+
+
+> If you have questions about upgrades (or need help), please feel free to 
reach out to us by [mailing list]({{ site.baseurl }}/contact) or [Slack 
Channel]({{ site.baseurl }}/contact).
+
+## Overview
+
+Consider the below guidelines in preparation for upgrading.
 
 Review comment:
   It would be good to have a paragraph at the start to give an overview of the 
upgrade. 
   
   i.e. 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 is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org


With regards,
Apache Git Services


[GitHub] ivankelly commented on a change in pull request #2048: Add Upgrade Guide to Apache Pulsar

2018-07-11 Thread GitBox
ivankelly commented on a change in pull request #2048: Add Upgrade Guide to 
Apache Pulsar
URL: https://github.com/apache/incubator-pulsar/pull/2048#discussion_r201619573
 
 

 ##
 File path: site/docs/latest/admin/Upgrade.md
 ##
 @@ -0,0 +1,152 @@
+---
+title: Upgrade
+---
+
+
+
+> If you have questions about upgrades (or need help), please feel free to 
reach out to us by [mailing list]({{ site.baseurl }}/contact) or [Slack 
Channel]({{ site.baseurl }}/contact).
+
+## 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, upgrade brokers next 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
 
 Review comment:
   This contain not only -> Not only do they contain
   configurations -> configuration


This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org


With regards,
Apache Git Services


[GitHub] ivankelly commented on a change in pull request #2048: Add Upgrade Guide to Apache Pulsar

2018-07-11 Thread GitBox
ivankelly commented on a change in pull request #2048: Add Upgrade Guide to 
Apache Pulsar
URL: https://github.com/apache/incubator-pulsar/pull/2048#discussion_r201625942
 
 

 ##
 File path: site/docs/latest/admin/Upgrade.md
 ##
 @@ -0,0 +1,152 @@
+---
+title: Upgrade
+---
+
+
+
+> If you have questions about upgrades (or need help), please feel free to 
reach out to us by [mailing list]({{ site.baseurl }}/contact) or [Slack 
Channel]({{ site.baseurl }}/contact).
+
+## 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, upgrade brokers next 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/brokers to canary new version 
before upgraing all bookies/brokers in your cluster.
+- Always upgrade one datacenter to canry new version before upgrading all 
datacenters if your cluster is running in multi-clusters replicated mode.
+
+Following is the general guide 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
+
+1. Upgrade Bookies
+  1. Canary: canary an upgraded version in one or small set of bookies.
 
 Review comment:
   "Canary: canary an" -> "Canary: test an"
   "in one or small set" -> "on a small subset"


This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org


With regards,
Apache Git Services


[GitHub] ivankelly commented on a change in pull request #2048: Add Upgrade Guide to Apache Pulsar

2018-07-11 Thread GitBox
ivankelly commented on a change in pull request #2048: Add Upgrade Guide to 
Apache Pulsar
URL: https://github.com/apache/incubator-pulsar/pull/2048#discussion_r201625533
 
 

 ##
 File path: site/docs/latest/admin/Upgrade.md
 ##
 @@ -0,0 +1,152 @@
+---
+title: Upgrade
+---
+
+
+
+> If you have questions about upgrades (or need help), please feel free to 
reach out to us by [mailing list]({{ site.baseurl }}/contact) or [Slack 
Channel]({{ site.baseurl }}/contact).
+
+## 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.
 
 Review comment:
   Make this one of those "admonishment" boxes


This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org


With regards,
Apache Git Services


[GitHub] ivankelly commented on a change in pull request #2048: Add Upgrade Guide to Apache Pulsar

2018-07-11 Thread GitBox
ivankelly commented on a change in pull request #2048: Add Upgrade Guide to 
Apache Pulsar
URL: https://github.com/apache/incubator-pulsar/pull/2048#discussion_r201624577
 
 

 ##
 File path: site/docs/latest/admin/Upgrade.md
 ##
 @@ -0,0 +1,152 @@
+---
+title: Upgrade
+---
+
+
+
+> If you have questions about upgrades (or need help), please feel free to 
reach out to us by [mailing list]({{ site.baseurl }}/contact) or [Slack 
Channel]({{ site.baseurl }}/contact).
+
+## 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, upgrade brokers next 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/brokers to canary new version 
before upgraing all bookies/brokers in your cluster.
+- Always upgrade one datacenter to canry new version before upgrading all 
datacenters if your cluster is running in multi-clusters replicated mode.
+
+Following is the general guide 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
+
+1. Upgrade Bookies
+  1. Canary: canary an upgraded version in one or small set of bookies.
+  2. Rolling Upgrade: rollout the upgraded version to all bookies in the 
cluster once you determined a version is safe after canary.
+2. Upgrade Brokers
+  1. Canary: canary 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.
+3. Upgrade Proxies
+  1. Canary: canary 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.
+
+Typically you don't need to upgrade zookeeper unless there are strong reasons 
documented in "Upgrade Guides" section below.
+But if you would like to keep your zookeeper cluster consistent with other 
components, follows the general upgrade guideline as others.
+
+1. Canary: canary an upgraded version in one of the zookeeper servers.
+2. Rolling Upgrade: rollout the upgraded version to all zookeeper servers 
incrementally, one at a time.
+
+## Upgrade Bookies
+
+> You can also read Apache BookKeeper [Upgrade 
Guide](http://bookkeeper.apache.org/docs/latest/admin/upgrade) for more details.
+
+### Canary
 
 Review comment:
   "Canary" -> "Canary testing"


This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org


With regards,
Apache Git Services


[GitHub] ivankelly commented on a change in pull request #2048: Add Upgrade Guide to Apache Pulsar

2018-07-11 Thread GitBox
ivankelly commented on a change in pull request #2048: Add Upgrade Guide to 
Apache Pulsar
URL: https://github.com/apache/incubator-pulsar/pull/2048#discussion_r201622511
 
 

 ##
 File path: site/docs/latest/admin/Upgrade.md
 ##
 @@ -0,0 +1,152 @@
+---
+title: Upgrade
+---
+
+
+
+> If you have questions about upgrades (or need help), please feel free to 
reach out to us by [mailing list]({{ site.baseurl }}/contact) or [Slack 
Channel]({{ site.baseurl }}/contact).
+
+## 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, upgrade brokers next 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/brokers to canary new version 
before upgraing all bookies/brokers in your cluster.
 
 Review comment:
   "upgrade one or a small set" -> "a small subset"
   "to canary new version" -> "to canary the new version"
   "upgraing" -> "upgrading"
   
   This is kinda contradictory with the fact that bookies should all be 
upgraded first, then brokers. An admin can't upgrade one broker and one bookie 
to canary the release. You have the full sequence below, so maybe here just you 
can say:
   
   - 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.


This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org


With regards,
Apache Git Services


[GitHub] ivankelly commented on a change in pull request #2048: Add Upgrade Guide to Apache Pulsar

2018-07-11 Thread GitBox
ivankelly commented on a change in pull request #2048: Add Upgrade Guide to 
Apache Pulsar
URL: https://github.com/apache/incubator-pulsar/pull/2048#discussion_r201618191
 
 

 ##
 File path: site/docs/latest/admin/Upgrade.md
 ##
 @@ -0,0 +1,152 @@
+---
+title: Upgrade
+---
+
+
+
+> If you have questions about upgrades (or need help), please feel free to 
reach out to us by [mailing list]({{ site.baseurl }}/contact) or [Slack 
Channel]({{ site.baseurl }}/contact).
+
+## 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.
 
 Review comment:
   Put differently -> In other words
   through the guide -> through this guide
   Read guide entirely -> Read the guide in its entirety
   then execute -> and then execute


This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org


With regards,
Apache Git Services