Manager 2025.8 Installation Guide for Kubernetes

The following chapters walk you through the installation of qTest Manager 2025.8 and its additional applications on a Kubernetes cluster, using Helm.

Prerequisites

The following requirements apply to proceed with the installation:

• Kubernetes 1.32 (or higher)

• Support for PersistentVolume (PV) in the underlying infrastructure (PV must set persistentVolumeReclaimPolicy to Retain)

• Helm 3.17

• PostgreSQL 16.x

• Elasticsearch 7.17.x

For more details on prerequisites, see chapter "2025.8 OnPremises Prerequisite Software for Linux and Kubernetes".

What's included

The qTest Helm repository includes the qTest applications listed below. You must first install qTest Manager to then choose which other applications to deploy. Note that the applications you can install are tied to your qTest license tier.

• qtest-mgr

• qtest-session

• qtest-parameters

• qtest-insights

• qtest-launch

• qtest-pulse

• qtest-scenario

• qtest-insights-ietl

To view the versions and parameters needed for each application, please take a look at our Helm Repository (opens in a new tab).

Docker Hub Repository Authentication

qTest uses private Docker images and requires authentication via Docker. To begin with the authentication process, perform the following steps:

1. Initiate the Docker login process:

   docker login

2. When prompted, enter your Docker ID and access token. The login process creates or updates a config.json file that holds an authorization token, typically located under $HOME/.docker/config.json.

3. Create a corresponding Kubernetes secret named regcred. This can be created from existing credentials as follows:

   kubectl create secret generic regcred \
   

   --from-file=.dockerconfigjson=<path/to/.docker/config.json> \
   

   --type=kubernetes.io/dockerconfigjson

4. Add your integration secret key. To do this, create a 256-bit base64 encoded secret key. You can provide your own, or generate one with the following command:

   head -c 32 /dev/urandom | base64

5. Create a corresponding Kubernetes secret called qtest-aes-secret-keys for the integration secret key. This should look like this:

   kubectl create secret generic qtest-aes-secret-keys \

   --from-literal=AESsecretKeys=<paste your key here>

   If you need to replace your integration secret key at any point, take a look at how to replace a leaked secret key.

6. If you do not wish to use the Docker config.json file, the secret can also be created directly from the command line:

   kubectl create secret docker-registry regcred --docker-server=<your-registry-server> --docker-username=<your-name> --docker-password=<your-password> --docker-email=<your-email>

   Replace the parameters above as follows:

   • <your-registry-server> is your Private Docker Registry FQDN. Use https://index.docker.io/v1/ for DockerHub.

   • <your-name> is your Docker username.

   • <your-password> is your Docker access token.

   • <your-email> is your Docker email.

Configure secrets for qTest Manager

To seamlessly integrate with apps such as Jenkins, Bamboo, Tosca, or Web and Desktop Explorer, you need to configure secrets for charts with qTest Manager version 2025.2.7 or greater.

Follow these steps to configure secrets for qTest Manager:

1. If you want, create a namespace. See the example code below:

   Copy

   kubectl create namespace qtest --dry-run=client -o yaml | kubectl apply -f
   

   In the example code, we use qtest as the sample namespace. If you want to skip using a namespace, remove -n qtest from all the sample commands to create resources in the default namespace.

2. Create the registry credentials secret. See the example code below:

   Copy

   kubectl create secret generic regcred \
       --from-file=.dockerconfigjson=<path/to/.docker/config.json> \
       --type=kubernetes.io/dockerconfigjson -n qtest

3. Create the qTest Manager secret and store the key-value pairs. See the example code below:

   Copy

   kubectl create secret generic qtest-manager-secret -n qtest \
     --from-literal=oauth.app.sp.access.validity="3600000" \
     --from-literal=oauth.app.sp.secret="{value}" \
     --from-literal=oauth.app.sp.grants="" \
     --from-literal=oauth.app.sessions.secret="{value}" \
     --from-literal=oauth.app.explorer.secret="{value}" \
     --from-literal=oauth.app.qmap.secret="{value}" \
     --from-literal=oauth.app.jenkins.secret="{value}" \
     --from-literal=oauth.app.bamboo.secret="{value}" \
     --from-literal=oauth.app.pulse.secret="{value}" \
     --from-literal=oauth.app.tosca.secret="{value}" \
     --from-literal=oauth.app.web-explorer.secret="{value}" \
     --dry-run=client -o yaml | kubectl apply -f -
   

   Replace {value} in the example codes with your actual secret values. To get secret values, please contact your PSO or Support team.

Create internal secret keys

Some satellite applications require secret keys when you install qTest in Kubernetes. Currently, you need to create internal secrets for Sessions and Pulse.

Create a secret key

Follow these steps to create a secret key:

1. Generate a random 32-character password. You can use any random password generator of your choice, or see the example code below:

   head -c 32 /dev/urandom | base64 | head -c 32

2. Encode the password to base64 to add it to the Kubernetes secret. The following example illustrates a password encoded into base64:

   echo -n AJ5EdHcZWTXm+vTECVfIJVLnoUY3HA6d | base64
   

   QUo1RWRIY1pXVFhtK3ZURUNWZklKVkxub1VZM0hBNmQ=

Store a secret key

After you create a secret key for the satellite application, store the key and its value pair in Kubernetes as a secret labeled qtest-manager-secret.

For Sessions, the key-value pair looks like the following example:

sessions.secret.key: V0Qzd2J2cTJSTkN4VGJ4U2xIVlpqWEx6K2JXRThUSHM=

For Pulse, the key-value pair looks like the following example:

qtestPulseExecutorApiKey: V0Qzd2J2cTJSTkN4VGJ4U2xIVlpqWEx6K2JXRThUSHM=

Store a secret csrfKey

For Parameters and Sessions, you also need to create a random 32 byte Base 64 encoded key for the csrfKey value.

For Parameters, that will look like the following example:

kubectl patch secret qtest-manager-secret \
    -n qtest \
    --type merge \
    -p='{"data":{"csrf.secret.key":"<YOUR_BASE_64_SECRET>"}}'

For Sessions, that will look like the following example:

kubectl patch secret qtest-manager-secret \
    -n qtest \
    --type merge \
    -p='{"data":{"csrfKey":"<YOUR_BASE_64_SECRET>"}}'

Installation

To install qTest Manager 2025.8 and its additional applications, follow the steps below:

1. Add the qTest Helm repository to your environment:

   helm repo add qtest https://tricentis.github.io/qTest.Charts
   helm repo update

2. Install the qTest Manager chart with the release name qtest-manager in the qtest namespace:

   helm install qtest-manager qtest/qtest-mgr -f <values.yaml> -n qtest --create-namespace

   You can use the values-aws-eks.yaml file for reference values.

3. Install other qTest applications as required, using the syntax below:

   helm install <qTest Application> qtest/<qTest Application> -n qtest

   Replace both <qTest Application> strings with one of the values below:

   • Sessions: qtest-sessions

   • Insights: qtest-insights

   • Parameters: qtest-parameters

   • Launch: qtest-launch

   • Pulse: qtest-pulse

   • Scenario: qtest-scenario

Configuration

The following sections list the configurable parameters for qTest Manager, its applications, and your qTest license. At a minimum, the PostgreSQL and elasticSearch parameters should be provided to match your environment.

You can use the provided sample YAML files as a reference during the deployment process.

Ingress Controller

qTest relies on an IngressController to route ingress traffic into the cluster. We recommend SSL offloading/termination to be done at the IngressController. Specific TLS setup instructions depend on the IngressController you have.

To define an IngressController for qTest, specify the IngressControllerClass name via the Helm value ingressClass.controller.

Below is the configuration for AWS ALB IngressController:

ingressClass:
   enabled: true
   controller: ingress.k8s.aws/alb

The configuration for NginX IngressController is as follows:

ingressClass:
   enabled: true
   controller: k8s.io/ingress-nginx

qTest Manager

At a minimum, the PostgreSQL and elasticSearch parameters should be provided to match your environment.

For file persistence, only one of the following options is needed:

• AWS S3: file attachments are stored into the specified S3 bucket or folder.

• StorageClass: used to carve out a PersistentVolumeClaim with the specified size and access mode. If empty, the default StorageClass will be used.

• existingClaim: uses PersistentVolumeClaim as file persistence for qTest if specified.

To see the parameters chart, go to our Helm Repository (opens in a new tab).

qTest Pulse

Use the following command to install the Pulse service:

helm install qtest-pulse-executor qtest/qtest-pulse -n qtest -f values-pulse.yaml

Set Helm chart values for the Pulse service in values-pulse.yaml or with the --set flag.

To see the parameters chart, go to our Helm Repository (opens in a new tab).

qTest Pulse Executor

Use the following command to install the executor service:

helm install qtest-pulse-executor qtest/qtest-pulse -n qtest -f values-pulse-executor.yaml

Set Helm chart values for the Pulse Executor service in values-pulse-executor.yaml or with the --set flag.

To see the parameters chart, go to our Helm Repository (opens in a new tab).

$ helm install qtest-mgr qtest/qtest-mgr -f values-aws-eks.yaml -n
qtest –create-namespace
NAME: qtest-mgr
LAST DEPLOYED: Thu Jan 13 17:49:00 2022
NAMESPACE: qtest
STATUS: deployed
REVISION: 1

$ kubectl -n qtest get pods
NAME					READY	STATUS		RESTARTS	AGE
mgr-ui-deployment-6b77987c79-q2msb	1/1	Running		0		18m

Configure SSL

This section shows how you can set up SSL connections for different qTest applications. Note that additional SSL validation at the pod level may impact the performance of qTest.

qTest Manager

To configure qTest Manager to use SSL, follow these steps:

1. Create your certificates and deploy them as a secret in the same namespace where qTest will be deployed.

   The name of the secret must be qtest-ssl-root-secret.

2. Set the parameter serverAppSSLRequired to true.

3. By default, the pod certificate mounting path is /mnt/secrets/tls. To mount a different directory, change the parameter server.sslMountPath accordingly.

qTest Parameters

To configure qTest Parameters to use SSL, follow these steps:

1. Make sure you have configured qTest Manager to use SSL.

2. In your qTest Parameters values, set the parameter qTestParametersSSLRequired to true.

3. To make changes to the default HTTPS port used for the connection, modify the parameter targetHttpsPort.

4. By default, the pod certificate mounting path is /mnt/secrets/tls. To mount a different directory, change the parameter qTestParametersSSLMountPath accordingly.

Autoscaling

autoscaling:
  enabled: true
  minReplicas:
    ui: 1
    api: 1
    notification: 1
    poller: 1
    default: 1
  maxReplicas:
    ui: 3
    api: 3
    notification: 3
    poller: 1
  targetCPUUtilizationPercentage: 70
  targetMemoryUtilizationPercentage: 70

Limit Ranges and ResourceQuotas

qTest supports ResourceQuotas to limit the amount of resources consumed by the qTest namespace. The default settings are presented below and can be configured to fit your workload:

resourceQuota:
  enabled: true
  hard:
    limits.cpu: "80"
    limits.memory: 400Gi
    requests.cpu: "64"
    requests.memory: 160Gi
    pods: "25"
    persistentvolumeclaims: "50"
    requests.storage: 500Gi

In addition, qTest applies LimitRanges to all containers running in the qTest namespace. The default settings are as follows:

limitRange:
  enabled: true
  limits:
    -max:
       cpu: "2"
       memory: 16Gi
    default:
       cpu: "2"
       memory: 16Gi
    defaultRequest:
       cpu: "2"
       memory: 4Gi      
    type: Container

Uninstall

To uninstall qTest Manager and other qTest applications, follow the steps below:

1. Using the same <qTest Application> string from the installation steps, uninstall every qTest application which you installed after qTest Manager:

   helm uninstall <qTest Application>

2. Once you have uninstalled all your qTest applications, uninstall qTest Manager:

   helm uninstall qtest-manager

Configure and Test Connectivity to qTest Applications

Follow the Configure qTest Applications guide to configure qTest Manager to connect with the other qTest applications you installed. You should also verify that the applications can be accessed and working properly before performing the next step.

What's next

Refer to the following chapters for more information on the qTest containerization with Kubernetes:

• Kubernetes External Secrets with qTest

• Set up qTest with Amazon Elastic Kubernetes Service