DNS and service discovery
Edgelet provides bridge-network service discovery for microservices on a single node. Behavior depends on containerEngine in config.
| Engine | Mechanism | Authoritative resolver |
|---|---|---|
edgelet (linux embed) | Embedded DNS on bridge gateway + per-container resolv.conf / /etc/hosts | Yes |
docker | User-defined bridge edgelet + network aliases + ExtraHosts | No |
podman | Same as docker (shared client) | No |
Zone: svc.bridge.local (default).
Bridge: Linux bridge edgelet0, CIDR 172.18.0.0/16, Docker/Podman network name edgelet.
See also: Container engines, Control plane on node.
When DNS applies
| Mode | Bridge | Service discovery |
|---|---|---|
hostNetworkMode: false | Workload joins edgelet bridge | Aliases + (embed) resolver records |
hostNetworkMode: true | Host network | No bridge aliases; no embed resolv.conf mount |
Host-network workloads use the host resolver directly.
FQDN catalog
Reserved system names (managed scope)
| FQDN | Role |
|---|---|
edgelet.default.svc.bridge.local | Edgelet node agent (bridge gateway) |
router.default.svc.bridge.local | Router microservice |
nats.default.svc.bridge.local | NATS microservice |
Per-workload names
For application myapp and microservice worker:
| Form | Example |
|---|---|
| Short (bridge alias / in-zone) | myapp.worker |
| FQDN | myapp.worker.svc.bridge.local |
| UUID alias | iofog_<uuid> and iofog_<uuid>.svc.bridge.local |
The iofog_ prefix on UUID aliases is a stable token in resolver code. It is not legacy product branding.
Control plane (three FQDNs)
For metadata.namespace = default, metadata.name = pot:
| # | FQDN |
|---|---|
| 1 | edgelet.controller.svc.bridge.local |
| 2 | controller.default.svc.bridge.local |
| 3 | default.pot.svc.bridge.local |
Identity comes from manifest metadata. See Control plane on node.
Embedded engine (containerEngine: edgelet)
Linux only. The embedded resolver listens on the bridge gateway for svc.bridge.local queries and forwards out-of-zone queries to host /etc/resolv.conf upstreams.
Non-host-network pods receive:
resolv.conf— nameserver = bridge gateway IP/etc/hosts— userextraHostsplus baseline entries
DNS workload snapshot persists at /var/lib/edgelet/dns/snapshot-v1.json (restore on startup).
Observability
When containerEngine: edgelet, GET /v1/system/status includes DNS fields such as dnsStarted, dnsHealth, dnsQueriesTotal, and dnsForwardingDegraded.
edgelet system status -o json | jq '{dnsStarted, dnsHealth, dnsForwardingDegraded}'
Docker and Podman
External engines do not start the embedded resolver. Discovery uses Docker networking on the shared edgelet bridge:
- Short aliases:
<application>.<name>on the bridge endpoint - Control plane extras:
edgelet.controller,controller.<namespace> - ExtraHosts in
/etc/hostsfor reserved FQDNs (edgelet.default.svc.bridge.local, router, nats)
Host-network mode: no ExtraHosts, no bridge network.
Troubleshooting
| Symptom | Checks |
|---|---|
| Name does not resolve (embed) | edgelet system status → dnsStarted, dnsHealth; verify workload not host-network |
| Name does not resolve (docker) | docker network inspect edgelet; container on network; aliases in inspect |
| Router/NATS unreachable | System MS running; ExtraHosts populated |
| External name fails (embed) | dnsForwardingDegraded; host /etc/resolv.conf upstreams |
| Control plane DNS wrong | Confirm metadata.namespace / metadata.name; see FQDN table above |
More: Troubleshooting.
See also
- Deploy manifests —
extraHosts,hostNetworkMode - Workload continuity — restart behavior on bridge workloads