chore: organize documentation structure for monorepo
- Create /docs structure (microdao, daarion, agents) - Organize 61 cursor technical docs - Add README files for each category - Copy key documents to public categories - Add GitHub setup instructions and scripts
This commit is contained in:
Apple
517
docs/cursor/35_microdao_service_mesh_design.md
Normal file
517
docs/cursor/35_microdao_service_mesh_design.md
Normal file
@@ -0,0 +1,517 @@
|
||||
# 35 — MicroDAO Service Mesh Design (MicroDAO)
|
||||
|
||||
*Арова архітектура сервіс-меш, резолюція сервісів, мережеві політики, zero-trust, observability, retries, autoscaling та інженерні стандарти для DAARION.city / microDAO*
|
||||
|
||||
---
|
||||
|
||||
## 1. Purpose & Scope
|
||||
|
||||
MicroDAO Service Mesh — це внутрішня мережна платформа, що забезпечує:
|
||||
|
||||
- безпечний виклик сервісів через **zero-trust** модель;
|
||||
- внутрішнє балансування навантаження;
|
||||
- автоматичне перез'єднання;
|
||||
- контроль трафіку;
|
||||
- observability (metrics / traces / logs);
|
||||
- резолюцію сервісів та політики доступу;
|
||||
- fault tolerance (retries, circuit breakers, rate limits).
|
||||
|
||||
Цей документ — обов'язковий для:
|
||||
|
||||
- backend-інженерів,
|
||||
- DevOps/SRE,
|
||||
- авторів внутрішніх сервісів,
|
||||
- security-аудиторів.
|
||||
|
||||
---
|
||||
|
||||
## 2. High-Level Mesh Architecture
|
||||
|
||||
```
|
||||
┌────────────────────────────────┐
|
||||
│ API Gateway (PEP) │
|
||||
└────────────────┬───────────────┘
|
||||
│
|
||||
┌──────────────────┴─────────────────┐
|
||||
│ SERVICE MESH FABRIC │
|
||||
└─────────────┬─────────────┬────────┘
|
||||
│ │
|
||||
┌─────────────────┘ └──────────────────┐
|
||||
Internal Services System Services
|
||||
```
|
||||
|
||||
Основу складають:
|
||||
|
||||
- Service Registry
|
||||
- Sidecar Proxy (Envoy / Linkerd / Traefik Mesh)
|
||||
- mTLS між сервісами
|
||||
- Observability pipeline
|
||||
- Traffic control (retries, timeouts, circuit breakers)
|
||||
|
||||
---
|
||||
|
||||
## 3. Zero-Trust Model
|
||||
|
||||
Платформа працює за правилом:
|
||||
|
||||
```text
|
||||
НІЯКІ ВНУТРІШНІ СЕРВІСИ НЕ ДОВІРЯЮТЬ ОДИН ОДНОМУ.
|
||||
```
|
||||
|
||||
Тому кожен запит:
|
||||
|
||||
- автентифікується,
|
||||
- авторизується через PDP,
|
||||
- шифрується,
|
||||
- логуються метадані.
|
||||
|
||||
### 3.1 Trust Boundaries
|
||||
|
||||
| Boundary | Policy |
|
||||
| ------------------ | ----------------------- |
|
||||
| Gateway → Services | PDP enforced |
|
||||
| Service → Service | mTLS + service identity |
|
||||
| Service → DB | minimal DB roles |
|
||||
| Service → NATS | per-stream permissions |
|
||||
|
||||
---
|
||||
|
||||
## 4. Service Identity (mTLS)
|
||||
|
||||
Кожен сервіс отримує власну сертифікацію:
|
||||
|
||||
```text
|
||||
CN = service_name
|
||||
SAN = service_name.namespace.svc
|
||||
```
|
||||
|
||||
mTLS забезпечує:
|
||||
|
||||
- автентифікацію сервісу,
|
||||
- заборону spoofing,
|
||||
- шифрування трафіку.
|
||||
|
||||
---
|
||||
|
||||
## 5. Service Registry
|
||||
|
||||
Mesh потребує **централізованого каталогу сервісів**:
|
||||
|
||||
```json
|
||||
{
|
||||
"service": "wallet",
|
||||
"host": "wallet.svc.cluster.local",
|
||||
"port": 8081,
|
||||
"metadata": {
|
||||
"team": "core",
|
||||
"version": "v1.4.0",
|
||||
"zone": "eu-central-1"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
У cloud-середовищі це зазвичай:
|
||||
|
||||
- Kubernetes DNS,
|
||||
- або Consul,
|
||||
- або власний registry.
|
||||
|
||||
---
|
||||
|
||||
## 6. Internal Service-to-Service Traffic
|
||||
|
||||
### 6.1 Pattern
|
||||
|
||||
```text
|
||||
serviceA → Envoy Sidecar → Mesh → Envoy Sidecar → serviceB
|
||||
```
|
||||
|
||||
### 6.2 Benefits
|
||||
|
||||
- automatic retries,
|
||||
- circuit breaking,
|
||||
- mTLS,
|
||||
- observability,
|
||||
- fine-grained routing,
|
||||
- traffic shadowing.
|
||||
|
||||
---
|
||||
|
||||
## 7. Core Service Mesh Features
|
||||
|
||||
### 7.1 mTLS Encryption
|
||||
|
||||
- Усі внутрішні запити шифровані.
|
||||
- Certificates rotate every 12–48 hours.
|
||||
|
||||
### 7.2 Load Balancing (Layer 7)
|
||||
|
||||
- round-robin,
|
||||
- least_conn,
|
||||
- locality-aware routing.
|
||||
|
||||
### 7.3 Retries
|
||||
|
||||
- max 3,
|
||||
- exponential backoff,
|
||||
- jitter.
|
||||
|
||||
### 7.4 Circuit Breakers
|
||||
|
||||
При перевантаженні:
|
||||
|
||||
- mesh відкриває circuit → запити йдуть у failfast,
|
||||
- після cooling-off — пробує відновити.
|
||||
|
||||
### 7.5 Timeouts
|
||||
|
||||
- default timeout: 3 seconds,
|
||||
- wallet, embassy: 1 second (short to avoid blocking),
|
||||
- agent runs: 10–60 seconds (handled separately).
|
||||
|
||||
---
|
||||
|
||||
## 8. Internal API Standard (Mesh Requirements)
|
||||
|
||||
Кожен сервіс має відповідати стандарту:
|
||||
|
||||
- JSON over HTTP (no gRPC unless planned),
|
||||
- `/internal/v1/<service>/<operation>`,
|
||||
- атомарні операції,
|
||||
- 4xx для клієнтських помилок,
|
||||
- 5xx для сервісних.
|
||||
|
||||
Приклад:
|
||||
|
||||
```text
|
||||
POST /internal/v1/wallet/payout/claim
|
||||
POST /internal/v1/embassy/energy/update
|
||||
POST /internal/v1/agent/run
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. PDP Integration (per-service)
|
||||
|
||||
PEP живе тільки у API Gateway, але Services повинні:
|
||||
|
||||
1. не довіряти payload, навіть після PDP → додаткова валідація;
|
||||
2. виконувати DB-level ACL checks;
|
||||
3. мутуючі операції мають виконуватись тільки через Gateway.
|
||||
|
||||
**Жоден сервіс не приймає зовнішній трафік напряму.**
|
||||
|
||||
---
|
||||
|
||||
## 10. Mesh-Level Policies
|
||||
|
||||
### 10.1 Allow-lists
|
||||
|
||||
Кожен сервіс може викликати тільки перелік інших сервісів:
|
||||
|
||||
| Service | Allowed to Call |
|
||||
| ------------------ | ----------------------------- |
|
||||
| Messaging | Usage, Storage |
|
||||
| Agent Orchestrator | LLM Proxy, Usage |
|
||||
| Embassy | RWA, Usage |
|
||||
| Wallet | Chain RPC, Usage |
|
||||
| Router | Agent Orchestrator, LLM Proxy |
|
||||
| RWA | Wallet, Usage |
|
||||
|
||||
### 10.2 Deny-lists
|
||||
|
||||
Забезпечує Zero-Trust:
|
||||
|
||||
- Messaging → No direct Wallet access
|
||||
- Agents → No direct RWA access
|
||||
- Embassy → No direct Wallet claim
|
||||
- Router → No low-level DB access
|
||||
|
||||
---
|
||||
|
||||
## 11. Observability Model
|
||||
|
||||
Mesh забезпечує повну видимість.
|
||||
|
||||
### 11.1 Metrics
|
||||
|
||||
- latency (p50, p95, p99),
|
||||
- HTTP codes,
|
||||
- retry count,
|
||||
- circuit breaker events,
|
||||
- request sizes,
|
||||
- traffic spikes.
|
||||
|
||||
### 11.2 Tracing
|
||||
|
||||
Підтримується:
|
||||
|
||||
- OpenTelemetry,
|
||||
- distributed tracing (trace_id, span_id),
|
||||
- propagation через Gateway → Mesh → Services → DB → NATS.
|
||||
|
||||
### 11.3 Logs
|
||||
|
||||
Збираються:
|
||||
|
||||
- access logs,
|
||||
- error logs,
|
||||
- mesh-level logs.
|
||||
|
||||
---
|
||||
|
||||
## 12. Failover & Resilience
|
||||
|
||||
### 12.1 Multi-zone (Cloud)
|
||||
|
||||
Mesh обирає найближчий healthy інстанс.
|
||||
|
||||
### 12.2 Zonal Failover
|
||||
|
||||
При провалі зони:
|
||||
|
||||
- трафік автоматично перенаправляється в інші зони.
|
||||
|
||||
### 12.3 Service Healthchecks
|
||||
|
||||
- `livenessProbe`: чи не висить процес.
|
||||
- `readinessProbe`: чи сервіс готовий приймати трафік.
|
||||
|
||||
---
|
||||
|
||||
## 13. Mesh Traffic Rules for Critical Services
|
||||
|
||||
### 13.1 Wallet Service
|
||||
|
||||
- low timeout (1 sec)
|
||||
- retries: 0 (щоб не дублювати транзакції)
|
||||
- circuit-breaker sensitivity: high
|
||||
|
||||
### 13.2 Embassy
|
||||
|
||||
- retries: 1
|
||||
- timeout: 0.5 sec
|
||||
- global rate limiting:
|
||||
- embassy bursts можуть спричинити навантаження
|
||||
|
||||
### 13.3 Agent Orchestrator
|
||||
|
||||
- long timeout (10–60 sec)
|
||||
- retries: none (idempotency?)
|
||||
- dedicated queue routing
|
||||
|
||||
### 13.4 Router/DAARWIZZ
|
||||
|
||||
- timeout: 5–15 sec
|
||||
- retries: 1–2
|
||||
- concurrency caps
|
||||
|
||||
---
|
||||
|
||||
## 14. Service Mesh Security
|
||||
|
||||
### 14.1 mTLS Everywhere
|
||||
|
||||
- між усіма сервісами обов'язково.
|
||||
|
||||
### 14.2 Internal Service Keys
|
||||
|
||||
Кожен сервіс має:
|
||||
|
||||
- `service_key`,
|
||||
- capability:
|
||||
|
||||
```text
|
||||
service.write.oracles
|
||||
service.mint.payout
|
||||
service.agent.run
|
||||
service.read.usage
|
||||
```
|
||||
|
||||
- PDP авторизація на рівні сервісів.
|
||||
|
||||
### 14.3 No direct DB access (where possible)
|
||||
|
||||
Сервіси мають мінімальні ролі DB.
|
||||
|
||||
### 14.4 Network Policies
|
||||
|
||||
Забороняють:
|
||||
|
||||
- доступ між сервісами, що не пов'язані функціонально,
|
||||
- будь-які вихідні запити (egress) без дозволу.
|
||||
|
||||
---
|
||||
|
||||
## 15. Deployment Model
|
||||
|
||||
### 15.1 Sidecar Mode
|
||||
|
||||
Рекомендовано:
|
||||
|
||||
- Envoy sidecar у кожному pod,
|
||||
- mesh контролер керує routing tables.
|
||||
|
||||
### 15.2 Node-agent Mode (Alternative)
|
||||
|
||||
- не потрібні sidecars,
|
||||
- менше накладних витрат,
|
||||
- простіше управління.
|
||||
|
||||
### 15.3 Observability stack
|
||||
|
||||
- Prometheus,
|
||||
- Grafana,
|
||||
- Loki (або Cloud Logging),
|
||||
- Jaeger / Tempo.
|
||||
|
||||
---
|
||||
|
||||
## 16. Service Mesh Integration with Scaling
|
||||
|
||||
### 16.1 Auto-discovery
|
||||
|
||||
Нові інстанси автоматично реєструються.
|
||||
|
||||
### 16.2 Load-aware routing
|
||||
|
||||
Mesh відправляє запити на:
|
||||
|
||||
- найменш завантажені інстанси,
|
||||
- локальні (в межах зони).
|
||||
|
||||
### 16.3 Autoscaling Signals
|
||||
|
||||
Mesh збирає:
|
||||
|
||||
- CPU,
|
||||
- memory,
|
||||
- request rate,
|
||||
- errors,
|
||||
- queue depth (for agents).
|
||||
|
||||
---
|
||||
|
||||
## 17. Message Patterns
|
||||
|
||||
### 17.1 Request-Response
|
||||
|
||||
Звичайні виклики:
|
||||
|
||||
- Messaging
|
||||
- Projects
|
||||
- Wallet reads
|
||||
|
||||
### 17.2 Asynchronous Events
|
||||
|
||||
Через NATS:
|
||||
|
||||
- payouts,
|
||||
- RWA updates,
|
||||
- agent events
|
||||
|
||||
### 17.3 Long-running tasks
|
||||
|
||||
Через Agent Orchestrator:
|
||||
|
||||
- LLM chain-of-thought,
|
||||
- multi-step flows.
|
||||
|
||||
---
|
||||
|
||||
## 18. Example Mesh Policy Config (Illustrative)
|
||||
|
||||
```yaml
|
||||
# service: wallet
|
||||
allow:
|
||||
- usage
|
||||
- chain_rpc
|
||||
deny:
|
||||
- messaging
|
||||
- router
|
||||
- embassy
|
||||
|
||||
timeouts:
|
||||
request: 1s
|
||||
|
||||
retries:
|
||||
enabled: false
|
||||
|
||||
mTLS: required
|
||||
```
|
||||
|
||||
```yaml
|
||||
# service: embassy
|
||||
allow:
|
||||
- rwa
|
||||
- usage
|
||||
deny:
|
||||
- wallet
|
||||
- agent
|
||||
- router
|
||||
|
||||
mTLS: required
|
||||
rate_limit: 500/min
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 19. Integration with Other Docs
|
||||
|
||||
Цей документ доповнює:
|
||||
|
||||
- `34_internal_services_architecture.md`
|
||||
- `33_api_gateway_security_and_pep.md`
|
||||
- `32_policy_service_PDP_design.md`
|
||||
- `29_scaling_and_high_availability.md`
|
||||
- `26_security_audit.md`
|
||||
|
||||
---
|
||||
|
||||
## 20. Завдання для Cursor
|
||||
|
||||
```text
|
||||
You are a senior DevOps/SRE engineer. Implement Service Mesh using:
|
||||
- 35_microdao_service_mesh_design.md
|
||||
- 34_internal_services_architecture.md
|
||||
- 29_scaling_and_high_availability.md
|
||||
|
||||
Tasks:
|
||||
1) Set up Service Registry (Kubernetes DNS or Consul).
|
||||
2) Configure mTLS for all services.
|
||||
3) Implement Envoy sidecar proxies (or node-agent mode).
|
||||
4) Set up mesh-level policies (allow-lists, deny-lists).
|
||||
5) Configure retries, timeouts, circuit breakers.
|
||||
6) Integrate with observability stack (Prometheus, Grafana, Loki, Jaeger).
|
||||
7) Set up health checks for all services.
|
||||
8) Configure load balancing and failover.
|
||||
9) Implement network policies for zero-trust.
|
||||
|
||||
Output:
|
||||
- list of modified files
|
||||
- diff
|
||||
- summary
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 21. Summary
|
||||
|
||||
MicroDAO Service Mesh забезпечує:
|
||||
|
||||
- захищені зв'язки між сервісами,
|
||||
- шифрування всього внутрішнього трафіку,
|
||||
- централізоване управління політиками,
|
||||
- fault tolerance,
|
||||
- трасування,
|
||||
- динамічну маршрутизацію,
|
||||
- стійкість до збоїв.
|
||||
|
||||
Це «нервова система» DAARION.city, яка дозволяє системі масштабуватися й залишатися безпечною при зростанні навантаження та сервісів.
|
||||
|
||||
---
|
||||
|
||||
**Версія:** 1.0
|
||||
**Останнє оновлення:** 2024-11-14
|
||||
|
||||
|
||||
Reference in New Issue
Block a user