This article outlines the best practices to follow before and during an AppGate SDP Appliance upgrade and is intended to supplement the upgrade instructions in your AppGate SDP Admin Guide. Be sure to refer to Upgrading Appliances (General Administration > Managing Appliances > Upgrading appliances) in your AppGate SDP Admin Guide while performing your upgrade.
Note that this guide is for upgrading AppGate SDP Collectives from version 5.5 or earlier. If your SDP Collective is on version 6.0 or later, please refer to the Best Practices: Upgrading AppGate SDP Appliances which provides details on the use of the new sdpctl upgrade script.
Key Points to Consider When Upgrading
If you are upgrading from version 5.5.x to version 6.0.x, it is recommended that you switch to a single Controller prior to performing the upgrade process to help ensure a successful upgrade. The Controller Functions assigned to an appliance can be edited in the Appgate SDP Admin UI > System > Appliances > Select Desired Appliance > Functions. After a Collective is successfully upgraded to 6.0, reassign the Controller Function back to reset to a HA configuration again.
If you are upgrading from version 5.5.x to version 6.0.x, using the Switch Partition function is not available to revert to the previous version on Controllers. It is critical that a snapshot or backup of your Controllers are taken prior to upgrading to version 6.0.x.
AppGate SDP appliance upgrades should only be performed from within two versions of the latest version. For example, an upgrade from version 5.2 to version 5.4 is permissible, but an upgrade from version 5.1 to version 5.4 is not. Customers running AppGate SDP version 5.1 must upgrade to version 5.2 before then upgrading to version 5.4.
AppGate SDP Clients should always be within two versions of the appliances. For example, when upgrading from 5.2 to 5.4, the SDP Clients must be on a version from 5.2 thru 6.2.
Some legacy AppGate SDP features are progressively being removed from the product, so there may be changes, deprecations, and deletions to functionality. We also may make changes to our system sizing recommendations. This may affect existing deployments, so any upgrade should always be carefully planned and tested before being executed.
The latest upgrade scripts now include a deprecation check to help identify things that need to be checked/fixed BEFORE performing the actual upgrade. Manual appliance upgrades are still supported but should only be used for single appliances. Note that if you are upgrading across multiple versions, i.e.: 5.3 to 5.5, be sure to check the Release Notes for both the version you are upgrading to as well as the version you are skipping.
Please always check Known Issues in the appropriate AppGate SDP Release Notes before considering an upgrade.
AppGate SDP Support recommends testing all upgrades in a development environment to verify that upgrades are successful and don't cause integration problems with third-party solutions or local client tools.
Preparing for the Upgrade
Review the release notes for the AppGate SDP version to be installed.
Schedule your maintenance window for the upgrade, including a moratorium on configuration changes to be imposed at the time of the upgrade. AppGate SDP Support recommends scheduling your maintenance window at least a week in advance of your planned upgrade, to allow time to address any issues discovered during preparation. If customers need assistance in the preparation phase of their upgrade, they should contact Support to setup a meeting to discuss their plans.
Obtain the appliance upgrade file from AppGate's secure Download Center and place the file in a location where it can be used by the upgrade script (e.g., on the local machine running the upgrade script, or on a web server accessible to all appliances). The upgrade file is a password-protected zip file (e.g., AppGate-5.0.1.img.zip), and you must open a case with AppGate SDP Support to obtain the latest password. Do not decompress the zip file before starting.
NOTE: The appliance upgrade file is approximately 850 mb in size.
Obtain the necessary upgrade scripts (Prepare and Complete) for your AppGate SDP version, as detailed at Upgrading appliances (General Administration > Managing Appliances > Upgrading appliances) in your AppGate SDP Admin Guide.
Verify that you can access the appliance(s) via Secure Shell (SSH).
Verify that Python version 3 or above is installed on the workstation on which the upgrade process will be executed, and that it can connect to the Controller(s).
Verify that you have the Local Admin username and password for use in performing the system upgrade. Credentials can be found in the AppGate SDP Admin Portal at System > Identity providers > Local > Manage Users > Admin User. If the Admin user password is unknown, enter and save a new password.
Check the SDP Dashboard and verify that all appliances are in a Healthy state. Any errors or warnings indicate that you should examine the console messages for suggested corrective actions.
Perform a backup of your Collective's Controller(s):
NOTE: Because the Controller houses a database, performing backups of Controllers is especially important. Gateways can be easily reset and seeded if necessary.
AppGate SDP Support advises backing up your Controllers before an upgrade, and these instructions address backing up Controllers only. However, the backup script also supports backing up your entire Collective (including LogServer) if desired, using the backup-all option. See the Backup Script section of Backup and restore (General Administration > Managing Appliances > Backup and restore) in your AppGate SDP Admin Guide for details.
Obtain the backup script from the AppGate SDP Admin Portal at Settings > Utilities.
Enable backup API in Global Settings of the Admin User Interface, set a Backup Passphrase and record the passphrase in case a restore is required in the future.
Perform a backup of your SDP Controller(s) using the following command:
python3 appgate-backup.pyz --cacert [CERTIFICATE FILE NAME] --backup-all [CONTROLLER HOST NAME]
where [CONTROLLER HOST NAME] is the Controller's admin interface hostname or IP address, specified in the following form: [https://]hostname[:port], and the [CERTIFICATE FILE NAME] can be obtained in Settings >> CA of the Admin User Interface. Port 8443 is assumed unless specified.If your AppGate SDP appliances are cloud-based, you can perform a backup of the Collective using your cloud computing platform's snapshot feature (e.g., Google Cloud Snapshot).
NOTE: Because cloud environment snapshots are very large, and can be corrupted, AppGate SDP Support also recommends using the backup scripts.
One Week Prior to Your Scheduled Upgrade
Check the SDP Dashboard and verify that all appliances are in a Healthy state. Any errors or warnings indicate that you should examine the console messages for suggested corrective actions.
Run the Prepare upgrade script, as detailed at Upgrading appliances (General Administration > Managing Appliances > Upgrading appliances) in your AppGate SDP Admin Guide. The Prepare upgrade script:
distributes upgrade files to all appliances
verifies all upgrade files
verifies the signature
performs a deprecation check
verifies any other applicable preconditions
Example Prepare Script Command
python appgate-upgrade.pyz prepare --cacert [CERTIFICATE FILE NAME] [CONTROLLER HOST NAME] AppGate-SDP-X.x.x.img.zip
NOTE: Replace "X.x.x" in the above example with the applicable SDP image version number for your upgrade.
NOTE: The Prepare upgrade script will not disturb a running collective or attempt to perform the actual upgrade.
Note also that you can run the Prepare script as many times as necessary to verify that any problems are addressed, prior to completing the upgrade using the Complete script.
The initial execution of the Prepare script distributes upgrade files to all appliances and may take time. Subsequent executions of the Prepare script distribute upgrade files only to appliances that have rebooted since the initial execution.
Note the results of the deprecation checks and verifications performed by the script and correct any problems prior to the day of your scheduled upgrade.
The Morning of Your Scheduled Upgrade
Check the SDP Dashboard and verify that all appliances are in a Healthy state. Any errors or warnings indicate that you should examine the console messages for suggested corrective actions.
If any configuration changes have been performed as a result of the Prepare script findings, perform another backup of your collective's Controller(s):
NOTE: Because the Controller houses a database, performing backups of Controllers is especially important. Gateways can be easily reset and seeded if necessary.
AppGate SDP Support advises backing up your Controllers before an upgrade, and these instructions address backing up Controllers only. However, the backup script also supports backing up your entire Collective (including LogServer) if desired, using the backup-all option. See the Backup Script section of Backup and restore (General Administration > Managing Appliances > Backup and restore) in your AppGate SDP Admin Guide for details.
Obtain the backup script from the AppGate SDP Admin Portal at Settings > Utilities.
Perform a backup of your SDP Controller(s) using the following command:
python3 appgate-backup.pyz --cacert [CERTIFICATE FILE NAME] --backup-all [CONTROLLER HOST NAME]
where [CONTROLLER] is the Controller's admin interface hostname or IP address, specified in the following form: [https://]hostname[:port]. Port 8443 is assumed unless specified.If your AppGate SDP appliances are cloud-based, you can perform a backup of the collective using your cloud computing platform's snapshot feature (e.g., Google Cloud Snapshot).
NOTE: Because cloud environment snapshots are very large, and can be corrupted, AppGate SDP Support recommends using the backup scripts.
Run the Prepare upgrade script again, as detailed at Upgrading appliances (General Administration > Managing Appliances > Upgrading appliances) in your AppGate SDP Admin Guide.
NOTE: The Prepare upgrade script will not disturb a running collective or attempt to perform the actual upgrade.
Performing the Upgrade
Impose a moratorium on configuration changes.
Check the SDP Dashboard and verify that all appliances are in a Healthy state. Any errors or warnings indicate that you should examine the console messages for suggested corrective actions.
Prepare your appliances for upgrade completion by running the Prepare upgrade script again, as detailed at Upgrading appliances (General Administration > Managing Appliances > Upgrading appliances) in your AppGate SDP Admin Guide.
NOTE: The Prepare upgrade script will not disturb a running collective or attempt to perform the actual upgrade.
IMPORTANT: If any of your collective's Gateways/Controllers/Connectors reboot at any time after running this instance of the Prepare script, you must run the Prepare script again before running the Complete script (detailed below).
After successfully running the Prepare upgrade script (with no deprecation check or verification errors), run the Complete upgrade script, as detailed at Upgrading appliances (General Administration > Managing Appliances > Upgrading appliances) in your AppGate SDP Admin Guide. The Complete upgrade script installs the prepared upgrade on the secondary partition and performs a reboot to make the second partition the primary partition.
Example Complete Script Command
python appgate-upgrade.pyz complete --cacert [CERTIFICATE FILE NAME] [CONTROLLER HOST NAME]
NOTE: Because the SDP image is staged by the Prepare script, it is not necessary to specify the SDP image version number to execute the Complete script.
NOTE: If your upgrade fails for any reason, remember to collect all appropriate log files to share with AppGate SDP Support for troubleshooting purposes. Detailed instructions for collecting and providing logs can be found here.
If you need to revert to the previous version, instructions on this process can be found in our Reverting to a Previous Version of AppGate SDP knowledge article.
LINKS
AppGate's Secure Download Center