Version upgrade¶

This guide covers the general steps to upgrade an existing pSeven Enterprise deployment to a new version.

Related guides

Administration: maintenance, advanced configuration, backups.
pSeven Enterprise deployment and Extension node deployment: initial deployment.

The upgrade process includes two stages, both are required:

Upgrading the pSeven Enterprise deployment, using Helm.
Upgrading Windows extension nodes, using the extension node setup package generated by the pSeven Enterprise deployment during the first upgrade stage.

Important

Never skip the extension node upgrade if there are such nodes in your deployment. Running different versions of the pSeven Enterprise deployment and extension nodes causes various connection issues and errors when running user workflows.

Upgrading pSeven Enterprise¶

To upgrade pSeven Enterprise to a new version, you will have to get configuration values from the existing release and generate a configuration file for the new version, then transfer settings from the existing configuration to the new one. After this, uninstall the existing release and install the new one. Uninstallation does not remove user files and settings, as the user database and file storage services are not parts of a pSeven Enterprise release.

Before you upgrade:

Review the Changelog sections for all versions newer than your existing release.

Plan your upgrade according to the changelog and the version-specific upgrade notices it contains. Note that upgrading often requires additional preparations or changes in your deployment environment, which must be done before you install the new pSeven Enterprise version. The actual upgrade steps depend on your current pSeven Enterprise version, the version you are upgrading to, and features of your deployment. This guide provides only a summary of the general upgrade steps.
Note that in the following cases you will have to enable the storage check by adding the -⁠-⁠set fixStorages=true option to the helm install command - otherwise users may lose access to their files due to incorrect filesystem permissions.
- You are upgrading from v2023.04 or an earlier version.
- You are upgrading from a non-recent version, having skipped several months of updates.
- You are restoring the file storage data from a backup copy.
- You move the storage data during upgrade - for example, migrate the storage to another disk or host.
- You change the NFS protocol version used when connecting to the file storage servers (enable or disable NFSv4 during the upgrade).
If your deployment has any additional Python modules installed, build an updated custom pseven-htcondorexecute Docker image by reinstalling those modules into the base pseven-htcondorexecute image of the new pSeven Enterprise version that you are going to deploy. For build instructions, see Installing modules into the pSeven Enterprise deployment.
If your deployment uses the DATADVANCE Docker registry, verify that your login succeeds:
```
docker login registry.pseven.io
```
If your deployment uses a self-hosted Docker registry, verify that it contains up-to-date images from the DATADVANCE registry.

In the examples below, pseven⁠-⁠rl is the Helm release name, which identifies your pSeven Enterprise deployment, and pseven⁠-⁠ns is the installation namespace (see section Installation namespace in the pSeven Enterprise deployment guide). Using exactly those names is not required - they are just examples used in this guide and other pSeven Enterprise administration guides. If you choose to use another names, replace pseven⁠-⁠rl and pseven⁠-⁠ns in example commands in the guides with the names that you actually use.

Upgrade steps:

Get configuration values from the existing release:

helm get values pseven-rl -n pseven-ns -o yaml > values_old.txt

Generate a configuration file for the new version:

helm show values pseven-<YYYY.MM.DD>.tgz > values.yaml

Using values_old.txt as a reference, set parameters in values.yaml as described in section Deployment configuration.

Warning

Carefully review the comments in values.yaml when transferring settings: the new version may introduce specific changes to some of the parameters and may require setting new values.

The maxUsers parameter

When setting parameters in values.yaml, make sure that the value you assign to the maxUsers parameter is not less than in values_old.txt. Otherwise, some of the existing accounts may become unusable after the upgrade. For more information, see Understanding accounts.
Uninstall the existing release:
```
helm uninstall pseven-rl -n pseven-ns
```
Install the new version with the prepared configuration file (values.yaml), using either of the commands below.
- If you are not reconfiguring the pSeven Enterprise file storage, use the following command:
```
helm install pseven-rl pseven-<YYYY.MM.DD>.tgz -f values.yaml -n pseven-ns --timeout 120m --wait --debug | tee pseven-<YYYY.MM.DD>.log
```
- If you are migrating the file storage or restoring data from a backup copy, enable the storage check by adding the -⁠-⁠set fixStorages=true option. Also enable this check if you are enabling NFSv4 on a deployment where it was disabled, or you have enabled NFSv4 earlier and now are disabling it. This is required to set correct filesystem permissions in the storage. Use the following command:
```
helm install pseven-rl pseven-<YYYY.MM.DD>.tgz -f values.yaml -n pseven-ns --set fixStorages=true --timeout 180m --wait --debug | tee pseven-<YYYY.MM.DD>.log
```
Installation timeout

Note the -⁠-⁠timeout option in the example installation commands. That option is required because pSeven Enterprise deployment downloads several GB of service images from the Docker registry, so the default Helm's operation timeout (5 minutes) is too low to complete that download. If you enable the storage check, it might require additional time too. Also you may want to increase the timeout values, depending on your network and deployment configuration.
Wait for the deployment finalization message to appear. If you install with the storage check enabled, verify that it has run. In this case, the finalization message should contain the following note:

Fixing storages enabled: deployment was run with the "--set fixStorages=true" option, fixing user permissions in data storages.

After you have upgraded pSeven Enterprise, upgrade all Windows extension nodes connected to the deployment you are updating.

Upgrading extension nodes¶

A new version of the extension node environment can be installed without removing the existing installation, provided that you install the new version to the same directory as the existing one.

Important

Never install any version of the extension node environment side-by-side with any other previously installed version (to a different directory).

To upgrade, get the new extension node setup package:

Sign in to pSeven Enterprise as administrator.
Download:
```
{sign-in URL}/pseven/@files/Users/.p7/pSevenExtensionNode.zip
```
The {sign-in URL} is the pSeven Enterprise sign-in URL, which you get during its deployment.

On each extension node to upgrade:

Copy the new downloaded setup package to the extension node host.
Unpack pSevenExtensionNode.zip to a temporary directory. The path to this directory must not contain spaces, for example: C:\Temp\pSevenExtensionSetup.
Open a command prompt as administrator and change to the directory with the unpacked installer.
Run bootstrap.bat without parameters. When started without parameters, the extension node setup script uses settings stored into environment variables on the node (listed in the Appendix A to the extension node deployment guide).
After bootstrap.bat completes, verify that there are no error messages in its output. If you find any error messages there, save the output to a file for later contacting Technical support. If bootstrap.bat completed without errors, check the node as described in the Node check section of the extension node deployment guide.
If any checks fail, reboot the node and conduct the checks again. If any checks fail after rebooting, contact Technical support.

If you previously installed any additional Python modules on the node, then, after upgrading the node, install them again as described in the Installing modules on an extension node section of the pSeven Enterprise administration guide.