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.0.
gateway10
The Expedited Upgrade Workflow
How do I Get to Gateway 10.0?
You must use one of the expedited upgrade procedures to get to Gateway 10.0.
The
Manual Expedited Upgrade Procedure
described 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.0.
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.0.
The
Standard Upgrade Procedure
using sequential platform patches is not supported between 9.x to 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.
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.
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.
  1. Access the privileged shell on the source Gateway.
  2. 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.sql
    Where
    "<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_USER
    Issue: 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
  3. Copy the databases from the source Gateway to the destination Gateway:
    # scp /home/ssgconfig/<source_Gateway>*.sql ssgconfig@<destination_Gateway_Hostname>:~/
    If re-imaging a hardware or virtual appliance Gateway, a destination Gateway would not apply in this scenario. Instead, copy database dump files to another secure machine.  See Re-image a Virtual Appliance and Re-image a Hardware Appliance.
Stop the Destination Gateway
Perform these steps on
every
node on the destination Gateway:
  1. Access the privileged shell.
  2. Stop the node with this command:
    # service ssg stop
    The '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.
  3. 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:
  1. Access the privileged shell.
  2. 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 exit
    You return to the Gateway main menu.
  3. Select option
    2
    (Display Layer7 API Gateway configuration menu) from the Gateway main menu.
  4. Select option
    1
    (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.
  1. Access the privileged shell again.
  2. Restart the Gateway by running this command on every node:
    # service ssg restart
Install the License
  1. Start the Policy Manager and connect to your destination Gateway.
  2. Install the license file.
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.