Local Network Discovery (mDNS)
Relevant source files
The following files were used as context for generating this wiki page:
The Local Network Discovery system in swimctl enables the swimming pool automation controller to be reachable on the local network via human-readable hostnames rather than static IP addresses. This is primarily achieved through the deployment of an mDNS (Multicast DNS) responder that monitors Kubernetes resources and advertises them to the local network segment.
The implementation relies on the external-mdns controller, which integrates with the Kubernetes API to watch for Ingress and Service resources. By utilizing the hostNetwork, the discovery service can broadcast availability directly to the physical network interface of the host machine, such as a Raspberry Pi.
Sources: external-mdns.yaml:49-65, values.yml:85-92
Architecture and Components
The discovery architecture consists of a controller running within the kube-system namespace. It is granted specific RBAC permissions to observe the state of the cluster and broadcast these states over mDNS.
External mDNS Controller
The core component is a Deployment running the blakec/external-mdns:latest image. It is configured to operate on the host's network stack (hostNetwork: true) to ensure that multicast packets reach the local network. It takes two primary arguments to define its discovery scope: -source=ingress and -source=service.
Sources: external-mdns.yaml:49-67
Discovery Data Flow
The controller acts as a bridge between the internal Kubernetes service discovery and the external local area network (LAN).
The diagram shows how the external-mdns pod watches for resource changes and broadcasts them to the local network.
Sources: external-mdns.yaml:57-67, values.yml:85-88
Security and Permissions
To function correctly, the mDNS controller requires broad read access across the cluster to identify resources that need to be advertised.
RBAC Configuration
A dedicated ServiceAccount, ClusterRole, and ClusterRoleBinding are established to grant the necessary permissions. The controller is authorized to list and watch services and ingresses across all namespaces.
| Component | Resource | Verbs | Purpose |
|---|---|---|---|
| ClusterRole | services | list, watch | Monitor internal services for discovery |
| ClusterRole | ingresses | list, watch | Monitor external-facing hostnames |
| ClusterRole | * | * | Broad API group access for resource detection |
Sources: external-mdns.yaml:1-40
Configured Hostnames
The system is configured to expose the main automation interface via a local TLD (Top-Level Domain).
Ingress Discovery
The primary entry point for the controller is defined in the Helm values, specifying the host swimctl.local. When the Ingress controller processes this resource, external-mdns detects the host definition and begins broadcasting the mapping.
- Hostname:
swimctl.local - Path:
/ - Path Type:
ImplementationSpecific
Sources: values.yml:85-92
Infrastructure Requirements
For mDNS and overall network discovery to function reliably on the target hardware (Raspberry Pi), specific host-level configurations are required during the setup phase.
- cgroups Enabling: Required for container resource management and network isolation.
- Host Network Access: The
external-mdnsandsmarter-device-managercomponents utilizehostNetwork: trueto bypass the container network interface (CNI) for direct hardware/network interaction. - Hostname Setting: The Raspberry Pi's hostname is used during the
k3supinstallation to establish the node identity and context.
Sources: README.md:9-15, README.md:31-40, smarter-device-manager.yaml:39
Summary
Local Network Discovery in swimctl provides zero-configuration access to the pool controller. By deploying an mDNS responder that synchronizes Kubernetes Ingress rules with local network broadcasts, users can access the system at http://swimctl.local without managing DNS servers or static IP reservations.