Setting Up Testsigma Agent on Kubernetes

If you already run Kubernetes, you can deploy the Testsigma Agent as a Helm release instead of installing it on a machine. The chart runs the agent together with the Selenium browsers it drives, so a single install gives you a working local execution environment. This article discusses how to install, configure, and verify that release.

This is the Kubernetes equivalent of the Docker Compose setup described in Setting Up Testsigma Agent Locally. Use that page instead if you are installing on a single machine.

What the Chart Deploys

A single pod containing:

1. The Testsigma Agent
2. One or more Selenium browsers, running as sidecars

Plus a PersistentVolumeClaim that keeps the agent registered across restarts.

The agent and the browsers share a pod on purpose. They exchange files through a shared directory during upload and download steps, and the agent reaches each browser on localhost. Splitting them apart breaks file upload steps.

Where the Chart Is Published

The same chart is available from two registries. Both are public and need no credentials.

Choose based on what your cluster is allowed to reach:

• Use Azure Container Registry with global.imageRegistry when egress is restricted, because the chart and every image then come from one host.
• Use GitHub Container Registry when your cluster can already reach Docker Hub. The images are not mirrored there, so global.imageRegistry does not apply and the agent and browser images are pulled from Docker Hub.

The examples in this article use Azure Container Registry. To use GitHub Container Registry instead, swap the chart address and drop the global.imageRegistry flag.

Prerequisites

1. A Kubernetes cluster running 1.23 or later. Version 1.29 or later is recommended, so the browsers can start as native sidecars.
2. Helm 3.8 or later, which is required for OCI chart support.

3. A default StorageClass, or the name of one you want to use. Check with:

   kubectl get storageclass

4. A node with enough free capacity for the whole pod, agent and browsers together. With the default Chrome-only setup the pod requests 1 CPU and 3Gi; with Firefox and Edge also enabled it requests 2 CPU and 5Gi. The pod is scheduled as a unit, so it must fit on a single node.
5. Outbound access from the cluster to your Testsigma instance and to the registry that serves the chart and images.

Install the Agent

1. In the Testsigma application, navigate to Agents and create an agent using the Activate Later option. Select the agent, open the Config tab, and copy the Activation Key.

2. Create a namespace and store the activation key in a secret. Write the key to a temporary file rather than passing it on the command line, so it does not end up in your shell history or in the process list:

   kubectl create namespace testsigma
   
   umask 077 && cat > activation-key.txt   # paste the key, then press Ctrl+D
   
   kubectl -n testsigma create secret generic testsigma-agent-auth \
    --from-file=TS_ACTIVATION_KEY=./activation-key.txt
   
   rm activation-key.txt

   If you manage secrets with a tool such as External Secrets Operator or Sealed Secrets, create testsigma-agent-auth through that instead.

3. Install the chart:

   helm install ts-agent oci://testsigmaregistry.azurecr.io/charts/testsigma-agent \
    --version 0.2.0 -n testsigma \
    --set global.imageRegistry=testsigmaregistry.azurecr.io \
    --set agent.auth.existingSecret=testsigma-agent-auth

4. Wait for the pod to become ready:

   kubectl -n testsigma rollout status statefulset/ts-agent-testsigma-agent

5. The agent appears under Agents in the Testsigma application once it registers.

To install the same chart from GitHub Container Registry, use this instead of step 3:

helm install ts-agent oci://ghcr.io/testsigmainc/charts/testsigma-agent \
  --version 0.2.0 -n testsigma \
  --set agent.auth.existingSecret=testsigma-agent-auth

The remaining steps are identical. Every --set flag shown in this article applies to both registries, apart from global.imageRegistry.

The first start takes a few minutes. The browser images are over 1 GB each, and the browsers must pass their readiness checks before the agent container starts.

Register a New Agent Automatically

Instead of creating the agent in the application first, the agent can register itself on startup. This suits environments where agents are created and destroyed frequently.

1. Obtain an API Key from the Testsigma application.

2. Create the namespace and store the key in a secret, keeping it off the command line for the same reason as above:

   kubectl create namespace testsigma
   
   umask 077 && cat > api-key.txt          # paste the key, then press Ctrl+D
   
   kubectl -n testsigma create secret generic testsigma-agent-auth \
    --from-file=TS_AUTO_REGISTRATION_KEY=./api-key.txt
   
   rm api-key.txt

3. Install with auto registration enabled:

   helm install ts-agent oci://testsigmaregistry.azurecr.io/charts/testsigma-agent \
    --version 0.2.0 -n testsigma \
    --set global.imageRegistry=testsigmaregistry.azurecr.io \
    --set agent.auth.mode=autoRegistration \
    --set agent.auth.existingSecret=testsigma-agent-auth

Each agent registers under its own pod name, so you can run several at once by adding --set agent.replicaCount=3 to the install command above.

To choose the name shown in the application, set agent.auth.autoRegistration.title.

Select Your Testsigma Region

The agent image is built against a specific Testsigma region, so the three builds are not interchangeable. Set agent.region to match the address you sign in to:

Add the flag to the install command:

--set agent.region=eu

If the agent is already installed, apply it with an upgrade:

helm upgrade ts-agent oci://testsigmaregistry.azurecr.io/charts/testsigma-agent \
  --version 0.2.0 -n testsigma --reuse-values \
  --set agent.region=eu

If the region does not match your account, the agent starts but cannot register, because it contacts the wrong Testsigma address.

Enable Additional Browsers

Chrome is enabled by default. Firefox and Edge are available and disabled.

To enable them during the initial install, use this in place of step 3:

helm install ts-agent oci://testsigmaregistry.azurecr.io/charts/testsigma-agent \
  --version 0.2.0 -n testsigma \
  --set global.imageRegistry=testsigmaregistry.azurecr.io \
  --set agent.auth.existingSecret=testsigma-agent-auth \
  --set browsers.firefox.enabled=true \
  --set browsers.edge.enabled=true

To add them to an existing release:

helm upgrade ts-agent oci://testsigmaregistry.azurecr.io/charts/testsigma-agent \
  --version 0.2.0 -n testsigma --reuse-values \
  --set browsers.firefox.enabled=true \
  --set browsers.edge.enabled=true

The pod is recreated, so the agent goes offline briefly and returns with the extra browsers registered.

Each browser you enable is reported to Testsigma as available on that agent, and adds 0.5 CPU and 1Gi to the pod's requests. Enable only the browsers you plan to use.

Install Using Argo CD

Argo CD does not detect OCI registries automatically, so register the repository first.

1. Navigate to Settings > Repositories > CONNECT REPO > VIA HTTPS and enter:

   Field	Value
   Type	helm
   Name	testsigma-charts
   Repository URL	testsigmaregistry.azurecr.io/charts, or ghcr.io/testsigmainc/charts
   Enable OCI	Selected
   Username and Password	Leave empty

2. Create the credential secret in the destination namespace, as shown in Install the Agent.

3. Create the application:

   apiVersion: argoproj.io/v1alpha1
   kind: Application
   metadata:
    name: testsigma-agent
    namespace: argocd
   spec:
    project: default
    source:
      repoURL: testsigmaregistry.azurecr.io/charts
      chart: testsigma-agent
      targetRevision: 0.2.0
      helm:
        releaseName: ts-agent
        values: |
          tests:
            enabled: false
          global:
            imageRegistry: testsigmaregistry.azurecr.io
          agent:
            region: us
            auth:
              mode: activationKey
              existingSecret: testsigma-agent-auth
    destination:
      server: https://kubernetes.default.svc
      namespace: testsigma
    syncPolicy:
      syncOptions:
        - CreateNamespace=true

4. Sync the application. CreateNamespace=true changes how a sync behaves, it does not start one, so a newly created application stays OutOfSync until you trigger it. In the UI, open the application and select SYNC, or from the CLI:

   argocd app sync testsigma-agent

   To have Argo CD deploy and self-heal without manual syncs, add this to the application instead:

    syncPolicy:
      automated:
        prune: true
        selfHeal: true
      syncOptions:
        - CreateNamespace=true

Points to note:

• repoURL holds the registry path only. The chart name belongs in chart, and there is no oci:// prefix.
• targetRevision is the chart version, not the agent version.
• Argo CD does not run Helm test hooks, so set tests.enabled to false and verify manually.
• To use GitHub Container Registry, set repoURL to ghcr.io/testsigmainc/charts and remove the global.imageRegistry value.

Verify the Installation

If you installed with Helm, run the bundled checks, which confirm the agent and every enabled browser are responding:

helm test ts-agent -n testsigma

Argo CD does not run Helm test hooks, so on an Argo CD install check the application state instead, then use the direct checks below:

argocd app get testsigma-agent

Synced and Healthy means the chart is applied and the pod is ready.

To inspect the agent directly, on either kind of install:

kubectl -n testsigma logs ts-agent-testsigma-agent-0 -c agent

kubectl -n testsigma exec ts-agent-testsigma-agent-0 -c agent -- \
  curl -sf http://127.0.0.1:8383/agent/health

Finally, confirm the agent is listed under Agents in the Testsigma application and run a test against it.

Configuration Reference

Pass these with --set, or collect them in a values file and use -f values.yaml. To see every available setting:

helm show values oci://testsigmaregistry.azurecr.io/charts/testsigma-agent --version 0.2.0

Upgrade and Uninstall

Manage the release with whichever tool installed it. Helm commands do not apply to an application deployed by Argo CD, and editing an Argo CD application by hand is reverted on the next sync.

Installed with Helm

To move to a newer chart version:

helm upgrade ts-agent oci://testsigmaregistry.azurecr.io/charts/testsigma-agent \
  --version <NEW_VERSION> -n testsigma --reuse-values

To remove the release:

helm uninstall ts-agent -n testsigma

Installed with Argo CD

Change targetRevision in the application to the new chart version, then sync. To remove it, delete the application:

argocd app set testsigma-agent --revision <NEW_VERSION>
argocd app sync testsigma-agent

argocd app delete testsigma-agent

The volume is kept so the agent can be reinstalled with the same registration. Delete it separately if you do not need it:

kubectl -n testsigma delete pvc data-ts-agent-testsigma-agent-0

Troubleshooting

For issues with agent startup or registration itself, see Agent - Startup and Registration Errors.