Skip to content

Commit c3f0a0f

Browse files
sureshanapartisureshanaparti
authored
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
1 parent 9b9c0c1 commit c3f0a0f

File tree

3 files changed

+104
-33
lines changed

3 files changed

+104
-33
lines changed

‎source/releasenotes/compat.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ Software Requirements
3838
~~~~~~~~~~~~~~~~~~~~~
3939

4040
- Java JRE 17
41-
- MySQL 8.0 (or equivalent compatible DBMS)
41+
- MySQL 8.4 (or equivalent compatible DBMS)
4242

4343
Supported Hypervisor Versions
4444
-----------------------------

‎source/upgrading/upgrade/mysql.rst‎

Lines changed: 102 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,109 @@
1313
specific language governing permissions and limitations
1414
under the License.
1515
16+
MySQL upgrade
17+
=============
18+
19+
Explicit JDBC driver declaration
20+
--------------------------------
21+
22+
While upgrading, on some environments the following may be required to be
23+
added in CloudStack's db.properties file:
24+
25+
# Add these to your db.properties file
26+
27+
db.cloud.driver=jdbc:mysql
28+
29+
db.usage.driver=jdbc:mysql
30+
31+
MySQL support updated to 8.4
32+
----------------------------
33+
34+
As of Apache CloudStack 4.20.3, support for MySQL 8.4 has been added.
35+
36+
Existing deployments upgraded to version 4.20.3 can still continue using MySQL 8.0
37+
without any changes.
38+
39+
If you are running MySQL 8.0 and would like to upgrade to MySQL 8.4,
40+
you may follow the standard MySQL upgrade process to migrate safely to version 8.4,
41+
and then update the authentication method for the root and CloudStack (cloud) users with
42+
caching_sha2_password plugin using the below steps as the mysql_native_password plugin
43+
is deprecated as of MySQL 8.0.34, and disabled by default in MySQL 8.4. For more details,
44+
refer to MySQL documentation here: https://dev.mysql.com/doc/refman/8.4/en/caching-sha2-pluggable-authentication.html
45+
46+
#. Stop MySQL server if already running
47+
48+
.. code-block:: bash
49+
50+
sudo systemctl stop mysqld
51+
52+
#. Start MySQL server in safe mode without auth
53+
54+
.. code-block:: bash
55+
56+
sudo mysqld --skip-grant-tables --skip-networking &
57+
58+
#. Login to MySQL without password
59+
60+
.. code-block:: bash
61+
62+
mysql -u root
63+
64+
#. Reset passwords for root and CloudStack (cloud) users.
65+
66+
.. code-block:: mysql
67+
68+
ALTER USER 'root'@'localhost' IDENTIFIED WITH caching_sha2_password BY 'ROOT_PASSWORD';
69+
ALTER USER 'root'@'%' IDENTIFIED WITH caching_sha2_password BY 'ROOT_PASSWORD';
70+
ALTER USER 'cloud'@'localhost' IDENTIFIED WITH caching_sha2_password BY 'CLOUD_PASSWORD';
71+
ALTER USER 'cloud'@'%' IDENTIFIED WITH caching_sha2_password BY 'CLOUD_PASSWORD';
72+
FLUSH PRIVILEGES;
73+
74+
Note: Please ensure that the password used for the cloud database user matches the value
75+
configured in /etc/cloudstack/management/db.properties. If the password in db.properties
76+
is encrypted, you can retrieve it using the below command.
77+
78+
.. code-block:: bash
79+
80+
java -classpath /usr/share/cloudstack-common/lib/cloudstack-utils.jar \
81+
com.cloud.utils.crypt.EncryptionCLI -d \
82+
-i "$(grep -oP 'db.cloud.password=ENC\(\K[^\)]+(?=\))' /etc/cloudstack/management/db.properties)" \
83+
-p "$(cat /etc/cloudstack/management/key)"
84+
85+
#. Remove deprecated authentication plugin 'mysql_native_password' from the MySQL configuration. Either comment or remove the below line from /etc/my.cnf
86+
87+
.. parsed-literal::
88+
89+
default_authentication_plugin=mysql_native_password
90+
91+
#. Restart MySQL server
92+
93+
.. code-block:: bash
94+
95+
killall mysqld
96+
systemctl start mysqld
97+
98+
MySQL 8.0+ sql mode change
99+
--------------------------
100+
101+
MySQL mode (sql_mode) has changed in CloudStack db.properties to
102+
"STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,
103+
ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION".
104+
105+
This gets automatically applies to the MySQL session used by CloudStack management server.
106+
107+
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.
108+
109+
Eg. mysql> set global sql_mode="STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,
110+
"> ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION";
111+
Query OK, 0 rows affected (0.00 sec)
112+
113+
mysql> set sql_mode="STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,
114+
"> ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION";
115+
Query OK, 0 rows affected (0.00 sec)
116+
16117
MySQL upgrade problems
17-
======================
118+
----------------------
18119

19120
With certain MySQL versions (see below), issues have been seen with "cloud.nics" table's
20121
column type (which was not updated properly during CloudStack upgrades, due to MySQL limitations),

‎source/upgrading/upgrade/upgrade_notes.rst‎

Lines changed: 1 addition & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -108,34 +108,4 @@ SystemVM 32bit deprecated
108108

109109
32bit versions of System VM Templates are in the process of being deprecated. Upgrade instructions from this Release Notes use 64bit Templates.
110110

111-
Explicit JDBC driver declaration
112-
--------------------------------
113-
114-
While upgrading, on some environments the following may be required to be
115-
added in CloudStack's db.properties file:
116-
117-
# Add these to your db.properties file
118-
119-
db.cloud.driver=jdbc:mysql
120-
121-
db.usage.driver=jdbc:mysql
122-
123-
124-
MySQL 8.0 sql mode change
125-
-------------------------
126-
127-
MySQL mode (sql_mode) has changed in CloudStack db.properties to
128-
"STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,
129-
ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION".
130-
131-
This gets automatically applies to the MySQL session used by CloudStack management server.
132-
133-
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.
134-
135-
Eg. mysql> set global sql_mode="STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,
136-
"> ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION";
137-
Query OK, 0 rows affected (0.00 sec)
138-
139-
mysql> set sql_mode="STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,
140-
"> ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION";
141-
Query OK, 0 rows affected (0.00 sec)
111+
.. include:: mysql.rst

0 commit comments

Comments
 (0)