goplt/docs/content/stories/epic3/3.5-service-registry.md

Story 3.5: Service Registry and Discovery

Metadata

• Story ID: 3.5
• Title: Service Registry and Discovery
• Epic: 3 - Module Framework
• Status: Pending
• Priority: High
• Estimated Time: 5-6 hours
• Dependencies: 1.7, 3.1

Goal

Implement a service registry that enables service discovery for microservices, allowing services to locate and communicate with each other.

Description

This story creates a service registry system supporting Consul and Kubernetes service discovery. The registry enables service discovery, health checking, and automatic service registration.

Deliverables

1. Service Registry Interface (pkg/services/registry.go)

• ServiceRegistry interface with:
  • Register(service ServiceInfo) error - Register a service
  • Deregister(serviceID string) error - Deregister a service
  • Discover(serviceName string) ([]ServiceInfo, error) - Discover services
  • GetService(serviceName string) (ServiceInfo, error) - Get specific service
  • ListServices() ([]ServiceInfo, error) - List all services
  • HealthCheck(serviceID string) error - Check service health

2. Service Info Structure

• ServiceInfo struct with:
  • ID, Name, Version
  • Address (host:port)
  • Protocol (local, grpc, http)
  • Health status
  • Metadata

3. Consul Registry (internal/services/registry/consul.go)

• Consul integration (primary for production)
• Service registration and discovery
• Health checking
• Automatic service registration

4. Kubernetes Service Discovery (internal/services/registry/kubernetes.go)

• Kubernetes service discovery
• Service health checking
• Automatic service registration via K8s services

5. Service Registration

• Auto-register services on startup
• Health check endpoints
• Graceful deregistration on shutdown

6. Configuration

• Registry configuration in config/default.yaml:

  service_registry:
    type: consul  # consul, kubernetes, etcd
    consul:
      address: localhost:8500
    kubernetes:
      namespace: default
    etcd:
      endpoints:
        - localhost:2379
  

7. Integration

• Integrate with service factory
• Auto-register core services
• Support module service registration

Implementation Steps

1. Create Service Registry Interface

   • Create pkg/services/registry.go
   • Define ServiceRegistry interface
   • Define ServiceInfo struct

2. Implement Consul Registry

   • Create internal/services/registry/consul.go
   • Implement Consul integration
   • Add health checking

3. Implement Kubernetes Registry

   • Create internal/services/registry/kubernetes.go
   • Implement K8s service discovery
   • Add health checking

4. Add Service Registration

   • Auto-register services on startup
   • Add health check endpoints
   • Handle graceful shutdown

5. Add Configuration

   • Add registry configuration
   • Support multiple registry types

6. Integrate with Service Factory

   • Use registry for service discovery
   • Resolve services via registry

Acceptance Criteria

• Service registry interface is defined
• Consul registry works correctly
• Kubernetes registry works correctly
• Services are auto-registered on startup
• Service discovery works
• Health checking works
• Registry is configurable
• Graceful deregistration works

Related ADRs

• ADR-0029: Microservices Architecture
• ADR-0030: Service Communication Strategy

Implementation Notes

• Consul is the primary registry for production
• Kubernetes service discovery for K8s deployments
• Health checks should be lightweight
• Support service versioning

Testing

# Test service registry
go test ./internal/services/registry/...

# Test service discovery
go test ./internal/services/registry/... -run TestDiscovery

Files to Create/Modify

• pkg/services/registry.go - Service registry interface
• internal/services/registry/consul.go - Consul registry
• internal/services/registry/kubernetes.go - Kubernetes registry
• internal/services/factory.go - Integrate with registry
• internal/di/providers.go - Add registry provider
• config/default.yaml - Add registry configuration