Private locations (UPT-013)

A private location runs checks from inside your network. The probe makes outbound HTTPS calls only; it opens no listener, so no inbound firewall rule is needed.

Create

POST /v1/projects/{p}/locations {"name": "dc1", "prefer_ip_family": "auto"} (needs ManageMonitors; plan limit private_locations). The response carries key (wtp_...) once; only its SHA-256 is stored. GET, PATCH and DELETE /v1/projects/{p}/locations[/{id}] list, rename or delete (deleting removes the key). Monitors use the location as private:dc1 next to public ones.

Run the probe

wt-probe --edge https://watchtower.example.com --location dc1 --location-key wtp_... [--prefer-ip auto|ipv4|ipv6]

(WT_PROBE_KEY also works.) Kubernetes: infra/kubernetes/probe (Deployment, optional HPA, NetworkPolicy with DNS plus a target allowlist, non-root, read-only root). Docker or Podman: infra/docker/probe.compose.yml.

Protocol: POST /v1/probe/claim (25 to 30 s long poll, returns the jobs of monitors assigned to this location, never another project's), POST /v1/probe/result, POST /v1/probe/heartbeat every 30 s.

Secrets

Vault values a job references are sealed to the probe's X25519 key (registered at the first claim) and opened on the probe; the edge never sends them in plaintext on this path. The key pair is derived from the location key, so rotating the location key (delete and recreate) rotates it too.

IPv4 and IPv6

prefer_ip_family ipv4 or ipv6 restricts check connections of that probe to the family (a target that has only the other family fails). auto allows both.

Offline

No heartbeat for 3 intervals (90 s) marks the location offline (GET .../locations shows state: offline). A failing result from an offline private location is reported as unknown, not down: the probe being gone says nothing about your target.

What a private probe may reach

Private probes may reach private address space (that is the point), but never cloud metadata endpoints or multicast; public locations never reach private space.