Skip to content

pSeven Enterprise deployment

This guide describes how to deploy pSeven Enterprise on Kubernetes using Helm v3. It assumes certain experience with Kubernetes and Helm, leaving details, which are not specific to pSeven deployment, mostly out of consideration. For this kind of general information, you can refer to the Kubernetes Documentation and the Helm Documentation which describe them in full.

For alternative deployments, please contact support@datadvance.net.

Prerequisites

Kubernetes cluster

Kubernetes 1.15.5 or newer is required. Older versions might also work but have never been tested by DATADVANCE. Kubernetes is used to manage pSeven Enterprise services.

A minimal known to work cluster configuration is:

  • 3 cluster nodes.
  • 2 vCPU per node.
  • 4 GB RAM per node.

A typical configuration recommended for a test deployment is:

  • 3 to 5 cluster nodes.
  • 4 to 8 vCPU per node.
  • 8 to 16 GB RAM per node.
  • 50 GB disk space per node.

The number and sizing of Kubernetes nodes in a production deployment depends on the expected load and shall be subject to discussion.

Helm

pSeven Enterprise is delivered as a Helm chart (package), which requires Helm v3.2.0 or newer. Older versions might also work but have never been tested.

Docker registry

Kubernetes needs a Docker registry, from which it downloads Docker images of managed services. DATADVANCE hosts a private Docker registry with pSeven Enterprise images at https://docker.pseven.datadvance.net. To get access credentials, send a request to support@datadvance.net. You will receive a Docker username and password for the DATADVANCE registry.

Your deployment may use the DATADVANCE registry or a local self-hosted registry. If you decide to use a self-hosted registry, add images from the DATADVANCE registry there.

Helm will configure your Kubernetes instance to access the registry. You will only have to specify the access credentials and, if using a local registry, change the registry address in the Helm chart.

File storage

pSeven Enterprise stores user files and application data on an external NFS server you provide. Requirements to this server are:

  • NFSv3. Other NFS versions are not compatible with pSeven Enterprise.
  • ACL support. The storage must allow using the Access Control List mechanism to set user permissions (setfacl).
  • File locking support (the flock() syscall).

The storage should have enough space to hold all user data (uploaded files, models, workflows, files generated in workflow runs, and so on). It is recommended to start with at least 100 GB of storage space. Further consumption depends on the amount of user activity and general usage patterns.

PostgreSQL server

A PostgreSQL database server version 11 or newer is required. Older versions might also work fine but have never been tested. In theory, the DATADVANCE Docker registry can provide an image with a preconfigured PostgreSQL server. However in practice most PaaS providers offer a managed PostgreSQL instance which is easy to deploy, so the pSeven deployment chart assumes that there is a PostgreSQL server already available on the network.

A typical database server configuration for a test deployment is:

  • 2 vCPU.
  • 4 GB RAM.
  • 50 GB disk space.

Configuration for a production deployment depends on the number of users and the expected load.

SMTP server

pSeven needs an account on an SMTP server to send emails to users - for example, when a user requests a password reset link. DATADVANCE does not provide an SMTP server, and the pSeven deployment chart assumes that you have an SMTP server already available on the network.

Load balancer

pSeven Enterprise edge router service listens on a specific port on each of the cluster nodes. While you can simply route all traffic to one of the nodes, common practice is to configure a load balancer to distribute incoming traffic across nodes. pSeven Enterprise typically relies on a load balancer from the PaaS provider, although it is possible to configure one manually if necessary.

Ingress configuration is not required, although you can add an ingress controller to pSeven Enterprise (see Ingress in the Kubernetes documentation).

In any case, you have to configure the load balancer or the ingress controller so it can handle pSeven Enterprise traffic. For example, if you use the NGINX Ingress Controller (ingress-nginx), its default maximum client request body size is too low, preventing pSeven Enterprise users from uploading large files. If you keep the default, users will often get the 413 Request Entity Too Large error when they try to upload a file, so you should set a custom size (see Custom max body size in NGINX). Other adjustments may also be required, depending on the load balancer or ingress controller you use.

Deployment diagram

The following diagram provides an overview of pSeven Enterprise deployment and network communications.

Deployment diagram

Deployment

This section provides step-by-step instructions on pSeven Enterprise deployment and initial configuration. See Preparations first for the steps required before deployment - in particular, generation of secrets. Also note that the tests outlined in Verify installation are required: consider your deployment successful only if these tests pass.

Preparations

Before you begin with deployment, verify the following:

  • You have set up a deployment environment that satisfies the requirements explained in section Prerequisites.
  • You can login to the DATADVANCE Docker registry:

    docker login docker.pseven.datadvance.net
    

    When prompted for a username and password, input the Docker registry access credentials that you have received from support@datadvance.net. Verify that login succeeds.

  • If you are going to use a self-hosted Docker registry, also verify that it contains up-to-date images from the DATADVANCE registry.

For a new deployment, you will need to generate a number of secrets - encryption keys and certificates used internally by pSeven Enterprise. While you can generate them manually, the DATADVANCE Docker registry also provides a dedicated image to streamline the generation process:

  • Login to the registry first:

    docker login docker.pseven.datadvance.net
    
  • Your pSeven Enterprise package contains a version tag - an empty file with a name in the vYYYY.MM.DD-tttttttttt.xxxxxxxx format. This filename is the full version number to use in the command below.

  • Run the following command to generate secrets and save them to a file (replace <full version> with the version number):

    docker run --rm -it docker.pseven.datadvance.net/pseven-secretgen:<full version> > pseven-secrets.txt
    

The above command outputs a configuration file snippet with secrets to pseven-secrets.txt. You are going to need this file during installation. It is also recommended to keep it after you finish with the deployment, as this sometimes simplifies version upgrades.

Installation

The deployment procedure is a typical Helm chart installation, which is described in Using Helm. For example, to install the chart as a new release (deployment instance) named my-pseven:

  1. Generate a configuration file for the pSeven chart:

    helm show values pseven-YYYY.MM.DD.tgz > config.yaml
    
  2. Open config.yaml with a text editor and specify the parameters noted below. See comments in config.yaml for detailed parameter descriptions and examples.

  3. Specify the Docker registry access credentials you have received from support@datadvance.net in registry.username and registry.password.

    Note if using a self-hosted Docker registry

    If you intend to use a self-hosted Docker registry, verify that it contains up-to-date images from the DATADVANCE registry. To pull images from your registry during deployment, edit the following:

    1. Replace the DATADVANCE registry address in registry.url with your registry address.
    2. Specify the username and password for your registry in registry.username and registry.password.
    3. In the image.* parameters found at the end of the configuration file, replace the DATADVANCE Docker registry address (docker.pseven.datadvance.net) with your registry address, which you have specified in registry.url.
  4. Set all parameters in storage. There are 3 storages - storage.userdata, storage.appdata, and storage.shareddata. Specify the NFS server address and storage path for each. Note section File storage in Prerequisites for the requirements.

  5. Set the postgres.* parameters, which specify your PostgreSQL database server. As noted in Prerequisites, the pSeven deployment chart assumes that you use a PostgreSQL server (version 11 or newer) that already exists in your network. You can deploy a server offered by your service provider or set up your own.
  6. Set the smtp.* parameters, which specify the email server used by pSeven to send emails to users - for example, when a user requests a password reset link. As noted in Prerequisites, DATADVANCE does not provide an SMTP server, and the pSeven deployment chart assumes that you use an existing email server.
  7. Add secrets:

    • In your config.yaml, find the part that contains secrets (the jobcluster.secret, jobcluster.token, and extensionNode.* parameters).
    • Open the file with secrets generated earlier (see Preparations) and copy its contents to your config.yaml, replacing the part with secrets.

    Note

    Extension node secrets are required only if you set up such nodes (see Extension nodes). Otherwise you may safely skip them - however, it is still recommended to include these secrets in config.yaml, in case you need to add extension nodes later.

  8. Other parameters in config.yaml, which are not mentioned here, are set to sensible defaults. You can change them according to your requirements - see comments in config.yaml for parameter descriptions.

  9. Install with the prepared configuration file:

    helm install my-pseven pseven-<YYYY.MM.DD>.tgz -f config.yaml --atomic --timeout <seconds>
    

    Installation timeout

    The --atomic option in helm install implies --wait, which times out according to --timeout. In this case, --timeout can be understood as a time limit to finish the deployment. Since pSeven deployment downloads several GB of service images from the Docker registry, the default Helm's timeout (5 minutes) is usually too low. Most likely, you will have to increase the timeout - its value depends on the throughput of the Docker registry connection.

    Use a release name (my-pseven in the example above) to identify your deployment. The name you specify must not be in use. To check name availability, you can run helm list -a --all-namespaces to list all existing releases.

    Note

    Note the release name you use as you are going to need it when updating your pSeven Enterprise deployment to a new version.

When installation enters the final stage, Helm shows a finalization message with a few commands to get URLs of your deployment. Run these commands and save the following URLs from their output:

Tip

To see the deployment progress, you can check Kubernetes resources with kubectl get all.

  • pSeven Enterprise sign-in URL
  • pSeven Enterprise admin URL
  • pSeven Enterprise health check URL
  • pSeven Enterprise extension node connection URL

These URLs are specific to your deployment; example commands in this guide refer to them as <sign-in URL>, <admin URL>, and so on. Note that all URLs include a port number.

When you see the finalization message, allow some time for the deployment to finish, while Kubernetes launches the pSeven Enterprise services. After a few minutes you can check the deployment:

  • Open the pSeven Enterprise sign-in URL with a web browser. The user sign-in page should load - however, at this stage sign-in is normally not available yet (see section License).
  • Send a HTTP request to the health check URL, for example:

    curl <health check URL>
    

    The HTTP response status should be OK.

Admin access

Open the pSeven Enterprise admin URL, sign in and change the default username and password for the admin account.

  • Settings page URL: <admin URL>/app_auth/user/1/change/
  • Default username: admin@admin.admin
  • Default password: admin

License

This step requires your license key. You may have received it by email or in a separate file.

Sign in as admin to add a license.

  • Settings page URL: <admin URL>/app_auth/license/add/
  • License source: copy your license key here and click the Save button below.

Note

End-user interface sign in is unavailable for all accounts (including admin) until you add a license. If you visit <sign-in URL> and try to sign in before adding a license, you will get an error.

Users

Create end-user accounts.

  • Settings page URL: <admin URL>/app_auth/user/add/

Verify installation

To verify your pSeven Enterprise installation, sign in to the end-user interface.

  • URL: <sign-in URL>
  • Username and password: any existing account.

File upload test

To test general operation, try uploading a file to user Home. The file size should be a few MB.

  • Drag a file to the Explorer pane on the left, or use the Upload files... command from the pane's menu.
  • Verify that the upload completes successfully.

If the upload succeeds, the test has passed. If you get an error, or the upload never finishes, see Troubleshooting.

AppsHub test

To test workflow execution, try running an example from AppsHub.

  • Switch to AppsHub: click the AppsHub link at the top right, or select AppsHub from your user menu.
  • In AppsHub, open the Disk optimization example: hover it with your mouse and click the icon that appears.
  • In the example, scroll down and click the Calculate button at the bottom. The button title should change to Deploying workflow..., then Setting parameters..., then Running workflow... Wait for a few minutes until the workflow finishes.

    Warning

    Do not refresh or close the browser tab with the example as this cancels the calculation.

  • When the example finishes, it shows results at the bottom, and the button title changes back to Calculate. Scroll down to see the results.

If you see the Results section with diagrams and result values, the test has passed. If you get an error while running the example, or calculation never finishes, there may be a problem with the deployment. Contact support@datadvance.net for further advice.

Extension nodes

pSeven Enterprise supports extension nodes, meaning that Windows hosts which are not Kubernetes nodes can be set up to connect with the cluster and receive pSeven tasks. These nodes can be used to run platform-dependent or node-locked software from pSeven workflows.

During deployment, pSeven Enterprise generates an extension node setup package and saves it to the pSeven file storage. See the Extension node deployment guide for the download and installation instructions. This step is optional.

Upgrade

To upgrade pSeven Enterprise to a new version, you will have to get the configuration file from the existing release, then 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 the release.

Before you upgrade:

  • If your deployment uses the DATADVANCE Docker registry, verify that your login succeeds:

    docker login docker.pseven.datadvance.net
    
  • If your deployment uses a self-hosted Docker registry, verify that it contains up-to-date images from the DATADVANCE registry.

  • Revise the Changelog section for version-specific upgrade notices. Check changelogs for all versions newer than your existing release.

Upgrade steps:

  1. Find the name of the existing pSeven release. For example, to list all releases:

    helm list -a --all-namespaces
    
  2. Generate the configuration file from your existing release (replace <release name>):

    helm get values <release name> > config_current.yaml
    

    Use the generated file (config_current.yaml) when installing the new release.

  3. Uninstall the existing release (replace <release name>):

    helm uninstall <release name>
    
  4. Install the upgrade with the previously generated configuration file (config_current.yaml):

    helm install <release name> pseven-<YYYY.MM.DD>.tgz -f config_current.yaml --atomic --timeout <seconds>
    
    Installation timeout

    The --atomic option in helm install implies --wait, which times out according to --timeout. In this case, --timeout can be understood as a time limit to finish the deployment. Since pSeven deployment downloads several GB of service images from the Docker registry, the default Helm's timeout (5 minutes) is usually too low. Most likely, you will have to increase the timeout - its value depends on the throughput of the Docker registry connection.

    It is recommended to keep the same release name for consistency. Note there is no need to run helm show values for the new package, as the configuration file is generated from the previous release.

Uninstallation

Helm automates pSeven Enterprise uninstallation. You will have to specify the release name to uninstall. For example, to uninstall the release named my-pseven:

helm uninstall my-pseven

Tip

To find release names, you can use helm list -a --all-namespaces, which lists all existing releases.

Troubleshooting

There are a few known issues, which may appear in a pSeven Enterprise deployment. These issues are usually identified by the file upload test after installation (see Verify installation).

  • If you get error 413 or other while uploading a file, there may be an issue with a traffic load balancer or an ingress controller in your deployment. See section Load balancer for details.
  • If the file upload never finishes, there may be a problem with your NFS server. Verify the requirements listed in section File storage. To investigate this issue, you may try to set the disableFileLock parameter in config.yaml to true, then re-run the deployment.

    Troubleshooting only

    The option to disable the file locking mechanism in pSeven Enterprise is for troubleshooting purposes only. Do not set disableFileLock to true in a production deployment. If you find out that an issue with your deployment is related to file locking, contact support@datadvance.net for further advice.