Domains¶
Every name answers three questions: what is it (picks the zone), where
is it (picks the label), and who may reach it (a gateway decision, never
part of the name). Decided 2026-10-16; supersedes the May 2026 mapping that
kept hosts on freckle.systems.
Zones and roles¶
| Zone | Role | Label |
|---|---|---|
freckle.network |
anything physical or infra: servers, BMCs, switches, routers, firewalls, APs, PDUs, UPSes, the NAS | site (btx1, den1) |
freckle.tools |
anything a human opens: app UIs, ops UIs (Grafana, Hubble, Rook, Alertmanager, Flux), storage as a service alias | environment (fairy, atlantis) |
freckle.services |
anything a machine talks to: Kubernetes API, OIDC issuer and JWKS, schema host, webhooks, MCP endpoints, S3, tunnel plumbing | environment |
freckle.media |
the media stack (Jellyfin, *arr, downloaders) | environment |
freckle.chat |
Matrix | — |
freckle.id |
identity provider | — |
freckle.family |
public-facing family things | — |
freckle.games |
games portal at the apex (tailnet only); game servers | apex for portal; environment for servers |
freckle.rocks |
personal public sites | — |
freckle.systems |
retired — draining to empty; no new names | — |
freckle.vision, freckle.build, freckle.email, freckle.community, freckle.management |
parked; registered because available | — |
frecklefamily.com, frecklesystems.com |
redirects to the dot-TLD siblings only | — |
A function zone wins over freckle.tools when one fits: Sonarr is
sonarr.fairy.freckle.media, not .tools.
.tools or .services?¶
Open the name in a browser. A page means .tools. JSON, a 401, or a
protocol handshake means .services — even if a person once pasted the URL
into a config. MCP endpoints, the Kubernetes API, webhooks and OIDC discovery
are all .services.
The split is about gateway treatment, not taste: .tools names get the login
redirect, the ID-token cookie and friendly error pages; .services names get
bearer tokens, mTLS or no auth, and a login redirect there is a bug. Keeping
them on separate zones lets gateway policy and certificate SANs follow the
domain instead of being per-route exceptions.
Labels¶
Two label sets with two meanings. They look alike today because each site hosts one environment, but they are different axes.
Physical site (.network) |
Environment code name (everything else) |
|---|---|
btx1 — the house |
fairy — the house's environment (the house keeps its name across moves) |
den1 — the colo |
atlantis — the colo's environment |
A datacenter is always named by site: moving it is a new site, not a lift. The
environment names stay put through a move, so every .network name changes
and nothing on .tools or .services does.
A service that spans environments, or is not tied to one, drops the label:
harvest.freckle.tools, watch.freckle.media.
Patterns¶
| Kind | Pattern | Example |
|---|---|---|
| Host, primary interface | <host>.<site>.freckle.network |
store01.btx1.freckle.network |
| Host, out-of-band / BMC | <host>-mgmt.<site>.freckle.network |
cn02-mgmt.btx1.freckle.network |
| Host, extra interface | <iface>.<host>.<site>.freckle.network |
e1-48.spine1.den1.freckle.network |
| Human-facing app | <app>.<env>.freckle.tools |
grafana.fairy.freckle.tools |
| Storage as a service | <role>.<env>.freckle.tools → CNAME to the host |
fs.fairy.freckle.tools → store01.btx1.freckle.network |
| Machine endpoint | <name>.<env>.freckle.services |
konflate.fairy.freckle.services |
| Kubernetes API | api.<cluster>.freckle.services |
api.fairy-k8s01.freckle.services |
| Environment-less machine endpoint | <name>.freckle.services |
k8s-oidc.freckle.services, fairy-cf-tun-gw.freckle.services |
| Function zone app | <app>.<env>.<zone> |
sonarr.fairy.freckle.media |
Hosts and services are different things: a NAS is a host on .network; the
share people mount is a service alias on .tools. Replace the NAS and only
the alias moves.
The Kubernetes API is labelled by cluster, not environment. An environment's
.services names may one day be served by more than one cluster, but an API
name must always mean exactly one cluster: api.fairy-k8s01, not api.fairy.
Exposure¶
Nothing on the internal gateway is anonymous. The tailnet gateway got
identity for free from Tailscale ACLs; the internal gateway is reachable from
every allowed VLAN, so every route on it must be gated before it moves: either
the app's own login (Grafana, Paperless, Mealie…) or an Envoy Gateway
SecurityPolicy (OIDC against pocket-id, with the jwt provider validating
the cookie — see kubernetes/apps/networking/cilium/app/oidc.yaml). The
network layer adds a second cut: the UDM keeps guest and IoT VLANs away from
the internal LB pools entirely.
Every name exists in the internal zones. It exists publicly only when a
route sits on the tunnel or public gateway, because only the Cloudflare
external-dns instances write public records. Moving an app from internal-only
to public is a parentRef change; the hostname never moves.
freckle.networknever has public records. The Cloudflare zone stays delegated but empty so DNS-01 can still issue certificates for internal names (ACME only needs the_acme-challengeTXT to be public).freckle.tools,freckle.services,freckle.media(andfreckle.systemsuntil it is empty) are split-horizon: Cloudflare serves the public view, BIND serves a superset internally. See Internal DNS.
MCP servers¶
MCP endpoints are .services names, but they never get a route of their own:
all of them sit behind the MCP gateway, which gives humans a
freckle.id login and agents a ServiceAccount-token check, plus per-caller tool
authorization. One name for humans (mcp.<env>.freckle.services), one for
agents (mcp-agents.<env>.freckle.services).
Reverse DNS¶
PTRs come only from the freckle.network host map in the private repo
(tofu/platform/internal-dns-records.tf): one source for forward and reverse.
LoadBalancer addresses get no PTRs.
Migration¶
.toolsadded to the internal DNS stack (done with this page) so new names resolve before anything moves.- Hosts: den1 and btx1 iron into the
freckle.networkmap;hw.freckle.systemsand the old*.den1.freckle.systemsnames retired; device-held aliases created (fs.fairy.freckle.tools) with a transition CNAME from the old name until clients are re-pointed. - Machine endpoints: the three API names →
api.<cluster>.freckle.services; OIDC issuer, JWKS and schemas →.services. The OIDC issuer is trusted by the WIF pool, so the old name stays until the pool is re-bootstrapped. - Human-facing apps move during the internal gateway migration, one route at a time, with certificates following the routes.
freckle.systemsgoes quiet; its certificate SANs shrink to nothing; the zone is left delegated and empty.
Transition aliases¶
| Old name | New name | Remove when |
|---|---|---|
store01.fairy.freckle.systems |
fs.fairy.freckle.tools |
laptops' Time Machine targets re-pointed |