PXC-4611 [DOCS] - update PXC 8.4 upgrade docs

modified: docs/upgrade-from-backup.md modified: docs/upgrade-guide.md
percona · Jan 21, 2025 · c4dd42c · c4dd42c
1 parent a8ed3fa
commit c4dd42c
Show file tree

Hide file tree

Showing 2 changed files with 5 additions and 107 deletions.
diff --git a/docs/upgrade-from-backup.md b/docs/upgrade-from-backup.md
@@ -1,11 +1,9 @@
 <!--------- Ask whether we need to change this doc --------->
 
-# Restore a 5.7 backup to an 8.0 cluster
+# Restore 8.0 backup to 8.4 cluster
 
 Use Percona XtraBackup to back up the source server data and restore the data to a target server, and then upgrade the server to a different version of Percona XtraDB Cluster.
 
-[Downgrading is not supported](https://docs.percona.com/percona-server/8.0/downgrade.html).
-
 ## Restore a database with a different server version
 
 Review [Upgrade Percona XtraDB cluster](upgrade-guide.md).

diff --git a/docs/upgrade-guide.md b/docs/upgrade-guide.md
@@ -1,113 +1,13 @@
-<!--------- Ask whether we need this doc or how to change it--------->
 
-# Upgrade Percona XtraDB Cluster
-
-<!-- This guide describes the procedure for upgrading Percona XtraDB Cluster without downtime
-(*rolling upgrade*) to the Percona XtraDB Cluster 8.0. -->
-<!-- A "rolling upgrade" means there is no need to take down the complete
-cluster during the upgrade. -->
-
-The following documents contain details about relevant changes in the 8.0 series
-of MySQL and Percona Server for MySQL. Make sure you deal with any incompatible features
-and variables mentioned in these documents when upgrading to Percona XtraDB Cluster 8.0.
-
-- [Upgrading MySQL](http://dev.mysql.com/doc/refman/8.0/en/upgrading.html)
-
-- [Upgrading from MySQL 5.7 to 8.0](https://dev.mysql.com/doc/refman/8.0/en/upgrading-from-previous-series.html)
-
-## Important changes in Percona XtraDB Cluster 8.0
-
-- [Upgrade Percona XtraDB Cluster](#upgrade-percona-xtradb-cluster)
-  - [Important changes in Percona XtraDB Cluster 8.0](#important-changes-in-percona-xtradb-cluster-80)
-    - [Traffic encryption is enabled by default](#traffic-encryption-is-enabled-by-default)
-    - [Not recommended to mix PXC 5.7 nodes with PXC 8.0 nodes](#not-recommended-to-mix-pxc-57-nodes-with-pxc-80-nodes)
-    - [PXC strict mode is enabled by default](#strict-mode-is-enabled-by-default)
-    - [The configuration file layout has changed in PXC 8.0](#the-configuration-file-layout-has-changed-in-pxc-80)
-    - [caching_sha2_password is the default authentication plugin](#caching_sha2_password-is-the-default-authentication-plugin)
-    - [mysql_upgrade is part of SST](#mysql_upgrade-is-part-of-sst)
-  - [Major upgrade scenarios](#major-upgrade-scenarios)
-    - [Scenario: No active parallel workload or with read-only workload](#scenario-no-active-parallel-workload-or-with-read-only-workload)
-    - [Scenario: Upgrade from PXC 5.6 to PXC 8.0](#scenario-upgrade-from-pxc-56-to-pxc-80)
-  - [Minor upgrade](#minor-upgrade)
-
-### Traffic encryption is enabled by default
-
-The `pxc_encrypt_cluster_traffic` variable, which enables traffic
-encryption, is set to `ON` by default in Percona XtraDB Cluster 8.0.
-
-Unless you configure a node accordingly (each node in your cluster must use the
-same SSL certificates) or try to join a cluster running PXC 5.7 which
-unencrypted cluster traffic, the node will not be able to join resulting in an
-error.
-
-??? example "The error message"
-
-    ```{.text .no-copy}
-    ... [ERROR] ... [Galera] handshake with remote endpoint ...
-    This error is often caused by SSL issues. ...
-    ```
-
-!!! admonition "See also"
-
-    sections [Encrypting PXC Traffic](encrypt-traffic.md#encrypt-traffic), [Configuring Nodes for Write-Set Replication](configure-nodes.md#configure)
-
-## <!-- Rolling upgrades to |version| from versions older than 5.7 are not supported
 
-Therefore, if you are running Percona XtraDB Cluster version 5.6, shut down all
-nodes, then remove and re-create the cluster from scratch. Alternatively,
-you can perform a `rolling upgrade from PXC 5.6 to 5.7 <https://www.percona.com/doc/percona-xtradb-cluster/5.7/howtos/upgrade_guide.html>`\_.
-and then follow the current procedure to upgrade from 5.7 to 8.0. -->
-
-### Not recommended to mix PXC 5.7 nodes with PXC 8.0 nodes
-
-Shut down the cluster and upgrade each node to PXC 8.0. It is
-important that you make backups before attempting an upgrade.
-
-<!-- If downtime is acceptable
-Shut down the cluster and upgrade all nodes to PXC
-8.0. It is important that you make backups before attempting an upgrade. -->
-<!-- If downtime is not possible
-The rolling upgrade is supported but ensure the
-traffic is controlled during the upgrade and writes are directed only to 5.7
-nodes until all nodes are upgraded to 8.0. -->
-
-### PXC strict mode is enabled by default
-
-Percona XtraDB Cluster in 8.0 runs with [PXC Strict Mode](strict-mode.md#pxc-strict-mode) enabled by default. This will deny any unsupported operations and may halt the server if [a strict mode validation fails](strict-mode.md#validations). It is recommended to first start the node with
-the `pxc_strict_mode` variable set to `PERMISSIVE` in the MySQL
-configuration file.
-
-All configuration settings are stored in the default MySQL configuration file:
-
-- Path on Debian and Ubuntu: `/etc/mysql/mysql.conf.d/mysqld.cnf`
-
-* Path on Red Hat Enterprise Linux: `/etc/my.cnf`
-
-After you check the log for any tech preview features or unsupported features
-and you have fixed any of the encountered incompatibilities, set the variable
-back to `ENFORCING` at run time:
-
-```{.bash data-prompt="mysql>"}
-mysql> SET pxc_strict_mode=ENFORCING;
-```
-
-Restarting the node with the updated configuration file also sets variable to `ENFORCING`.
-
-### The configuration file layout has changed in PXC 8.0
-
-All configuration settings are stored in the default MySQL configuration file:
-
-- Path on Debian and Ubuntu: `/etc/mysql/mysql.conf.d/mysqld.cnf`
+# Upgrade Percona XtraDB Cluster
 
-* Path on Red Hat Enterprise Linux: /etc/my.cnf
+You must make backups before attempting an upgrade.
 
-Before you start the upgrade, move your custom settings from
-`/etc/mysql/percona-xtradb-cluster.conf.d/wsrep.cnf` (on Debian and
-Ubuntu) or from `/etc/percona-xtradb-cluster.conf.d/wsrep.cnf` (on Red Hat Enterprise Linux) to the new location accordingly.
+This guide explains how to upgrade a Percona XtraDB Cluster to version 8.4 without causing downtime. This process is called a “rolling upgrade,” which means you can upgrade the cluster one node at a time without shutting down the whole cluster. Keep in mind that rolling upgrades to 8.4 are only supported if your current version is 8.0 or newer.
 
-!!! note
+If you are using Percona XtraDB Cluster 5.7, it’s best to shut down all the nodes, remove the cluster, and create it again from scratch. Another option is to do a rolling upgrade from PXC 5.7 to 8.0 first. Once that’s done, you can follow the current steps to upgrade from 8.0 to 8.4.
 
-    If you have moved your my.cnf file to a different location and added a symlink to `/etc/my.cnf`, the RPM package manager, when upgrading, can delete the symlink and put a default my.cnf file in /etc/.
 
 ### caching_sha2_password is the default authentication plugin