Coordinator discovery of workers via service discovery
- Dominant language
- Python
- Stars
- 670
- Forks
- 183
- Avg merge
- 17h 7m
- Merged PRs (30d)
- 358
Description
## Story
As the app-proxy coordinator, I want to discover workers via service discovery so that I can manage workers dynamically without requiring direct registration.
## Background
Currently, the coordinator relies on workers actively registering themselves via API calls. This creates a dependency where workers must successfully connect to the coordinator to be recognized. By implementing service discovery, the coordinator can independently discover available workers, improving system flexibility and resilience.
## Related Epic
BA-2380: Implement Service Discovery for App-proxy Worker Registration
## Technical Details
### Changes in Coordinator
#### 1. Worker Discovery Service
Create a new service in the coordinator that:
- Periodically polls service discovery for registered workers
- Maintains a synchronized view of available workers
- Handles worker appearance and disappearance events
- Updates the database with discovered worker information
#### 2. Database Synchronization
- Sync discovered workers with the `workers` table
- Mark workers as ALIVE when found in service discovery
- Mark workers as LOST when missing from service discovery
- Preserve existing worker metadata and relationships
#### 3. API Changes in `coordinator/api/worker_v2.py`
- Modify worker registration endpoint to be optional
- Add endpoint to force service discovery refresh
- Update worker listing to include discovery source
- Maintain backward compatibility with direct registration
#### 4. Service Discovery Integration
- Use `ServiceDiscovery.get_service_group("appproxy-worker")`
- Parse worker ServiceMetadata to extract configuration
- Handle both Redis and Etcd backends
- Implement appropriate polling intervals
### Worker ServiceMetadata Structure
The coordinator expects workers to register with:
```python
ServiceMetadata(
id: UUID,
display_name: str, # worker authority
service_group: "appproxy-worker",
version: str,
endpoint: ServiceEndpoint(
address: str, # hostname
port: int, # api_port
protocol: str, # proxy protocol
prometheus_address: str
),
# Additional worker-specific data in metadata field
extra: {
"frontend_mode": str,
"tls_listen": bool,
"tls_advertised": bool,
"port_range": [int, int] | null,
"wildcard_domain": str | null,
"wildcard_traffic_port": int | null,
"accepted_traffics": list[str],
"filtered_apps_only": bool,
"app_filters": list[dict]
}
)
```
## Implementation Steps
1. Create WorkerDiscoveryService class
1. Implement periodic polling of service discovery
1. Create worker metadata parser and validator
1. Implement database synchronization logic
1. Add discovery status to worker model
1. Create management endpoints for discovery control
1. Add configuration for discovery intervals
1. Implement event handlers for worker state changes
## Acceptance Criteria
- [ ] Coordinator discovers all workers registered in service discovery
- [ ] Discovered workers are synchronized to database
- [ ] Worker status (ALIVE/LOST) reflects service discovery state
- [ ] Polling interval is configurable
- [ ] Both Redis and Etcd backends are supported
- [ ] Direct registration still works as fallback
- [ ] API provides visibility into discovery status
- [ ] Proper logging of discovery events
- [ ] Graceful handling of service discovery failures
## Migration Strategy
1. Phase 1: Add discovery alongside existing registration (both work)
1. Phase 2: Make direct registration optional via config
1. Phase 3: Deprecate direct registration in favor of discovery
## Dependencies
- Epic: BA-2380
- Depends on: BA-2381 (Worker self-registration)
- Requires: `ai.backend.common.service_discovery` module
## Testing
- Unit tests for metadata parsing and validation
- Integration tests with mock service discovery
- Test worker appearance/disappearance handling
- Test database synchronization logic
- Performance tests with many workers
- Failure scenario testing
JIRA Issue: BA-2382
Contributor guide
Assessment
This issue has not been assessed yet.