You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@geode.apache.org by GitBox <gi...@apache.org> on 2021/03/16 22:11:31 UTC
[GitHub] [geode] karensmolermiller commented on a change in pull request #6134: GEODE-8946: User Guide - add an Upgrade section
karensmolermiller commented on a change in pull request #6134:
URL: https://github.com/apache/geode/pull/6134#discussion_r595413270
##########
File path: geode-docs/getting_started/upgrade/upgrade_overview.html.md.erb
##########
@@ -0,0 +1,56 @@
+<% set_title("Upgrading", product_name_long) %>
+
+
+<!--
+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.
+-->
+
+To upgrade an existing installation to a new version of <%=vars.product_name_long%>,
+follow these general steps:
+
+1. Back up your current system.
+1. Install the new version of the software.
+1. Stop your distributed system using the current software.
+1. Restart the system using the new software.
+
+In many cases, components running under the current version can be stopped selectively, then restarted under the new version
+so that the distributed system as a whole remains functional during the upgrade process; this is known as a "rolling upgrade."
Review comment:
Maybe change _distributed system_ to _cluster_?
##########
File path: geode-docs/getting_started/upgrade/upgrade_overview.html.md.erb
##########
@@ -0,0 +1,56 @@
+<% set_title("Upgrading", product_name_long) %>
+
+
+<!--
+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.
+-->
+
+To upgrade an existing installation to a new version of <%=vars.product_name_long%>,
+follow these general steps:
+
+1. Back up your current system.
+1. Install the new version of the software.
+1. Stop your distributed system using the current software.
+1. Restart the system using the new software.
+
+In many cases, components running under the current version can be stopped selectively, then restarted under the new version
+so that the distributed system as a whole remains functional during the upgrade process; this is known as a "rolling upgrade."
+
+In other cases, the entire system must be stopped in order to accomplish the upgrade,
+which will require some downtime for your system.
+
+See [Planning an Upgrade](upgrade_planning.html) to choose the upgrade scenario that best suits your implementation and to understand the resources
+you will need to accomplish the upgrade. Then select the appropriate upgrade procedure for more detailed instructions that fit your specific needs.
+
+## <a id="upgrade_details" class="no-quick-link"></a>Upgrade Details
+
+- **[Planning an Upgrade](upgrade_planning.html)**
+
+ This section discusses the upgrade paths for various <%=vars.product_name_long%>
+ versions, and it lists information you need to know before you begin
+ the upgrade process.
+
+- **[Rolling Upgrade](upgrade_rolling.html)**
+
+ A rolling upgrade allows you to keep your existing distributed system running while you upgrade your members gradually.
Review comment:
Maybe change _distributed system_ to _cluster_?
##########
File path: geode-docs/getting_started/upgrade/upgrade_overview.html.md.erb
##########
@@ -0,0 +1,56 @@
+<% set_title("Upgrading", product_name_long) %>
+
+
+<!--
+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.
+-->
+
+To upgrade an existing installation to a new version of <%=vars.product_name_long%>,
+follow these general steps:
+
+1. Back up your current system.
+1. Install the new version of the software.
+1. Stop your distributed system using the current software.
Review comment:
Maybe change _distributed system_ to _cluster_?
##########
File path: geode-docs/getting_started/upgrade/upgrade_rolling.html.md.erb
##########
@@ -0,0 +1,218 @@
+---
+title: Rolling 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.
+-->
+
+A rolling upgrade eliminates system downtime by keeping your existing distributed system running while you upgrade one member at a time.
+Each upgraded member can communicate with other members that are still running the earlier version of <%=vars.product_name%>, so servers can respond to
+client requests even as the upgrade is underway. Interdependent data members can be stopped and started without mutually blocking, a problem
+that can occur when multiple data members are stopped at the same time.
+
+## <a id="rolling-upgrade-limitations-requirements" class="no-quick-link"></a>Rolling Upgrade Limitations and Requirements
+
+**Versions**
+
+Rolling upgrade requires that the older and newer versions of <%=vars.product_name%> are mutually compatible, which usually means that they
+share the same major version number.
+
+See [Version Compatibilities](upgrade_planning.html#version_compatibilities)
+for more details on how different versions of <%=vars.product_name%> can interoperate.
+
+**Components**
+
+Rolling upgrades apply to the peer members or cache servers within a distributed system.
Review comment:
If changing other things, can you add locators to this list? They are peer members, but I don't know that readers would know.
##########
File path: geode-book/master_middleman/source/subnavs/geode-subnav.erb
##########
@@ -49,6 +49,23 @@ limitations under the License.
</li>
</ul>
</li>
+ <li class="has_submenu">
+ <a href="/docs/guide/<%=vars.product_version_nodot%>/getting_started/upgrade/upgrade_overview.html">Upgrading <%=vars.product_name_long%></a>
+ <ul>
+ <li>
+ <a href="/docs/guide/<%=vars.product_version_nodot%>/getting_started/upgrade/upgrade_planning.html">Planning an upgrade</a>
+ </li>
+ <li>
+ <a href="/docs/guide/<%=vars.product_version_nodot%>/getting_started/upgrade/upgrade_rolling.html">Rolling upgrade</a>
+ </li>
+ <li>
+ <a href="/docs/guide/<%=vars.product_version_nodot%>/getting_started/upgrade/upgrade_offline.html">Offline upgrade</a>
+ </li>
+ <li>
+ <a href="/docs/guide/<%=vars.product_version_nodot%>/getting_started/upgrade/upgrade_clients.html">Upgrading clients</a>
+ </li>
+ </ul>
+ </li>
Review comment:
Within these new subnav entries, please capitalize to match what is done in the rest of the subnav.
##########
File path: geode-docs/getting_started/upgrade/upgrade_rolling.html.md.erb
##########
@@ -0,0 +1,218 @@
+---
+title: Rolling 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.
+-->
+
+A rolling upgrade eliminates system downtime by keeping your existing distributed system running while you upgrade one member at a time.
Review comment:
Maybe change _distributed system_ to _cluster_? I'm only marking this for the first instance within this subsection.
##########
File path: geode-docs/getting_started/upgrade/upgrade_planning.html.md.erb
##########
@@ -0,0 +1,91 @@
+---
+title: Planning an 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.
+-->
+
+Before you upgrade your system, back it up. Make backup copies of all existing disk-stores,
+server-side code, configuration files, and data across the entire cluster. To get a backup of the
+data that includes the most recent changes may require that traffic across the cluster is stopped
+before the backup is made.
+The discussion at [Creating Backups for System Recovery and Operational Management](../../managing/disk_storage/backup_restore_disk_store.html#backup_restore_disk_store)
+explains the process, and the
+[backup disk-store](../../tools_modules/gfsh/command-pages/backup.html) command reference page describes
+how to use the `gfsh backup disk-store` command to make a backup.
+
+## <a id="guidelines-upgrading" class="no-quick-link"></a>Guidelines for Upgrading
+
+- Schedule your upgrade during a period of low user activity for your system and network.
+- **Important:** After all locators have been upgraded, *do not start or restart any processes* that use the older version of the software. The older process will either not be allowed to join the distributed system or, if allowed to join, can potentially cause a deadlock.
+- Verify that all members that you wish to upgrade are members of the same distributed system cluster.
+A list of cluster members will be output with the `gfsh` command:
+
+ ``` pre
+ gfsh>list members
+ ```
+
+- Locate a copy of your system's startup script, if your site has one (most do). The startup script can be a handy reference for restarting upgraded locators and servers with the same `gfsh` command lines that were used in your current installation.
+
+- Identify how your current cluster configuration was specified. The way in which your cluster
+ configuration was created determines which commands you use to save and restore that cluster
+ configuration during the upgrade procedure. There are two possibilites:
+
+ - With `gfsh` commands, relying on the underlying **cluster configuration service** to record the configuration: see [Exporting and Importing Cluster Configurations](../../configuring/cluster_config/export-import.html).
+ - With **XML properties** specified through the Java API or configuration files: see [Deploying Configuration Files without the Cluster Configuration Service](../../configuring/running/deploying_config_files.html).
+
+- Do not modify region attributes or data, either via `gfsh` or `cache.xml` configuration, during the upgrade process.
+
+- If possible, follow the [Rolling Upgrade](upgrade_rolling.html) procedure. A multi-site
+installation can also do rolling upgrades within each site. If a rolling upgrade is not possible,
+follow the [Off-Line Upgrade](upgrade_offline.html) procedure.
+A rolling upgrade is not possible for a cluster that has partitioned regions without redundancy.
+Without the redundancy, region entries will be lost when individual servers are taken out of the
+cluster during a rolling upgrade.
+
+## <a id="version_compatibilities" class="no-quick-link"></a>Version Compatibilities
+
+Your choice of upgrade procedure depends, in part, on the versions of <%=vars.product_name_long%> involved.
+
+- **Version Compatibility Between Peers and Cache Servers**
+
+ For best reliability and performance, all server components of a <%=vars.product_name%> system should run the same version of the software.
+ For the purposes of a rolling upgrade, you can have peers or cache servers running different minor
+ versions of <%=vars.product_name_long%> at the same time, as long as the major version is the same. For example,
+ some components can continue to run under version <%=vars.product_version_old_minor%> while you are in the process of upgrading to
+ version <%=vars.product_version%>.
+
+- **Version Compatibility Between Clients and Servers**
+
+ Client/server access is backward compatible. An <%=vars.product_name_long%> cluster can be accessed by clients using any previous version. However, clients
+ cannot connect to servers running older versions of <%=vars.product_name_long%>. For example, a client running <%=vars.product_name_long%> <%=vars.product_version_old_minor%> can access a cluster
+ running <%=vars.product_name_long%> <%=vars.product_version%>, but a client running <%=vars.product_name_long%> <%=vars.product_version%> could not connect to a cluster running <%=vars.product_name_long%> <%=vars.product_version_old_minor%>.
+
+- **Version Compatibility Between Sites in Multi-Site (WAN) Deployments**
+
+ In multi-site (WAN) deployments, sites should still be able to communicate with one another, even if they use different versions.
+
+## <a id="java-notes" class="no-quick-link"></a>Java Notes
+
+- To check your current Java version, type `java -version` at a command-line prompt.
+
+- <%=vars.product_name_long%> <%=vars.product_version%> requires Java SE 8, version 92 or a more recent version.
Review comment:
I believe this is quite out of date. Maybe revise to link to the Host Machine Requirements subsection, where the Java version is listed?
##########
File path: geode-docs/getting_started/upgrade/upgrade_planning.html.md.erb
##########
@@ -0,0 +1,91 @@
+---
+title: Planning an 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.
+-->
+
+Before you upgrade your system, back it up. Make backup copies of all existing disk-stores,
+server-side code, configuration files, and data across the entire cluster. To get a backup of the
+data that includes the most recent changes may require that traffic across the cluster is stopped
+before the backup is made.
+The discussion at [Creating Backups for System Recovery and Operational Management](../../managing/disk_storage/backup_restore_disk_store.html#backup_restore_disk_store)
+explains the process, and the
+[backup disk-store](../../tools_modules/gfsh/command-pages/backup.html) command reference page describes
+how to use the `gfsh backup disk-store` command to make a backup.
+
+## <a id="guidelines-upgrading" class="no-quick-link"></a>Guidelines for Upgrading
+
+- Schedule your upgrade during a period of low user activity for your system and network.
+- **Important:** After all locators have been upgraded, *do not start or restart any processes* that use the older version of the software. The older process will either not be allowed to join the distributed system or, if allowed to join, can potentially cause a deadlock.
+- Verify that all members that you wish to upgrade are members of the same distributed system cluster.
+A list of cluster members will be output with the `gfsh` command:
+
+ ``` pre
+ gfsh>list members
+ ```
+
+- Locate a copy of your system's startup script, if your site has one (most do). The startup script can be a handy reference for restarting upgraded locators and servers with the same `gfsh` command lines that were used in your current installation.
+
+- Identify how your current cluster configuration was specified. The way in which your cluster
+ configuration was created determines which commands you use to save and restore that cluster
+ configuration during the upgrade procedure. There are two possibilites:
+
+ - With `gfsh` commands, relying on the underlying **cluster configuration service** to record the configuration: see [Exporting and Importing Cluster Configurations](../../configuring/cluster_config/export-import.html).
+ - With **XML properties** specified through the Java API or configuration files: see [Deploying Configuration Files without the Cluster Configuration Service](../../configuring/running/deploying_config_files.html).
+
+- Do not modify region attributes or data, either via `gfsh` or `cache.xml` configuration, during the upgrade process.
+
+- If possible, follow the [Rolling Upgrade](upgrade_rolling.html) procedure. A multi-site
+installation can also do rolling upgrades within each site. If a rolling upgrade is not possible,
+follow the [Off-Line Upgrade](upgrade_offline.html) procedure.
+A rolling upgrade is not possible for a cluster that has partitioned regions without redundancy.
+Without the redundancy, region entries will be lost when individual servers are taken out of the
+cluster during a rolling upgrade.
+
+## <a id="version_compatibilities" class="no-quick-link"></a>Version Compatibilities
+
+Your choice of upgrade procedure depends, in part, on the versions of <%=vars.product_name_long%> involved.
+
+- **Version Compatibility Between Peers and Cache Servers**
+
+ For best reliability and performance, all server components of a <%=vars.product_name%> system should run the same version of the software.
+ For the purposes of a rolling upgrade, you can have peers or cache servers running different minor
+ versions of <%=vars.product_name_long%> at the same time, as long as the major version is the same. For example,
+ some components can continue to run under version <%=vars.product_version_old_minor%> while you are in the process of upgrading to
+ version <%=vars.product_version%>.
+
+- **Version Compatibility Between Clients and Servers**
+
+ Client/server access is backward compatible. An <%=vars.product_name_long%> cluster can be accessed by clients using any previous version. However, clients
+ cannot connect to servers running older versions of <%=vars.product_name_long%>. For example, a client running <%=vars.product_name_long%> <%=vars.product_version_old_minor%> can access a cluster
+ running <%=vars.product_name_long%> <%=vars.product_version%>, but a client running <%=vars.product_name_long%> <%=vars.product_version%> could not connect to a cluster running <%=vars.product_name_long%> <%=vars.product_version_old_minor%>.
+
+- **Version Compatibility Between Sites in Multi-Site (WAN) Deployments**
+
+ In multi-site (WAN) deployments, sites should still be able to communicate with one another, even if they use different versions.
+
+## <a id="java-notes" class="no-quick-link"></a>Java Notes
+
+- To check your current Java version, type `java -version` at a command-line prompt.
+
+- <%=vars.product_name_long%> <%=vars.product_version%> requires Java SE 8, version 92 or a more recent version.
Review comment:
Actually, I think that this entire subsection (Java Notes) could be removed, and instead, add a bullet item in the _Guidelines for Upgrading_ that states that the upgrade planner should ensure that the machines hosting the cluster members meet the _Host Machine Requirements_ of the upgraded cluster.
----------------------------------------------------------------
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:
users@infra.apache.org