You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@geode.apache.org by db...@apache.org on 2021/03/18 19:27:07 UTC
[geode] branch support/1.14 updated: GEODE-8946: User Guide - add
an Upgrade section (#6134)
This is an automated email from the ASF dual-hosted git repository.
dbarnes pushed a commit to branch support/1.14
in repository https://gitbox.apache.org/repos/asf/geode.git
The following commit(s) were added to refs/heads/support/1.14 by this push:
new c661e2c GEODE-8946: User Guide - add an Upgrade section (#6134)
c661e2c is described below
commit c661e2c4b437bb7514772cb57ca495f6527612b9
Author: Dave Barnes <db...@apache.org>
AuthorDate: Thu Mar 18 12:07:36 2021 -0700
GEODE-8946: User Guide - add an Upgrade section (#6134)
* GEODE-8946: User Guide - add an Upgrade section
---
geode-book/config.yml | 1 +
.../source/subnavs/geode-subnav.erb | 17 ++
.../running/cluster-management-service.html.md.erb | 2 +-
.../upgrade/upgrade_clients.html.md.erb | 38 ++++
.../upgrade/upgrade_offline.html.md.erb | 109 +++++++++++
.../upgrade/upgrade_overview.html.md.erb | 56 ++++++
.../upgrade/upgrade_planning.html.md.erb | 81 ++++++++
.../upgrade/upgrade_rolling.html.md.erb | 218 +++++++++++++++++++++
8 files changed, 521 insertions(+), 1 deletion(-)
diff --git a/geode-book/config.yml b/geode-book/config.yml
index b3d2bda..3bb97e7 100644
--- a/geode-book/config.yml
+++ b/geode-book/config.yml
@@ -31,6 +31,7 @@ template_variables:
product_version: '1.14.0'
product_version_nodot: '114'
product_version_geode: '1.14'
+ product_version_old_minor: '1.13'
min_java_version: '8'
min_java_update: '121'
support_url: http://geode.apache.org/community
diff --git a/geode-book/master_middleman/source/subnavs/geode-subnav.erb b/geode-book/master_middleman/source/subnavs/geode-subnav.erb
index 68ae2bb..fa0f050 100644
--- a/geode-book/master_middleman/source/subnavs/geode-subnav.erb
+++ b/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>
<li>
<a href="/docs/guide/<%=vars.product_version_nodot%>/getting_started/15_minute_quickstart_gfsh.html">Apache Geode in 15 Minutes or Less</a>
</li>
diff --git a/geode-docs/configuring/running/cluster-management-service.html.md.erb b/geode-docs/configuring/running/cluster-management-service.html.md.erb
index ae63e75..582a590 100644
--- a/geode-docs/configuring/running/cluster-management-service.html.md.erb
+++ b/geode-docs/configuring/running/cluster-management-service.html.md.erb
@@ -49,7 +49,7 @@ so users can use POST, PATCH, DELETE, and GET to create,
update, delete, and read, respectively.
See the versioned documentation at [Cluster Management Service REST API](https://cwiki.apache.org/confluence/display/GEODE/Cluster+Management+Service+Rest+API) for more details.
-This version of <%=vars.product_name%> uses the [<%=vars.product_version_geode%>.0 Management REST API](https://cwiki.apache.org/confluence/display/GEODE/<%=vars.product_version_geode%>.0+Management+REST+API+-+v1).
+This version of <%=vars.product_name%> uses the <%=vars.product_version_geode%> Management REST API.
## Cluster Management Configuration
diff --git a/geode-docs/getting_started/upgrade/upgrade_clients.html.md.erb b/geode-docs/getting_started/upgrade/upgrade_clients.html.md.erb
new file mode 100644
index 0000000..38a909a
--- /dev/null
+++ b/geode-docs/getting_started/upgrade/upgrade_clients.html.md.erb
@@ -0,0 +1,38 @@
+---
+title: Upgrading Clients
+---
+
+<!--
+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.
+-->
+
+When you upgrade your <%=vars.product_name%> server software, you will likely need to update your client applications in order to maintain
+compatibility with the upgraded servers. To support real-world implementations, servers can usually interoperate with a few
+different versions of the client software. In general, you will have best performance and reliability if:
+
+- All clients run the same version of the client software.
+- Clients and servers both run the latest versions of their respective software.
+
+Changes you may need to make when you update, recompile, and link your client code include:
+
+- Removing or replacing obsolete identifiers
+- Reinstating secure client/server messaging
+
+## <a id="remove-replace-obsolete-identifiers" class="no-quick-link"></a>Remove or Replace Obsolete Identifiers
+
+Review the Release Notes for a list of classes, methods, and other identifiers that are no longer present in the current release.
+Update client code so it no longer uses any of these removed identifiers.
+
diff --git a/geode-docs/getting_started/upgrade/upgrade_offline.html.md.erb b/geode-docs/getting_started/upgrade/upgrade_offline.html.md.erb
new file mode 100644
index 0000000..95685a8
--- /dev/null
+++ b/geode-docs/getting_started/upgrade/upgrade_offline.html.md.erb
@@ -0,0 +1,109 @@
+---
+title: Offline 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.
+-->
+
+Use the offline upgrade procedure when you cannot, or choose not to, perform a rolling upgrade.
+For example, a rolling upgrade is not possible for a cluster that has partitioned regions without redundancy.
+(Without the redundancy, region entries would be lost when individual servers were taken out of the cluster during a rolling upgrade.)
+
+## <a id="offline-upgrade-guidelines" class="no-quick-link"></a>Offline Upgrade Guidelines
+
+**Versions**
+
+For best reliability and performance, all server components of a <%=vars.product_name%> system should run the same version of the software.
+See [Version Compatibilities](upgrade_planning.html#version_compatibilities) for more details on how different versions of <%=vars.product_name%> can interoperate.
+
+**Data member interdependencies**
+
+When you restart your upgraded servers, interdependent data members may hang on startup waiting for each other. In this case, start the servers in
+separate command shells so they can start simultaneously and communicate with one another to resolve dependencies.
+
+## <a id="offline-upgrade-procedure" class="no-quick-link"></a>Offline Upgrade Procedure
+
+1. Stop any connected clients.
+
+1. On a machine hosting a locator, open a terminal console.
+
+1. Start a `gfsh` prompt, using the version from your current <%=vars.product_name%> installation, and connect to a currently running locator.
+ For example:
+
+ ``` pre
+ gfsh>connect --locator=locator_hostname_or_ip_address[port]
+ ```
+
+1. Use `gfsh` commands to characterize your current installation so you can compare your post-upgrade system to the current one.
+For example, use the `list members` command to view locators and data members:
+
+ ```
+ Name | Id
+ -------- | ------------------------------------------------
+ locator1 | 172.16.71.1(locator1:26510:locator)<ec><v0>:1024
+ locator2 | 172.16.71.1(locator2:26511:locator)<ec><v1>:1025
+ server1 | 172.16.71.1(server1:26514)<v2>:1026
+ server2 | 172.16.71.1(server2:26518)<v3>:1027
+ ```
+
+1. Save your cluster configuration.
+ - If you are using the cluster configuration service, use the gfsh `export cluster-configuration` command. You only need to do this once, as the newly-upgraded locator will propagate the configuration to newly-upgraded members as they come online.
+ - For an XML configuration, save `cache.xml`, `gemfire.properties`, and any other relevant configuration files to a well-known location. You must repeat this step for each member you upgrade.
+
+1. Shut down the entire cluster (by pressing Y at the prompt, this will lose no persisted data):
+
+ ``` pre
+ gfsh>shutdown --include-locators=true
+ As a lot of data in memory will be lost, including possibly events in queues, do you really want to shutdown the entire distributed system? (Y/n): y
+ Shutdown is triggered
+
+ gfsh>
+ No longer connected to 172.16.71.1[1099].
+ gfsh>quit
+ ```
+
+ Since <%=vars.product_name%> is a Java process, to check before continuing that all <%=vars.product_name%> members successfully stopped,
+it is useful to use the JDK-included `jps` command to check running java processes:
+
+ ``` pre
+ % jps
+ 29664 Jps
+ ```
+
+1. On each machine in the cluster, install the new version of the software (alongside the older version of the software).
+
+1. Redeploy your environment's configuration files to the new version installation. If you are using the cluster configuration service, one copy of the exported `.zip` configuration file is sufficient, as the first upgraded locator will propagate it to the other members.
+For XML configurations, you should have a copy of the saved configuration files for each data member.
+
+1. On each machine in the cluster, install any updated server code. Point all client applications to the new installation of <%=vars.product_name%>.
+
+1. Run the new version of `gfsh`.
+
+1. Start a locator and import the saved configuration. If you are using the cluster configuration service, use the same name and directory as the older version you stopped, and the new locator will access the old locator's cluster configuration without having to import it in a separate step:
+
+ ```
+ gfsh>start locator --name=locator1 --enable-cluster-configuration=true --dir=/data/locator1
+ ```
+
+ Otherwise, use the gfsh `import cluster-configuration` command or explicitly import `.xml` and `.properties` files, as appropriate.
+
+1. Restart all system data members using the new version of gfsh. Use the same names, directories, and other properties that
+were used when starting the system under the previous version of the software. (Here is where a system startup script comes in
+handy as a reference.) Interdependent data members may hang on startup waiting for each other. In this case, start servers in
+separate shells so they can communicate with one another to resolve dependencies.
+
+1. Upgrade <%=vars.product_name%> clients, following the guidelines described in [Upgrading Clients](upgrade_clients.html).
diff --git a/geode-docs/getting_started/upgrade/upgrade_overview.html.md.erb b/geode-docs/getting_started/upgrade/upgrade_overview.html.md.erb
new file mode 100644
index 0000000..cfecad3
--- /dev/null
+++ b/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 cluster 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 cluster 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 cluster running while you upgrade your members gradually.
+
+- **[Offline Upgrade](upgrade_offline.html)**
+
+ An offline upgrade can handle the widest variety of software versions and cluster configurations, but requires shutting down the entire
+ system for at least a short time.
+
+- **[Upgrading Clients](upgrade_clients.html)**
+
diff --git a/geode-docs/getting_started/upgrade/upgrade_planning.html.md.erb b/geode-docs/getting_started/upgrade/upgrade_planning.html.md.erb
new file mode 100644
index 0000000..68a605d
--- /dev/null
+++ b/geode-docs/getting_started/upgrade/upgrade_planning.html.md.erb
@@ -0,0 +1,81 @@
+---
+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.
+- Verify that the machines hosting the cluster members meet the [Host Machine Requirements](../system_requirements/host_machine.html) of the upgraded cluster.
+- **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 cluster or, if allowed to join, can potentially cause a deadlock.
+- Verify that all members that you wish to upgrade are members of the same 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.
diff --git a/geode-docs/getting_started/upgrade/upgrade_rolling.html.md.erb b/geode-docs/getting_started/upgrade/upgrade_rolling.html.md.erb
new file mode 100644
index 0000000..ee78b2d
--- /dev/null
+++ b/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 cluster 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, cache servers, and locators within a cluster.
+Under some circumstances, rolling upgrades can also be applied within individual sites of multi-site (WAN) deployments.
+
+**Redundancy**
+
+All partitioned regions in your system must have full redundancy.
+Check the redundancy state of all your regions *before* you begin the rolling upgrade and *before* stopping any members.
+See [Checking Redundancy in Partitioned Regions](../../developing/partitioned_regions/checking_region_redundancy.html) for details.
+
+If a rolling update is not possible for your system, follow the [Off-Line Upgrade](upgrade_offline.html) procedure.
+
+## <a id="rolling-upgrade-guidelines" class="no-quick-link"></a>Rolling Upgrade Guidelines
+
+**Do not create or destroy regions**
+
+When you perform a rolling upgrade, your online cluster will have a mix of members running different versions of <%=vars.product_name%>.
+During this time period, do not execute region operations such as region creation or region destruction.
+
+**Region rebalancing affects the restart process**
+
+If you have `startup-recovery-delay` disabled (set to -1) for your partitioned region, you will need to perform a rebalance on your
+region after you restart each member.
+If rebalance occurs automatically, as it will if `startup-recovery-delay` is enabled (set to a value other than -1), make sure that the rebalance completes before you stop the next server.
+If you have `startup-recovery-delay` enabled and set to a high number, you may need to wait extra time until the region has recovered redundancy, because rebalance must complete before new servers are restarted.
+The partitioned region attribute `startup-recovery-delay` is described in [Configure Member Join Redundancy Recovery for a Partitioned Region](../../developing/partitioned_regions/set_join_redundancy_recovery.html).
+
+**Checking component versions while upgrading**
+
+During a rolling upgrade, you can check the current <%=vars.product_name%> version of all members in the cluster by looking at the server or locator logs.
+
+ When an upgraded member reconnects to the cluster, it logs all the members it can see as well as the <%=vars.product_name%> version of those members. For example, an upgraded locator will now detect <%=vars.product_name%> members running the older version of <%=vars.product_name%> (in this case, the version being upgraded, GEODE 1.2.0):
+
+``` pre
+[info 2013/06/03 10:03:29.206 PDT frodo <vm_1_thr_1_frodo> tid=0x1a] DistributionManager frodo(locator1:21869:locator)<v16>:28242 started on frodo[15001]. There
+ were 2 other DMs. others: [frodo(server2:21617)<v4>:14973( version:GEODE 1.2.0 ), frodo(server1:21069)<v1>:60929( version:Geode 1.2.0 )] (locator)
+```
+
+After some members have been upgraded, non-upgraded members will log the following message when they receive a new membership view:
+
+``` pre
+Membership: received new view [frodo(locator1:20786)<v0>:32240|4]
+ [frodo(locator1:20786)<v0>:32240/51878, frodo(server1:21069)<v1>:60929/46949,
+ frodo(server2:21617)<v4>( version:UNKNOWN[ordinal=23] ):14973/33919]
+```
+
+ Non-upgraded members identify members that have been upgraded to the next version with `version: UNKNOWN`.
+
+**Cluster configuration affects save and restore**
+
+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.
+
+ - If your system was configured with `gfsh` commands, relying on the underlying **cluster configuration service**, the configuration can be saved in one central location, then applied to all newly-upgraded members. See [Exporting and Importing Cluster Configurations](../../configuring/cluster_config/export-import.html).
+ - If your system was configured with **XML properties** specified through the Java API or configuration files, you must save the configuration for each member before you bring it down, then re-import it for that member's upgraded counterpart. See [Deploying Configuration Files without the Cluster Configuration Service](../../configuring/running/deploying_config_files.html).
+
+## <a id="rolling-upgrade-procedure" class="no-quick-link"></a>Rolling Upgrade Procedure
+
+Begin by installing the new version of the software alongside the older version of the software on all hosts. You will need both versions of the software during the upgrade procedure.
+
+Upgrade locators first, then data members, then clients.
+
+### <a id="upgrade-locators" class="no-quick-link"></a>Upgrade Locators
+
+1. On the machine hosting the first locator you wish to upgrade, open a terminal console.
+
+2. Start a `gfsh` prompt, using the version from your current <%=vars.product_name%> installation, and connect to the currently running locator.
+ For example:
+
+ ``` pre
+ gfsh>connect --locator=locator_hostname_or_ip_address[port]
+ ```
+
+3. Use `gfsh` commands to characterize your current installation so you can compare your post-upgrade system to the current one.
+For example, use the `list members` command to view locators and data members:
+
+ ```
+ Name | Id
+ -------- | ------------------------------------------------
+ locator1 | 172.16.71.1(locator1:26510:locator)<ec><v0>:1024
+ locator2 | 172.16.71.1(locator2:26511:locator)<ec><v1>:1025
+ server1 | 172.16.71.1(server1:26514)<v2>:1026
+ server2 | 172.16.71.1(server2:26518)<v3>:1027
+ ```
+
+4. Save your cluster configuration.
+ - If you are using the cluster configuration service, use the gfsh `export cluster-configuration` command. You only need to do this once, as the newly-upgraded locator will propagate the configuration to newly-upgraded members as they come online.
+ - For an XML configuration, save `cache.xml`, `gemfire.properties`, and any other relevant configuration files to a well-known location. You must repeat this step for each member you upgrade.
+
+5. Stop the locator. For example:
+
+ ``` pre
+ gfsh>stop locator --name=locator1
+ Stopping Locator running in /Users/username/sandbox/locator on 172.16.71.1[10334] as locator...
+ Process ID: 96686
+ Log File: /Users/username/sandbox/locator/locator.log
+ ....
+ No longer connected to 172.16.71.1[1099].
+ ```
+6. Start `gfsh` from the new <%=vars.product_name%> installation.
+ Verify that you are running the newer version with
+
+ ``` pre
+ gfsh>version
+ ```
+
+7. Start a locator and import the saved configuration. If you are using the cluster configuration service, use the same name and directory as the older version you stopped, and the new locator will access the old locator's cluster configuration without having to import it in a separate step:
+
+ ```
+ gfsh>start locator --name=locator1 --enable-cluster-configuration=true --dir=/data/locator1
+ ```
+
+ Otherwise, use the gfsh `import cluster-configuration` command or explicitly import `.xml` and `.properties` files, as appropriate.
+
+8. The new locator should reconnect to the same members as the older locator. Use `list members` to verify:
+
+ ```
+ gfsh>list members
+ Name | Id
+ -------- | ----------------------------------------------------
+ locator1 | 172.16.71.1(locator1:26752:locator)<ec><v17>:1024(version:UNKNOWN[ordinal=65])
+ locator2 | 172.16.71.1(locator2:26511:locator)<ec><v1>:1025
+ server1 | 172.16.71.1(server1:26514)<v2>:1026
+ server2 | 172.16.71.1(server2:26518)<v3>:1027
+ ```
+
+9. Upgrade the remaining locators by stopping and restarting them. When you have completed that step, the system gives a more coherent view of version numbers:
+
+ ```
+ gfsh>list members
+ Name | Id
+ -------- | ----------------------------------------------------
+ locator1 | 172.16.71.1(locator1:26752:locator)<ec><v17>:1024
+ locator2 | 172.16.71.1(locator2:26808:locator)<ec><v30>:1025
+ server1 | 172.16.71.1(server1:26514)<v2>:1026(version:GEODE 1.2)
+ server2 | 172.16.71.1(server2:26518)<v3>:1027(version:GEODE 1.2)
+ ```
+
+ The server entries show that the servers are running an older version of <%=vars.product_name%>, in this case `(version:GEODE 1.2)`.
+
+### <a id="upgrade-servers" class="no-quick-link"></a>Upgrade Servers
+
+After you have upgraded all of the system's locators, upgrade the servers.
+
+1. Upgrade each server, one at a time, by stopping it and restarting it. Restart the server with the same command-line options with which it was originally started in the previous installation. For example:
+
+ ```
+ gfsh>stop server --name=server1
+ Stopping Cache Server running in /Users/share/server1 on 172.16.71.1[52139] as server1...
+
+ gfsh>start server --name=server1 --use-cluster-configuration=true --server-port=0 --dir=/data/server1
+ Starting a Geode Server in /Users/share/server1...
+ ```
+
+ Use the `list members` command to verify that the server is now running the new version of <%=vars.product_name%>:
+
+ ```
+ gfsh>list members
+ Name | Id
+ -------- | ----------------------------------------------------
+ locator1 | 172.16.71.1(locator1:26752:locator)<ec><v17>:1024
+ locator2 | 172.16.71.1(locator2:26808:locator)<ec><v30>:1025
+ server1 | 172.16.71.1(server1:26835)<v32>:1026
+ server2 | 172.16.71.1(server2:26518)<v3>:1027(version:GEODE 1.2)
+ ```
+
+2. Restore data to the data member. If automatic rebalancing is enabled (partitioned region
+ attribute `startup-recovery-delay` is set to a value other than -1), data restoration will start
+ automatically. If automatic rebalancing is disabled (partitioned region attribute
+ `startup-recovery-delay=-1`), you must initiate data restoration by issuing the gfsh `rebalance`
+ command.
+
+ Wait until the newly-started server has been restored before upgrading the next server. You can repeat various gfsh
+ `show metrics` command with the `--member` option or the `--region` option to verify that the data member is hosting data and that
+ the amount of data it is hosting has stabilized.
+
+3. Shut down,restart, and rebalance servers until all data members are running the new version of <%=vars.product_name%>.
+
+### <a id="upgrade-clients" class="no-quick-link"></a>Upgrade Clients
+
+Upgrade <%=vars.product_name%> clients, following the guidelines described in [Upgrading Clients](upgrade_clients.html).