Automated Expedited Upgrade Procedure
Expedited Upgrade Workflow
The automated expedited upgrade procedure is used in both of the following scenarios:
- Create New and Migrate. Install the new Gateway version by creating new VMs. Using the automated procedure, migrate your data from the old version to the new version. The benefit of this approach is that you keep the old Gateway instance which allows you to switch back to the old version.
- Re-image ExistingVM instance or Hardware Appliance. The benefit of this approach is there is no additional procurement required while making it possible for you to keep the same IP or MAC address. However, switching back to the old version is not available and downtime is required for creating MySQL replication. There are also manual steps to configure the Gateway when a Gateway administrator adds the ISO file and after re-imaging is complete.See Virtual Machine Re-image to learn how to re-image an OVA Virtual Machine.See Hardware Appliance Machine Re-image to learn how to re-image a hardware appliance.
The automated steps of this procedure are performed with Ansible, an open-source automation engine for application management. In the following diagrams, the green boxes indicate steps that are automated. The OTK database steps cover the scenario where the OTK database is co-located with the Gateway (SSG) database.
Create New and Migrate
Create New and Migrateexpedited upgrade procedure:
Re-image Existing VM Instance or Hardware Appliance
Re-image Exsitingexpedited upgrade procedure:
How it All Works
It works with Ansible.
See Automating with Ansible for an overview of the Ansible workflow for the Automated Expedited Upgrade Procedure.
Running an Ansible
playbookexecutes a list of sequential tasks to complete a step (one of the green boxes) in the automated expedited upgrade procedure. Ansible
inventoriescontain a list of hosts and global variables used by the playbooks. Ansible
rolesprovide variables and instructions specific to running a playbook.
Access the README.md files in the GatewayDeveloper_Ansible GitHub repository to learn how to configure and run each playbook of the Ansible automation. Start with the README.md file in the root directory. Additional README.md files are located in each of the role directories. This documentation describes how to configure the required variables, and how to customize and extend the standard automation tasks to better fit your environment.
All contents in the repository are intended as a reference implementation. Should you decide to deviate from the reference implementation, please use the contents as a guideline for implementing your own custom automations.
Export Database from Source Gatewaytask in the expedited upgrade procedure is automated by running the gateway-database-export.yml
playbookthat executes sequential tasks. The playbook references the
inventorieshost file where source and target Gateway paths are set. The gateway_export_database
roleincludes default variable values that you customize. The playbook calls the role and uses the values found within when executing the tasks.
The README.md file in /roles/gateway_export_database/ explains what variables to set, what to expect, and how to run the playbook. Notice that the hosts file of the inventories directory is referenced in order to retrieve passwords required for completing the task.
run : ansible-playbook playbooks/gateway-database-export.yml -i inventories/test/hosts --vault-password-file vault-password-file.txt
When to Use the Automated Expedited Procedure
Do you have multiple clusters of Gateways? The automated expedited procedure is designed to upgrade one cluster at a time, with a recommended limit of 8 nodes per cluster. Each cluster requires a database upgrade.
Currently, the Automated Expedited Procedure is only supported for upgrading Gateway 9.4 to Gateway 10.x. If you are upgrading from Gateway 8.x use the standard patch procedure to upgrade to 9.x. If you are upgrading from 9.x, you can use the manual expedited procedure to upgrade to Gateway 10.x.
The following table shows what procedure to use when upgrading to Gateway version 10.x from earlier Gateway versions.
Current Hardware and Virtual appliance Gateway Version
Upgrading to Gateway 10.x
Gateway versions 8.x
Use the Standard Patch Upgrade Procedure to upgrade sequentially to Gateway 9.0.
Gateway versions 9.0, 9.1, 9.2, 9.3.
Use the manual expedited to upgrade from Gateway 9.x to Gateway 10.x.
Alternatively, you can upgrade to Gateway to 9.4 using the sequential platform updates. Upgrading to Gateway 9.4 allows you to use the automated expedited procedure.
Use either the manual or automated expedited upgrade procedure.
Unsupported by Automation
The following items are not supported or migrated when performing the automated expedited upgrade procedure:
- AMI, Azure, Docker and other Gateway form factors are not supported.
- The automateddeploymentof OVA Virtual Appliances is not supported. No automated ESXi deployment is available.
- The MAG database is not migrated.
- If the OTK database is co-located with the Gateway database additional customization must be performed in the group_vars/gateway_mysql.yml. See About the OTK Database.
- Log files and audits are not migrated.
- Only the default owners and permissions are preserved. Custom OS users or custom file owners and permissions are not migrated.
- No migration of IP Tables (firewall rules).
- No migration of custom scripts.
- No migration of Hardware Security Module (HSM) configuration, including private keys. See Preparing for Expedited Upgrade for instructions on how to back up nShield Solo+ private keys.
- No migration of the MySQL 5.x Server property file. The file my.cnf is not compatible with MySQL 8.
- Limited migration of system level property files.
About the OTK Database
OTK database export and import is
disabledby default because co-locating the OTK database with the Gateway database (ssg) is not recommended. However, migration is supported for this scenario.
Instructions on how to enable OTK database export and import can be found in README.md files of the gateway_export_database and gateway_import_database roles. Replication for the OTK database is not supported.