ContextQMD
Back to Go Micro

ADR-004: mDNS as Default Registry

internal/website/docs/architecture/adr-004-mdns-default-registry.md

5.19.13.0 KB
Original Source

ADR-004: mDNS as Default Registry

Status

Accepted

Context

Service discovery is critical for microservices. Common approaches:

  1. Central registry (Consul, Etcd) - Requires infrastructure
  2. DNS-based (Kubernetes DNS) - Platform-specific
  3. Static configuration - Doesn't scale
  4. Multicast DNS (mDNS) - Zero-config, local network

For local development and getting started, requiring infrastructure setup is a barrier. Production deployments typically have existing service discovery infrastructure.

Decision

Use mDNS as the default registry for service discovery.

  • Works immediately on local networks
  • No external dependencies
  • Suitable for development and simple deployments
  • Easily swapped for production registries (Consul, Etcd, Kubernetes)

Implementation

go
// Default - uses mDNS automatically
svc := micro.NewService(micro.Name("myservice"))

// Production - swap to Consul
reg := consul.NewConsulRegistry()
svc := micro.NewService(
    micro.Name("myservice"),
    micro.Registry(reg),
)

Consequences

Positive

  • Zero setup: go run main.go just works
  • Fast iteration: No infrastructure for local dev
  • Learning curve: Newcomers start immediately
  • Progressive complexity: Add infrastructure as needed

Negative

  • Local network only: mDNS doesn't cross subnets/VLANs
  • Not for production: Needs proper registry in production
  • Port 5353: May conflict with existing mDNS services
  • Discovery delay: Can take 1-2 seconds

Mitigations

  • Clear documentation on production alternatives
  • Environment variables for easy swapping (MICRO_REGISTRY=consul)
  • Examples for all major registries
  • Health checks and readiness probes for production

Use Cases

Good for mDNS

  • Local development
  • Testing
  • Simple internal services on same network
  • Learning and prototyping

Need Production Registry

  • Cross-datacenter communication
  • Cloud deployments
  • Large service mesh (100+ services)
  • Require advanced features (health checks, metadata filtering)

Alternatives Considered

No Default (Force Configuration)

Rejected because:

  • Poor first-run experience
  • Increases barrier to entry
  • Users must setup infrastructure before trying framework

Static Configuration

Rejected because:

  • Doesn't support dynamic service discovery
  • Manual configuration doesn't scale
  • Doesn't reflect real microservices usage

Consul as Default

Rejected because:

  • Requires running Consul for "Hello World"
  • Platform-specific
  • Adds complexity for beginners

Migration Path

Start with mDNS, migrate to production registry:

bash
# Development
go run main.go

# Staging
MICRO_REGISTRY=consul MICRO_REGISTRY_ADDRESS=consul:8500 go run main.go

# Production (Kubernetes)
MICRO_REGISTRY=nats MICRO_REGISTRY_ADDRESS=nats://nats:4222 ./service