Private locations: checking an internal endpoint from inside your network
A hosted check runs from Bucker's locations, so it cannot reach a host that only your own network can. A private location is a place inside your network that runs the checks and reports the results. This page says what Bucker gives you today, what it does not, and how to set one up.
Status. The first form, the Collector recipe, is built. The second, a worker that pulls its checks from Bucker, is not built: it would be software Bucker ships for you to run, which the hosted-only licence decision of 2026-10-17 does not allow until the owner decides it (OD-DP-09). Nothing on this page needs it, and nothing here quietly depends on it. The attribution rules under "How results are attributed" are what the metrics endpoint enforces once it is wired to the location check (the release that carries this page); a deployment that has not got that release stores a request's attributes as sent.
What the recipe is
There is no Bucker software to install. The location is the upstream OpenTelemetry Collector with the httpcheck, tcpcheck and tlscheck receivers, running on a machine you choose. Bucker generates the configuration. The Collector probes your targets on an interval and sends the results to the OTLP metrics endpoint your project already has.
What it covers: status, latency and certificates for HTTP, TCP and TLS targets. It does not run multistep, browser, DNS, gRPC or WebSocket checks, and it does not assert on a response body. Those checks stay hosted. The three receivers are marked alpha upstream.
A minute in which the Collector reported nothing is no data. Bucker never reads a silent location as up.
Who may do what
| Act | Who | Notes |
|---|---|---|
| Create a location | A person with egress:admin (Owner or Admin), acting for themselves |
Human-only: not an agent, a service account, or an OAuth client acting for a person |
| Mint, rotate or re-enrol its key | The same | The key is shown once. Only its digest is stored |
| Render the recipe | Anyone who can configure synthetics on the project | A read. It stores nothing and contains no secret |
| Revoke a location | Anyone who can configure synthetics may request it, an agent included | An ask: it waits for the approval of a person other than the requester, even when an organization policy would allow it. In an organization where nobody else could approve, the request is recorded as an inert draft and nothing changes |
| Add a target | You choose the targets when you render the recipe | Which internal hosts are probed is a person's decision |
Revoking only removes access. Re-enrolling a revoked location is a person minting it a new key.
Setting one up
Create the location:
POST /orgs/{org}/private-locationswith{ "slug": "hq-network" }. A slug is lowercase letters, digits and hyphens, at most 40 characters. An organization holds at most 25 locations, revoked ones included.Mint its key:
POST /orgs/{org}/private-locations/hq-network/key. The response is the only place the key (bplk_…) ever appears. Put it in your secret store.Render the recipe:
POST /orgs/{org}/projects/{project}/private-locations/hq-network/recipewith the targets:{ "targets": [ { "kind": "http", "url": "https://intranet.example/health" }, { "kind": "tcp", "host": "db.internal", "port": 5432 }, { "kind": "tls", "host": "api.internal", "port": 443 } ], "intervalSeconds": 60 }A target URL carries no credentials. At most 50 targets, and an interval of 30 seconds to an hour.
Run an upstream Collector build that includes the three receivers with that file. Set two environment variables in the Collector's own environment, never in the file:
BUCKER_DSN(the project's key) andBUCKER_LOCATION_KEY(step 2).
The recipe sends both credentials on every request: the project's key, and the location's key in the x-bucker-location-key header.
How results are attributed
Results are attributed to a location only through its key.
- A request with a valid key for an active location of your organization is stored as location
private:<slug>, labelled synthetic, under the servicebucker-synthetics. - A request with no key is stored as it is, with any
bucker.location*attribute removed. A project key alone cannot make a metric look as though a private location sent it. - A request with a key that is unknown, rotated away, revoked or another organization's is refused. It is not stored as ordinary data. A Collector still using an old key fails loudly instead of looking healthy.
The recipe sets no location itself. The attribution comes from the key.
Rotating and revoking
Minting a key for a location that already has one rotates it: the old key is refused from that moment. Revoking a location refuses its key from the moment the approval is applied. Its earlier results are kept under the retention your plan states. Re-enrolling is minting a new key.
Every create and every mint is audited with the location's name and a short fingerprint of the key, never the key. A revocation is recorded as a governed operation with the reason.
Where the data lives
Results land in the one US database. A probe location is not a data residency choice.
What is not here
- A Bucker-run worker that pulls checks and returns signed results (OD-DP-09).
- Private-range rules per location. They belong to that worker; the recipe probes exactly the targets you list.
- ICMP, UDP and traceroute (deferred: path diagnosis).