go-micro.dev/v5@v5.12.0/internal/website/docs/architecture/adr-004-mdns-default-registry.md (about)

     1  ---
     2  layout: default
     3  ---
     4  
     5  # ADR-004: mDNS as Default Registry
     6  
     7  ## Status
     8  **Accepted**
     9  
    10  ## Context
    11  
    12  Service discovery is critical for microservices. Common approaches:
    13  
    14  1. **Central registry** (Consul, Etcd) - Requires infrastructure
    15  2. **DNS-based** (Kubernetes DNS) - Platform-specific
    16  3. **Static configuration** - Doesn't scale
    17  4. **Multicast DNS (mDNS)** - Zero-config, local network
    18  
    19  For local development and getting started, requiring infrastructure setup is a barrier. Production deployments typically have existing service discovery infrastructure.
    20  
    21  ## Decision
    22  
    23  Use **mDNS as the default registry** for service discovery.
    24  
    25  - Works immediately on local networks
    26  - No external dependencies
    27  - Suitable for development and simple deployments
    28  - Easily swapped for production registries (Consul, Etcd, Kubernetes)
    29  
    30  ## Implementation
    31  
    32  ```go
    33  // Default - uses mDNS automatically
    34  svc := micro.NewService(micro.Name("myservice"))
    35  
    36  // Production - swap to Consul
    37  reg := consul.NewConsulRegistry()
    38  svc := micro.NewService(
    39      micro.Name("myservice"),
    40      micro.Registry(reg),
    41  )
    42  ```
    43  
    44  ## Consequences
    45  
    46  ### Positive
    47  
    48  - **Zero setup**: `go run main.go` just works
    49  - **Fast iteration**: No infrastructure for local dev
    50  - **Learning curve**: Newcomers start immediately
    51  - **Progressive complexity**: Add infrastructure as needed
    52  
    53  ### Negative
    54  
    55  - **Local network only**: mDNS doesn't cross subnets/VLANs
    56  - **Not for production**: Needs proper registry in production
    57  - **Port 5353**: May conflict with existing mDNS services
    58  - **Discovery delay**: Can take 1-2 seconds
    59  
    60  ### Mitigations
    61  
    62  - Clear documentation on production alternatives
    63  - Environment variables for easy swapping (`MICRO_REGISTRY=consul`)
    64  - Examples for all major registries
    65  - Health checks and readiness probes for production
    66  
    67  ## Use Cases
    68  
    69  ### Good for mDNS
    70  - Local development
    71  - Testing
    72  - Simple internal services on same network
    73  - Learning and prototyping
    74  
    75  ### Need Production Registry
    76  - Cross-datacenter communication
    77  - Cloud deployments
    78  - Large service mesh (100+ services)
    79  - Require advanced features (health checks, metadata filtering)
    80  
    81  ## Alternatives Considered
    82  
    83  ### No Default (Force Configuration)
    84  Rejected because:
    85  - Poor first-run experience
    86  - Increases barrier to entry
    87  - Users must setup infrastructure before trying framework
    88  
    89  ### Static Configuration
    90  Rejected because:
    91  - Doesn't support dynamic service discovery
    92  - Manual configuration doesn't scale
    93  - Doesn't reflect real microservices usage
    94  
    95  ### Consul as Default
    96  Rejected because:
    97  - Requires running Consul for "Hello World"
    98  - Platform-specific
    99  - Adds complexity for beginners
   100  
   101  ## Migration Path
   102  
   103  Start with mDNS, migrate to production registry:
   104  
   105  ```bash
   106  # Development
   107  go run main.go
   108  
   109  # Staging
   110  MICRO_REGISTRY=consul MICRO_REGISTRY_ADDRESS=consul:8500 go run main.go
   111  
   112  # Production (Kubernetes)
   113  MICRO_REGISTRY=nats MICRO_REGISTRY_ADDRESS=nats://nats:4222 ./service
   114  ```
   115  
   116  ## Related
   117  
   118  - [ADR-001: Plugin Architecture](adr-001-plugin-architecture.md)
   119  - [ADR-009: Progressive Configuration](adr-009-progressive-configuration.md)
   120  - [Registry Documentation](../registry.md)