Kubernetes Agent

Kubernetes Agent

The Kubernetes agent watches one Kubernetes cluster and reports workloads and pods to Trove.

It is intended to run in-cluster as a Deployment with read-only RBAC.

What it reports

The Kubernetes agent reports Kubernetes workload objects and child pods.

Typical service kinds include:

• deployment
• statefulset
• daemonset
• pod

Pods can link to parent workloads through Trove's parent_id model. This lets the dashboard show the relationship between a Deployment and the Pods it owns.

Deployment shape

Use the manifest in:

deploy/kubernetes/trove-agent.yaml

The shipped manifest includes:

• ServiceAccount
• ClusterRole with read-only verbs
• ClusterRoleBinding
• Deployment for the agent
• Secret or environment values for Trove server URL and token

Create the token on the Trove server, then create the namespace and Secret:

If you used the server-only Quickstart, use the TROVE_TOKEN already saved in its .env for this first agent. For an additional agent, mint a new token:

docker compose exec server trove-server agent create k8s-homelab
kubectl create namespace trove
kubectl -n trove create secret generic trove-agent \
  --from-literal=token='AGENT_TOKEN_VALUE'

Download the manifest, edit TROVE_SERVER_URL and TROVE_CLUSTER_NAME, then apply it:

curl -fsSLO https://raw.githubusercontent.com/techdox/trove/main/deploy/kubernetes/trove-agent.yaml
kubectl apply -f trove-agent.yaml
kubectl -n trove rollout status deploy/trove-agent
kubectl -n trove logs deploy/trove-agent -f

Required configuration

Variable	Required	Purpose
TROVE_SERVER_URL	yes	Trove server URL reachable from the cluster.
TROVE_TOKEN	yes	Trove agent token.
TROVE_INTERVAL	no	Push interval.
TROVE_AGENT_NAME	no	Informational report name. The dashboard agent name comes from agent create.
TROVE_CLUSTER_NAME	no	Dashboard host name for the cluster. Default kubernetes.
TROVE_KUBE_NAMESPACE	no	Restrict discovery to one namespace. Default is all namespaces.

Server URL from inside the cluster

The URL must be reachable from the pod.

Good examples:

http://trove-server.trove.svc.cluster.local:8080
http://192.168.68.56:8080
https://trove.example.com

Bad unless the server is in the same pod:

http://localhost:8080

RBAC principle

The Kubernetes agent should have read-only access. It needs to list/watch/get the resources it reports. It should not have update, patch, delete, create, exec, or attach rights.

Parent-child model

Kubernetes creates a lot of child objects. Trove models this with:

services.parent_id

The agent reports parent_external_id for child pods. During ingest, the server resolves that external parent ID to the internal service ID.

This is intentionally resolved per full-state report. Parent and child are both present in the report, so ordering does not matter.

Workloads report ready/desired state and pods report phase/readiness. Unhealthy pods include a short reason such as CrashLoopBackOff, ImagePullBackOff, OOMKilled, or a non-zero exit code when Kubernetes provides one. The host header also includes Kubernetes version/platform metadata.

Out-of-cluster mode

In-cluster deployment is the normal path. For a jump host or other out-of-cluster collector, configure TROVE_KUBE_APISERVER, TROVE_KUBE_TOKEN, and either TROVE_KUBE_CA or the test-only TROVE_KUBE_INSECURE=true. Keep the token read-only.

Common issues

Agent pod is running but dashboard is empty

Check logs:

kubectl logs deploy/trove-agent -n trove

Look for:

• Kubernetes API permission errors
• push failed errors
• DNS or network failures to the Trove server
• 401 from the Trove server

Pods show but parent links are missing

That usually means the agent is not reporting parent_external_id, or the parent object is not included in the same report.

Too many state alerts during deployments

Pod churn can produce removed state events. If that is too noisy, trim alert types:

TROVE_ALERT_EVENTS=agent,health

See Alerts-and-Digest.