This is an automated email from the ASF dual-hosted git repository.
harikrishna pushed a commit to branch 4.20
in repository https://gitbox.apache.org/repos/asf/cloudstack-documentation.git
The following commit(s) were added to refs/heads/4.20 by this push:
new c3f0a0fc Doc update for MySQL 8.4 support (#629)
c3f0a0fc is described below
commit c3f0a0fcae1ef4c4b558f0f364235dcf66883ea7
Author: Suresh Kumar Anaparti <[email protected]>
AuthorDate: Tue Mar 10 10:55:33 2026 +0530
Doc update for MySQL 8.4 support (#629)
* Doc update for MySQL 8.4 support
* added steps to update authentication method to caching_sha2_password
* fix alignment
* some text improvements
* fix alignments
* changes
* move mysql upgrade details to mysql.rst
---
source/releasenotes/compat.rst | 2 +-
source/upgrading/upgrade/mysql.rst | 103 ++++++++++++++++++++++++++++-
source/upgrading/upgrade/upgrade_notes.rst | 32 +--------
3 files changed, 104 insertions(+), 33 deletions(-)
diff --git a/source/releasenotes/compat.rst b/source/releasenotes/compat.rst
index e77e2a06..b4e5af83 100644
--- a/source/releasenotes/compat.rst
+++ b/source/releasenotes/compat.rst
@@ -38,7 +38,7 @@ Software Requirements
~~~~~~~~~~~~~~~~~~~~~
- Java JRE 17
-- MySQL 8.0 (or equivalent compatible DBMS)
+- MySQL 8.4 (or equivalent compatible DBMS)
Supported Hypervisor Versions
-----------------------------
diff --git a/source/upgrading/upgrade/mysql.rst
b/source/upgrading/upgrade/mysql.rst
index ea9e8849..a0e611f4 100644
--- a/source/upgrading/upgrade/mysql.rst
+++ b/source/upgrading/upgrade/mysql.rst
@@ -13,8 +13,109 @@
specific language governing permissions and limitations
under the License.
+MySQL upgrade
+=============
+
+Explicit JDBC driver declaration
+--------------------------------
+
+While upgrading, on some environments the following may be required to be
+added in CloudStack's db.properties file:
+
+ # Add these to your db.properties file
+
+ db.cloud.driver=jdbc:mysql
+
+ db.usage.driver=jdbc:mysql
+
+MySQL support updated to 8.4
+----------------------------
+
+As of Apache CloudStack 4.20.3, support for MySQL 8.4 has been added.
+
+Existing deployments upgraded to version 4.20.3 can still continue using MySQL
8.0
+without any changes.
+
+If you are running MySQL 8.0 and would like to upgrade to MySQL 8.4,
+you may follow the standard MySQL upgrade process to migrate safely to version
8.4,
+and then update the authentication method for the root and CloudStack (cloud)
users with
+caching_sha2_password plugin using the below steps as the
mysql_native_password plugin
+is deprecated as of MySQL 8.0.34, and disabled by default in MySQL 8.4. For
more details,
+refer to MySQL documentation here:
https://dev.mysql.com/doc/refman/8.4/en/caching-sha2-pluggable-authentication.html
+
+#. Stop MySQL server if already running
+
+ .. code-block:: bash
+
+ sudo systemctl stop mysqld
+
+#. Start MySQL server in safe mode without auth
+
+ .. code-block:: bash
+
+ sudo mysqld --skip-grant-tables --skip-networking &
+
+#. Login to MySQL without password
+
+ .. code-block:: bash
+
+ mysql -u root
+
+#. Reset passwords for root and CloudStack (cloud) users.
+
+ .. code-block:: mysql
+
+ ALTER USER 'root'@'localhost' IDENTIFIED WITH caching_sha2_password BY
'ROOT_PASSWORD';
+ ALTER USER 'root'@'%' IDENTIFIED WITH caching_sha2_password BY
'ROOT_PASSWORD';
+ ALTER USER 'cloud'@'localhost' IDENTIFIED WITH caching_sha2_password BY
'CLOUD_PASSWORD';
+ ALTER USER 'cloud'@'%' IDENTIFIED WITH caching_sha2_password BY
'CLOUD_PASSWORD';
+ FLUSH PRIVILEGES;
+
+ Note: Please ensure that the password used for the cloud database user
matches the value
+ configured in /etc/cloudstack/management/db.properties. If the password in
db.properties
+ is encrypted, you can retrieve it using the below command.
+
+ .. code-block:: bash
+
+ java -classpath /usr/share/cloudstack-common/lib/cloudstack-utils.jar \
+ com.cloud.utils.crypt.EncryptionCLI -d \
+ -i "$(grep -oP 'db.cloud.password=ENC\(\K[^\)]+(?=\))'
/etc/cloudstack/management/db.properties)" \
+ -p "$(cat /etc/cloudstack/management/key)"
+
+#. Remove deprecated authentication plugin 'mysql_native_password' from the
MySQL configuration. Either comment or remove the below line from /etc/my.cnf
+
+ .. parsed-literal::
+
+ default_authentication_plugin=mysql_native_password
+
+#. Restart MySQL server
+
+ .. code-block:: bash
+
+ killall mysqld
+ systemctl start mysqld
+
+MySQL 8.0+ sql mode change
+--------------------------
+
+MySQL mode (sql_mode) has changed in CloudStack db.properties to
+"STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,
+ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION".
+
+This gets automatically applies to the MySQL session used by CloudStack
management server.
+
+If the admin uses MySQL directly and wants to query tables it is advised to
change the sql_mode in the corresponding session or globally.
+
+Eg. mysql> set global
sql_mode="STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,
+ ">
ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION";
+ Query OK, 0 rows affected (0.00 sec)
+
+ mysql> set sql_mode="STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,
+ "> ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION";
+ Query OK, 0 rows affected (0.00 sec)
+
MySQL upgrade problems
-======================
+----------------------
With certain MySQL versions (see below), issues have been seen with
"cloud.nics" table's
column type (which was not updated properly during CloudStack upgrades, due to
MySQL limitations),
diff --git a/source/upgrading/upgrade/upgrade_notes.rst
b/source/upgrading/upgrade/upgrade_notes.rst
index 44935891..c433e872 100644
--- a/source/upgrading/upgrade/upgrade_notes.rst
+++ b/source/upgrading/upgrade/upgrade_notes.rst
@@ -108,34 +108,4 @@ SystemVM 32bit deprecated
32bit versions of System VM Templates are in the process of being deprecated.
Upgrade instructions from this Release Notes use 64bit Templates.
-Explicit JDBC driver declaration
---------------------------------
-
-While upgrading, on some environments the following may be required to be
-added in CloudStack's db.properties file:
-
- # Add these to your db.properties file
-
- db.cloud.driver=jdbc:mysql
-
- db.usage.driver=jdbc:mysql
-
-
-MySQL 8.0 sql mode change
--------------------------
-
-MySQL mode (sql_mode) has changed in CloudStack db.properties to
-"STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,
-ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION".
-
-This gets automatically applies to the MySQL session used by CloudStack
management server.
-
-If the admin uses MySQL directly and wants to query tables it is advised to
change the sql_mode in the corresponding session or globally.
-
-Eg. mysql> set global
sql_mode="STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,
- ">
ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION";
- Query OK, 0 rows affected (0.00 sec)
-
- mysql> set sql_mode="STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,
- "> ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION";
- Query OK, 0 rows affected (0.00 sec)
\ No newline at end of file
+.. include:: mysql.rst
