Skip to content

# 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

Платформа працює за правилом:

    НІЯКІ ВНУТРІШНІ СЕРВІСИ НЕ ДОВІРЯЮТЬ ОДИН ОДНОМУ.

Тому кожен запит:

- автентифікується,
- авторизується через 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)

Кожен сервіс отримує власну сертифікацію:

    CN = service_name
    SAN = service_name.namespace.svc

mTLS забезпечує:

- автентифікацію сервісу,
- заборону spoofing,
- шифрування трафіку.

## 5. Service Registry

Mesh потребує централізованого каталогу сервісів:

    {
      "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

    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 для сервісних.

Приклад:

    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)

    # service: wallet
    allow:
      - usage
      - chain_rpc
    deny:
      - messaging
      - router
      - embassy

    timeouts:
      request: 1s

    retries:
      enabled: false

    mTLS: required

    # 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

    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