Manual Expedited Appliance Upgrade
This topic describes how to perform an expedited upgrade of a gateway Appliance (Hardware or Virtual), from version 9.x to version 10.1.
The Expedited Upgrade Workflow
How do I Get to Gateway 10.x?
You must use one of the expedited upgrade procedures to get to Gateway 10.x.
Manual Expedited Upgrade Proceduredescribed below consists of installing a new Gateway, then manually migrating data from the older Gateway version. The current procedure is supported for migrating from Gateway 9.x to Gateway 10.x.
An alternative to this manual procedure is the
Automated Expedited Upgrade Procedure. The benefits of the automated procedure include ease of backup and configuration (running playbooks containing scripted tasks), and the ability to upgrade multiple Gateway clusters simultaneously. The Automated Expedited Upgrade procedure is only supported for migrating data from Gateway 9.4 to Gateway 10.x.
The procedure assumes that you have followed the supported Gateway database architecture model in which your MySQL database (ssg) is located on the Gateway server.
Standard Upgrade Procedureusing sequential platform patches is not supported between 9.x to 10.x.
Prepare for the Expedited Upgrade
Before you start the upgrade, you must complete preparation tasks, including backing up the existing Gateway artifacts, and installing a new target Gateway or cluster as the destination for your migration, and creating a new database that will be restored on top later.
Perform only the preparation tasks that apply to your installation. It is not recommended for a production environment to host the OTK and MAG databases on the same server as the ssg database. Only migration of MySQL databases are supported by this procedure.
Export Databases from Source Gateway
The following steps are used to backup and migrate the co-located databases to the new Gateway.
- Access the privileged shell on the source Gateway.
- Run the following commands to export the Gateway and any co-located OTK or MAG database:# mysqldump ssg --routines > /home/ssgconfig/<source_Gateway>.sql # mysqldump <otk_db_name> --routines > /home/<source_Gateway>_otk.sql # mysqldump <mag_db_name> --routines > /home/<source_Gateway>_mag.sql //These next steps only apply if the destination Gatway DB version is MySQL 8 #sed -i 's/NO_AUTO_CREATE_USER,//g' /home/ssgconfig/<source_Gateway>.sql #sed -i 's/NO_AUTO_CREATE_USER,//g' /home/ssgconfig/<source_Gateway>_otk.sql #sed -i 's/NO_AUTO_CREATE_USER,//g' /home/ssgconfig/<source_Gateway>_mag.sqlWhere"<source_Gateway>"is any label that indicates the .sql file is the database from the source Gateway.Known Issue for Upgrading to MySQL 8.0 from 5.7: NO_AUTO_CREATE_USERIssue: MySQL 8.0 removed NO_AUTO_CREATE_USER SQL mode (a MySQL issue). When creating a backup from MySQL 5.7 and upgrading to MySQL 8.0, you may encounter an issue related to 'sql_mode' that can't be set to the value of 'NO_AUTO_CREATE_USER'.Wokaround: Use the following command to remove 'NO_AUTO_CREATE_USER' in dump file by simple space:sed -i "s/NO_AUTO_CREATE_USER//g" mysql_dump.sql
- Copy the databases from the source Gateway to the destination Gateway:# scp /home/ssgconfig/<source_Gateway>*.sql [email protected]<destination_Gateway_Hostname>:~/
Stop the Destination Gateway
Perform these steps on
everynode on the destination Gateway:
- Access the privileged shell.
- Stop the node with this command:# service ssg stopThe 'ssg' service must be stopped on all nodes, otherwise the upgrade is not successful.Perform any required re-imaging of a hardware or virtual appliance Gateway after completing this stoppage procedure.
- After the stoppage, it's strongly recommended that you configure database replication and database failover prior to importing and upgrading the database on the destination Gateway. To learn how to get started, see Configuring Cluster Database Replication.
Configure nShield Connect/Connect XC
Performed on the destination Gateway, this step only applies if your Gateway is configured to work with nShield Connect/Connect XC HSM. You must have already committed and synched your HSM private keys to the RFS server as instructed in Preparing for Expedited Upgrade. Prior to importing and upgrading the database on the destination Gateway, set up your nShield Connect/Connect XC HSM with the guidance provided in Configure the nShield Connect.
Import and Upgrade the Database on the Destination Gateway
The following steps are used to import and upgrade the Gateway database (ssg) plus any co-located databases onto the destination Gateway server.
Ensure that you have stopped the destination Gateway, and all the nodes in a target cluster, then perform the following:
- Access the privileged shell.
- Run the commands applicable to your installation://ssg database restore mysqladmin drop ssg mysqladmin create ssg mysql ssg </home/ssgconfig/<source_Gateway>.sql //OTK database restore mysql create database <otk_db>; CREATE USER <otk_user>@'<hostname/ip>' IDENTIFIED BY '<password>'; grant select,delete,update,insert on <otk_db>.* to <otk_user>@'<hostname/ip>'; flush privileges; exit mysql <otk_db_name> < /home/ssgconfig/<source_Gateway>_otk.sql exit //MAG database restore mysql create database <mag_db>; CREATE USER <mag_user>@'<hostname/ip>' IDENTIFIED BY '<password>'; grant select,delete,update,insert on <mag_db>.* to <mag_user>@'<hostname/ip>'; flush privileges; exit mysql <mag_name> < /home/ssgconfig/<source_Gateway>_mag.sql exitYou return to the Gateway main menu.
- Select option2(Display Layer7 API Gateway configuration menu) from the Gateway main menu.
- Select option1(Upgrade the Layer7 API Gateway database). Confirm the upgrade. Allow several minutes for the upgrade to complete.
Restart the Gateway
After you have imported and upgraded the database, restart the Gateway cluster.
- Access the privileged shell again.
- Restart the Gateway by running this command on every node:# service ssg restart
Install the License
Your destination Gateway is now operational.
Post Upgrade Tasks
Some items cannot be brought over in the expedited upgrade process. Manually complete the Post Upgrade Tasks that apply to you.