Kubernetes Agent Installation

The ThousandEyes Kubernetes Agent enables you to deploy and operate Enterprise Agents natively in Kubernetes clusters through a YAML manifest, replacing manually managed containers or pods with a repeatable, stateful deployment model.

This guide details the supported test types, prerequisites, and installation instructions.

Kubernetes agents do not support agent modules, including BrowserBot.

Supported Test Types

Kubernetes Agents support the following test types:

• Agent-to-server tests

• Agent-to-agent tests

• HTTP server tests

• API tests

• FTP tests

• DNS server tests

• DNS trace tests

• DNSSEC tests

• RTP tests

• Voice tests

Using a Kubernetes agent as the target for agent-to-agent or RTP tests requires additional ingress configuration in the cluster. See the Kubernetes documentation.

Page load and transaction tests are not supported.

Prerequisites

Before you deploy a Kubernetes Agent, verify that you have the following:

• Administrative access to the Kubernetes cluster.

• kubectl configured for the target cluster.

• Kubernetes version 1.32 or later for the documented stable PVC-retention behavior.

• A StorageClass that supports ReadWriteOnce.

• A ThousandEyes account with permission to install Enterprise Agents. For more information, see Role-Based Access Control, Explained.

• Permission to create namespaces, Secrets, StatefulSets, pods, and persistent volume claims (PVCs).

• The common Enterprise Agent installation prerequisites.

Kubernetes agents are based on the Docker agent image without BrowserBot and share the same hardware requirements as Docker agents.

Configure and Download the YAML Manifest

1. On the Network & App Synthetics page, select Add Agent, then open the Kubernetes tab.

2. Configure the following Kubernetes settings to generate the downloadable YAML manifest:

   • Instance name: Use lowercase letters, numbers, and hyphens only. The value sets the StatefulSet name (te-agent-<instance-name>), label (app: <instance-name>), container name, and service name.

   • Replica count: The number of pods to deploy.

   • PVC storage size: The amount of storage allocated to the PVC.

3. Download the generated te-agent-statefulset.yaml file and save it locally.

Create the Namespace

Copy the command from the ThousandEyes platform and run it in a terminal:

kubectl create namespace thousandeyes

Create the Account Token Secret

Copy the complete command generated by the ThousandEyes platform and paste it into a terminal. Do not manually type or edit the Account Group Token.

kubectl create secret generic te-credentials \
  --from-literal=ACCOUNT_TOKEN="<ACCOUNT_GROUP_TOKEN>" \
  -n thousandeyes

The command contains a sensitive Account Group Token. Do not share it, commit it, or save it in a script.

Verify that the Secret exists. This command does not print the token:

kubectl get secret te-credentials -n thousandeyes

Customize the StatefulSet (Optional)

Open te-agent-statefulset.yaml and adjust the following values as needed.

Changing other values may affect agent functionality and is not recommended.

Setting	Configuration	Allowed value
Replicas	Changeable	1-10
Container name	Changeable	Lowercase letters, numbers, and hyphens only
Security capabilities	Static	Fixed at NET_RAW
TEAGENT_REGISTRY	Static	Fixed at sc1.thousandeyes.com
Memory request	Changeable	1 Gi or greater
CPU request	Changeable	100m or greater
TEAGENT_INET	Changeable	4 or 6 (IPv4 or IPv6)
Volume mount path	Static	Exclude /var/lib/te-browserbot
Storage request	Changeable	PVC storage size

Deploy the StatefulSet

Copy the command from the ThousandEyes platform. This command deploys the specified number of agents:

kubectl apply -f te-agent-statefulset.yaml -n thousandeyes

Verify the Deployment

Quick Status

kubectl get statefulset,pods,pvc -n thousandeyes

When the deployment is healthy:

• The StatefulSet READY column shows 3/3, or your configured replica count.

• Each pod shows READY 1/1 and STATUS Running.

• Each PVC shows STATUS Bound.

Watch Pods Start

kubectl get pods -n thousandeyes -w

Press Ctrl+C to stop watching.

Check Agent Registration Logs

Replace <statefulset-name> with the StatefulSet name generated from your instance name. The pod index in this example is 0.

kubectl exec -it <statefulset-name>-0 -n thousandeyes -- tail -f /var/log/agent/te-agent.log

Healthy registration logs include messages similar to the following:

Attempting to get agent id from https://sc1.thousandeyes.com
Controller tells us we are enabled
Starting task processors

Confirm Registration in the ThousandEyes Portal

After registration succeeds, the agents appear under Agents in the ThousandEyes platform. The new agents will report their names in the format <statefulset-name>-0, <statefulset-name>-1 etc., based on the number of replicas you configure. They will also be categorized under the “Kubernetes” installation type. Registration may take 1-2 minutes.

Scale Replicas

Replace <statefulset-name> with the StatefulSet name generated from your instance name:

kubectl scale statefulset <statefulset-name> -n thousandeyes --replicas=2

Alternatively, edit replicas in the YAML manifest and apply it again.

View Logs for a Specific Pod

Replace <statefulset-name> with the StatefulSet name and <pod-index> with the pod index:

kubectl logs <statefulset-name>-<pod-index> -n thousandeyes
kubectl exec <statefulset-name>-<pod-index> -n thousandeyes -- tail -100 /var/log/agent/te-agent.log

Describe a Failing Pod

kubectl describe pod <statefulset-name>-<pod-index> -n thousandeyes

Remove the Deployment

Replace <statefulset-name> with the StatefulSet name generated from your instance name:

kubectl delete statefulset <statefulset-name> -n thousandeyes
kubectl delete secret te-credentials -n thousandeyes
kubectl delete namespace thousandeyes