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:
[email protected]
