This guide covers the general steps to upgrade an existing pSeven Enterprise deployment to a new version.
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.
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=trueoption to the
helm installcommand - 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-htcondorexecuteDocker image by reinstalling those modules into the base
pseven-htcondorexecuteimage 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
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-ns in example commands in the guides
with the names that you actually use.
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
values_old.txtas a reference, set parameters in
values.yamlas described in section Deployment configuration.
Carefully review the comments in
values.yamlwhen transferring settings: the new version may introduce specific changes to some of the parameters and may require setting new values.
When setting parameters in
values.yaml, make sure that the value you assign to the
maxUsersparameter 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=trueoption. 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
--timeoutoption 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 newer version of the extension node environment can be installed without removing an existing installation, but all versions must be installed to the same directory.
Never install any version of the pSeven extension node environment alongside 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.
<sign-in URL>is the user sign-in page URL.
On each extension node to upgrade:
- Copy the new downloaded setup package to the extension node host.
pSevenExtensionNode.zipto a temporary directory. The path to this directory must not contain spaces, for example:
- Open a command prompt as administrator and change to the directory with the unpacked installer.
bootstrap.batwithout 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).
bootstrap.batfinishes, check its output for errors. If there are none, reboot. If you see errors, save the script's output from the command prompt and contact the DATADVANCE support team (see Technical support).
- After the reboot, re-run checks described in section Node check of the extension node deployment guide. If any of those checks fails, contact the DATADVANCE support team.
If you had previously installed any additional Python modules on the node, then, after upgrading the node, you also have to reinstall those modules as described in section Installing modules on an extension node of the pSeven Enterprise administration guide.