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.
Make sure there is enough free storage space available in your Registry and on the Kubernetes nodes.
- Registry: at least 50 GB free to pull the updated images.
- Kubernetes nodes: each node should provide about 70 GB free space. In any case, the amount of free space must be no less than 50 GB with an added 10-15% threshold, which is needed to avoid the node-pressure eviction.
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.
Check that your login to the pSeven SAS Registry succeeds:
```
docker login registry.pseven.io
```
Pull the updated images from the pSeven SAS Registry to your Registry. Get the list of their names from the Helm chart:
```
helm show values pseven-{YYYY.MM.DD}.tgz | grep -oE "registry\.pseven\.io\/[^:]+"
```

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 the 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
```
Do not manually remove any Kubernetes objects created by pSeven Enterprise, which exist after you run the uninstall command.
If you have changed any of the data storage settings in values.yaml (the storage.* parameters), you might need to re-create the related PersistentVolume and PersistentVolumeClaim objects. This depends upon the way you had configured the data storages earlier, when deploying your previous pSeven Enterprise version; see Installing with limited cluster permissions for more information.
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 examples of installation commands. That option is required because during installation Helm downloads several GB of Docker images from the Registry, so the default Helm's operation timeout (5 minutes) is too short to complete the required downloads. If you enable the storage check, you should set the timeout even longer, because the check requires additional time. You may also want to additionally 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¶

Do not remove the existing installation of the extension node environment. Install its new version to the same directory as the existing one.

Important

Never install any version of the extension node environment side-by-side with an already installed version, that is, to a different directory on the same node.

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.

Upgrading block runtime environment¶

Check what runenv versions are in use on your deployment and add the missing runenv images as described in Maintaining block runtime environment.

Registry cleanup¶

If you wish to clean up your Registry by removing unused images, be sure to keep all existing pseven-runenv-* and pseven-extnode images, and keep one latest version of the legacy runenv (pseven-runenv-legacy).

The pseven-runenv-legacy image: after you have pulled the latest version of this image from the pSeven SAS Registry, remove its other versions.
The pseven-runenv-* images: keep all existing versions of these, as they are required to run the user workflows created in the previously installed versions of pSeven Enterprise.
The pseven-extnode images: keep all existing versions.
The rest of the images provided by pSeven SAS: keep the latest version, remove previous versions.
Other (custom) images: keep all, and contact their developers if you have questions.