Upgrade to 2023.1+ process¶
Upgrading from an Early Access release to a 2023.1+ General Access release is a major upgrade that includes file location changes and re-configuration of some features.
Server Upgrade¶
This details the process to upgrade a hub server.
Preparation¶
The recommended upgrade process to version 2.0 and later is to do a full uninstall and re-install. This will require some manual effort to migrate configuration and data to the new installation directory.
Before any upgrade, it is a sensible precaution to backup the hub. To avoid any data loss, ensure that all users log out from the hub, including those logged in to the hub portal from a browser and those logged in from Altair Analytics Workbench.
First stop the hub and all workers using the command on each machine
hubctl service stop
Backup the database¶
It is recommended that the database is backed up following your standard recovery procedures.
If backup procedures are not in place yet, the PostgreSQL utility pg_dump can be used to do this. The details for the database connection can be found using the hubctl command:
hubctl config print database
Paths¶
Through this guide we'll be referencing the location of the etc and var directories of the Altair SLC Hub that is being upgraded from, the table below lists the locations of these depending on the version that is being upgraded from.
| Location | Versions < 2.0 | Versions 2.0 - 2.2 |
|---|---|---|
| [old etc directory] | /opt/worldprogramming/wpshub-c/etc | /opt/altair/swhub/etc |
| [old var directory] | /opt/worldprogramming/wpshub-c/var | /opt/altair/swhub/var |
| Location | Versions < 2.0 | Versions 2.0 - 2.2 |
|---|---|---|
| [old etc directory] | C:\Program Files\Altair\Analytics Hub 5.0\etc | C:\Program Files\Altair\SmartWorks Hub\etc |
| [old var directory] | C:\ProgramData\Altair\Analytics Hub 5.0\var | C:\ProgramData\Altair\SmartWorks Hub\var |
Backup all configuration¶
Backup all configuration, by taking a copy of the [old etc directory] directory.
When upgrading use the following command to create an archive of your etc directory:
tar cvf HubConfigBackup.tar [old etc directory]
etc path for the correct version of Altair SLC Hub that's being upgraded from.
For Windows, browse to the Altair SLC Hub install directory, locate the etc directory, right click on it, select Send to then select Compressed (zipped) folder.
Make sure to use the etc path for the correct version of Altair SLC Hub that's being upgraded from.
Backup S3 storage¶
It is recommended that the S3 storage is backed up following your standard recovery procedures.
If the server is running a local MinIO object store it may be backed up directly by copying the folder.
The following command will create an copy of your MinIO object store directory:
cp -r [old var directory]/minio <minio-backup-location>
<minio-backup-location> should be outside the Altair SLC Hub install directory.
Make sure to use the var path for the correct version of Altair SLC Hub that's being upgraded from.
For Windows, browse to [old var directory], locate the minio directory, and copy it to a location outside the var directory.
Make sure to use the path of [old var directory] for the correct version of Altair SLC Hub that's being upgraded from.
Upgrade¶
The first step is to uninstall the old version of Altair SLC Hub. If upgrading from a version earlier than 2.0, use the following command:
sudo dnf remove -y wpshub-*
If upgrading from a version between 2.0 and 2.2 then use this command:
sudo dnf remove -y swhub
The next step is to install Altair SLC Hub. Download the new RPM and copy on to the machine as with a fresh install.
sudo dnf install -y slchub_<version>-1_x86_64.rpm
Once installed any custom configuration files which have been left behind after the uninstall can be copied across from the old install directory to the new one:
cp -r [old etc directory] /opt/altair/slchub/
If still using legacy licensing then the license file also needs to be copied to the new location:
mv [old var directory]/licence.txt [var directory]/licence.txt
Ensure any temporary shared memory file, which may now have incorrect file permissions is removed.
rm /dev/shm/envoy_shared_memory_0
To perform the upgrade on Windows download the latest MSI and copy it onto the machine as with a fresh install. Run the MSI and work through the install wizard.
Once installed any custom configuration files which have been left behind after the uninstall can be copied across from the old install directory to the new one using file explorer.
MinIO¶
If the system previously made use of the wpshub-minio-cfg package for setting up a MinIO instance, this package is no longer supported and MinIO setup should be performed to configure a S3 bucket.
It is possible to move the existing data and configure MinIO to serve this directory, or to configure a MinIO instance to serve the existing data directory.
Instructions on installing and configuring MinIO locally for use by Hub are available in the Altair Community.
When migrating it is important to ensure the user MinIO is running under has access to the data directory by setting the permissions:
chown -R [MinIO user] <Directory Name>
chgrp -R [MinIO user group] <Directory Name>
etc/config.d/s3_custom.yaml config file
Postgresql¶
Early versions of Altair SLC Hub allowed installation of wpshub-postgres and wpshub-postgres-repo to provide a simple database setup for use in evaluations. This was deprecated in previous versions of Altair SLC Hub. These are no longer supported and the postgres database should be setup as a pre-requisite of an Altair SLC Hub install, for more information see here.
Configure HTTPS¶
If HTTPS was previously configured, file ownership of the certificate and key used for external ingress will need to be updated to ensure the updated Altair SLC Hub has access.
sudo chown slchub-ingress cert.pem key.pem
Migrate¶
Next make sure the database server is running. Use the hubctl command to perform any necessary database migrations and bootstrapping, and then to start the updated Hub services:
hubctl bootstrap
hubctl service start
Worker Upgrade¶
This details the process to upgrade a hub worker. Each worker node should be upgraded.
Preparation¶
The worker services should have been stopped in a previous step with
hubctl service stop
The steps here are similar to the server steps. It is a sensible precaution to back up the configuration files.
The following command can be used to create a backup archive of your etc directory:
tar cvf HubConfigBackup.tar [old etc directory]
etc path for the correct version of Altair SLC Hub that's being upgraded from.
For Windows, browse to the Altair SLC Hub install directory, locate the etc directory, right click on it, select Send to then select Compressed (zipped) folder.
Make sure to use the etc path for the correct version of Altair SLC Hub that's being upgraded from.
Update¶
The first step is to uninstall the old version of Altair SLC Hub. If upgrading from a version earlier than 2.0, use the following command:
sudo dnf remove -y wpshub-*
If upgrading from a version between 2.0 and 2.2 then use this command:
sudo dnf remove -y swhub-worker
The next step is to install Altair SLC Hub worker RPM. Download the new RPM and copy on to the machine. It can then be installed using DNF:
sudo dnf install -y slchub-worker_<version>-1_x86_64.rpm
Once installed any custom configuration files which have been left behind after the uninstall can be copied across from the old install directory to the new one:
cp -r [old etc directory] /opt/altair/swhub/
Move any wps_installs.yaml file to slc_installs.yaml
mv [old etc directory]/wps_installs.yaml [etc directory]/slc_installs.yaml
To perform the upgrade on Windows download the latest MSI and copy it onto the machine as with a fresh install. Run the MSI and work through the install wizard to install the Altair SLC Hub for a worker.
Once installed any custom configuration files which have been left behind after the uninstall can be copied across from the old install directory to the new one using file explorer.
If the file [etc directory]/wps_installs.yaml was copied over from the previous configuration files then rename it to slc_installs.yaml.
Use the hubctl command to start the updated Hub services:
hubctl service start
Migrate to new features¶
Link Session configurations¶
Any Link Session configurations that have been defined under [old etc directory]/linksessionmgr.d/ will need to be recreated as Execution Profiles in Hub.
Operating System Users¶
The concept of "default users" has been removed. Any previous configuration will be ignored. This may mean some configuration is needed where a local user needs to run a workload. See Operating System Users for details on configuration options
Namespaces and Execution Profiles¶
Altair SLC Hub contains new Features to provide separation, Namespaces, and to allow controlling where jobs are run, Execution Profiles. Users desiring to make use of these features should read these sections and update their configuration as desired.