Locations & Agents

A location is a place checks run from; agents are the processes that run them. A monitor picks one or more locations, and the agents of those locations run its checks.

You create locations in KubeSense. Agents are never created there: started with a location's token, they register themselves and appear under that location.

Locations and agents are managed under Settings → Synthetics → Locations & agents.

---

Built-in Location

• Kubernetes — the in-cluster agents form the in-cluster location automatically, with two agents spread across nodes.
• VM — the agents from Deployment form the vm location.

These run checks from inside your network, against internal and public endpoints. The in-cluster agents do not run Kubernetes resource checks; for those, install an agent with the synthetics-agent chart and k8sChecks=true.

---

Private Locations

Add a private location for each other place you want to check from: another cluster, a VM in another network, a data centre or a cloud region.

Step 1 — Make the agent endpoint reachable

Agents outside the KubeSense cluster or VM reach synthetics-api over HTTPS.

• Kubernetes — enable the agent ingress. It routes only /api/v1/probes/ and /healthz, on the KubeSense host with its TLS:

  synthetics:
    agentIngress:
      enabled: true
      # host: synthetics-agents.example.com   # optional: a host of its own
      # tls: { enabled: true, secretName: synthetics-agents-tls }

• VM — put a reverse proxy with TLS in front of synthetics-api and forward only /api/v1/probes/ and /healthz to it. Nothing else of synthetics-api should be reachable from outside.

Without this, the location's install commands warn: These commands work only inside the KubeSense cluster.

Step 2 — Add the location

Click Add private location and fill in:

Click Create. The dialog switches to Install agents for <name>.

Step 3 — Install agents

1. Click Generate token. The token is shown once — copy it now. It works only for this location and can be revoked.
2. Pick the helm, docker or kubectl tab, and Standard agent or Browser agent. The token is filled into the command.
3. Run the command where the agent should run.

The Helm command installs the synthetics-agent chart from https://helm.kubesense.ai. Agents pull their images from the KubeSense registry, so the machine or cluster they run on needs pull access; with Helm, add --set imagePullSecrets[0].name=<secret>. More agent settings (proxy, DNS, allowed domains, custom CAs) are in Configuration.

The agent appears as online under the location within a minute.

---

The Locations Page

Locations tab

Click a location to open its drawer:

• Facts — Region, Provider, Coordinates, Monitors run on (one agent each or every agent), Created, Updated, Labels.
• Install agent — the install panel from step 3.
• Agents tab — the location's agents, with status, version, last seen and capabilities.
• Registration tokens tab — every token, with its status, creation time and last use. Generate another token creates a new one; revoke a token to stop new agents registering with it (agents already registered keep running).
• ⋯ → Edit / Delete — change the location's fields, or delete it.

Agents tab

Every agent of every location: Agent, Status, Region, Location, Version, Last seen, Labels, Capabilities (browser for browser agents). Click an agent to see which token it registered with, its labels, its effective configuration (Configuration tab) and its reported load (Load tab).

---

Availability

The agents of a location share its monitors: each monitor runs on one online agent, and the monitors are spread evenly across the agents. A second agent therefore adds failover without running every check twice, and more agents add capacity. Browser tests are shared among the location's browser agents. Run two agents per location on different machines, so one going down loses no checks. The in-cluster agents already run two replicas, spread across nodes.

When an agent goes offline, its monitors move to the location's other agents; when it comes back, they move back. During the move those monitors do not run, but the location keeps its last state, so no alert fires (a failure that starts in that gap is seen that much later):

These times are settings — see Handover. For no gap at all, turn on Run every monitor on every agent for the location: every agent then runs every monitor, each run counts as its own vantage point, and the location threshold of a monitor counts agents.

• Agents chosen in a monitor under Advanced: specific agents, agents by label each run that monitor, whatever the location's setting.
• When a location that has agents has had none online for 5 minutes, the alert rule [Synthetics] Location has no online agent fires.
• Agents keep results while synthetics-api is unreachable, and send them when it is back.

To check different networks or regions, add more locations rather than more agents.