Skip to content

Commit d7f9f08

Browse files
sureshanapartisureshanaparti
committed
move mysql upgrade details to mysql.rst
1 parent 09885d3 commit d7f9f08

File tree

2 files changed

+103
-98
lines changed

2 files changed

+103
-98
lines changed

‎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 & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -108,100 +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-
MySQL support updated to 8.4
124-
----------------------------
125-
126-
As of Apache CloudStack 4.20.3, support for MySQL 8.4 has been added.
127-
128-
Existing deployments upgraded to version 4.20.3 can still continue using MySQL 8.0
129-
without any changes.
130-
131-
If you are running MySQL 8.0 and would like to upgrade to MySQL 8.4,
132-
you may follow the standard MySQL upgrade process to migrate safely to version 8.4,
133-
and then update the authentication method for the root and CloudStack (cloud) users with
134-
caching_sha2_password plugin using the below steps as the mysql_native_password plugin
135-
is deprecated as of MySQL 8.0.34, and disabled by default in MySQL 8.4. For more details,
136-
refer to MySQL documentation here: https://dev.mysql.com/doc/refman/8.4/en/caching-sha2-pluggable-authentication.html
137-
138-
#. Stop MySQL server if already running
139-
140-
.. code-block:: bash
141-
142-
sudo systemctl stop mysqld
143-
144-
#. Start MySQL server in safe mode without auth
145-
146-
.. code-block:: bash
147-
148-
sudo mysqld --skip-grant-tables --skip-networking &
149-
150-
#. Login to MySQL without password
151-
152-
.. code-block:: bash
153-
154-
mysql -u root
155-
156-
#. Reset passwords for root and CloudStack (cloud) users.
157-
158-
.. code-block:: mysql
159-
160-
ALTER USER 'root'@'localhost' IDENTIFIED WITH caching_sha2_password BY 'ROOT_PASSWORD';
161-
ALTER USER 'root'@'%' IDENTIFIED WITH caching_sha2_password BY 'ROOT_PASSWORD';
162-
ALTER USER 'cloud'@'localhost' IDENTIFIED WITH caching_sha2_password BY 'CLOUD_PASSWORD';
163-
ALTER USER 'cloud'@'%' IDENTIFIED WITH caching_sha2_password BY 'CLOUD_PASSWORD';
164-
FLUSH PRIVILEGES;
165-
166-
Note: Please ensure that the password used for the cloud database user matches the value
167-
configured in /etc/cloudstack/management/db.properties. If the password in db.properties
168-
is encrypted, you can retrieve it using the below command.
169-
170-
.. code-block:: bash
171-
172-
java -classpath /usr/share/cloudstack-common/lib/cloudstack-utils.jar \
173-
com.cloud.utils.crypt.EncryptionCLI -d \
174-
-i "$(grep -oP 'db.cloud.password=ENC\(\K[^\)]+(?=\))' /etc/cloudstack/management/db.properties)" \
175-
-p "$(cat /etc/cloudstack/management/key)"
176-
177-
#. Remove deprecated authentication plugin 'mysql_native_password' from the MySQL configuration. Either comment or remove the below line from /etc/my.cnf
178-
179-
.. parsed-literal::
180-
181-
default_authentication_plugin=mysql_native_password
182-
183-
#. Restart MySQL server
184-
185-
.. code-block:: bash
186-
187-
killall mysqld
188-
systemctl start mysqld
189-
190-
MySQL 8.4 sql mode change
191-
-------------------------
192-
193-
MySQL mode (sql_mode) has changed in CloudStack db.properties to
194-
"STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,
195-
ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION".
196-
197-
This gets automatically applies to the MySQL session used by CloudStack management server.
198-
199-
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.
200-
201-
Eg. mysql> set global sql_mode="STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,
202-
"> ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION";
203-
Query OK, 0 rows affected (0.00 sec)
204-
205-
mysql> set sql_mode="STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,
206-
"> ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION";
207-
Query OK, 0 rows affected (0.00 sec)
111+
.. include:: mysql.rst

0 commit comments

Comments
 (0)