docs: Align documentation with true microservices architecture
Transform all documentation from modular monolith to true microservices
architecture where core services are independently deployable.
Key Changes:
- Core Kernel: Infrastructure only (no business logic)
- Core Services: Auth, Identity, Authz, Audit as separate microservices
- Each service has own entry point (cmd/{service}/)
- Each service has own gRPC server and database schema
- Services register with Consul for service discovery
- API Gateway: Moved from Epic 8 to Epic 1 as core infrastructure
- Single entry point for all external traffic
- Handles routing, JWT validation, rate limiting, CORS
- Service Discovery: Consul as primary mechanism (ADR-0033)
- Database Pattern: Per-service connections with schema isolation
Documentation Updates:
- Updated all 9 architecture documents
- Updated 4 ADRs and created 2 new ADRs (API Gateway, Service Discovery)
- Rewrote Epic 1: Core Kernel & Infrastructure (infrastructure only)
- Rewrote Epic 2: Core Services (Auth, Identity, Authz, Audit as services)
- Updated Epic 3-8 stories for service architecture
- Updated plan.md, playbook.md, requirements.md, index.md
- Updated all epic READMEs and story files
New ADRs:
- ADR-0032: API Gateway Strategy
- ADR-0033: Service Discovery Implementation (Consul)
New Stories:
- Epic 1.7: Service Client Interfaces
- Epic 1.8: API Gateway Implementation
This commit is contained in:
@@ -1,138 +1,38 @@
|
||||
# Story 3.5: Service Registry and Discovery
|
||||
# Story 3.5: Service Registry and Discovery (Verification)
|
||||
|
||||
## Metadata
|
||||
- **Story ID**: 3.5
|
||||
- **Title**: Service Registry and Discovery
|
||||
- **Epic**: 3 - Module Framework
|
||||
- **Title**: Service Registry and Discovery (Verification)
|
||||
- **Epic**: 3 - Module Framework (Feature Services)
|
||||
- **Status**: Pending
|
||||
- **Priority**: High
|
||||
- **Estimated Time**: 5-6 hours
|
||||
- **Estimated Time**: 2-3 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.
|
||||
Verify and document integration of Consul service registry (implemented in Epic 1) with feature services. Ensure all services can register and discover each other correctly.
|
||||
|
||||
## 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.
|
||||
This story verifies that the Consul service registry implemented in Epic 1 (Story 1.7) works correctly with feature services. It ensures service registration, discovery, and health checking work for both core services and feature services.
|
||||
|
||||
## 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
|
||||
### 1. Service Registry Verification
|
||||
- Verify Consul registry implementation from Epic 1 works correctly
|
||||
- Test service registration for feature services
|
||||
- Test service discovery for feature services
|
||||
- Verify health checking integration
|
||||
|
||||
### 2. Service Info Structure
|
||||
- `ServiceInfo` struct with:
|
||||
- ID, Name, Version
|
||||
- Address (host:port)
|
||||
- Protocol (local, grpc, http)
|
||||
- Health status
|
||||
- Metadata
|
||||
### 2. Integration Documentation
|
||||
- Document how feature services register with Consul
|
||||
- Document service discovery patterns for feature services
|
||||
- Update examples to show feature service registration
|
||||
|
||||
### 3. Consul Registry (`internal/services/registry/consul.go`)
|
||||
- Consul integration (primary for production)
|
||||
- Service registration and discovery
|
||||
- Health checking
|
||||
- Automatic service registration
|
||||
### 3. Integration Tests
|
||||
- Test feature service registration
|
||||
- Test feature service discovery
|
||||
- Test health checking for feature services
|
||||
- Test service client integration with Consul
|
||||
|
||||
### 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`:
|
||||
```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/0029-microservices-architecture.md)
|
||||
- [ADR-0030: Service Communication Strategy](../../adr/0030-service-communication-strategy.md)
|
||||
|
||||
## Implementation Notes
|
||||
- Consul is the primary registry for production
|
||||
- Kubernetes service discovery for K8s deployments
|
||||
- Health checks should be lightweight
|
||||
- Support service versioning
|
||||
|
||||
## Testing
|
||||
```bash
|
||||
# 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
|
||||
**Note:** Service registry implementation is in Epic 1 (Story 1.7). This story verifies integration with feature services.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user