Topologia di Rete

La topologia di rete di Emblema è progettata per garantire sicurezza, scalabilità e performance attraverso una architettura containerizzata con reverse proxy centralizzato e reti Docker segmentate.

Architettura di Rete

Loading diagram...

Configurazione di Rete Docker

Network Definitions

Emblema utilizza due reti Docker principali:

networks:
  emblema:
    external: true # Rete principale per comunicazione inter-service
    driver: bridge

  redis-net:
    driver: bridge # Rete dedicata per cluster Redis
    internal: true # Isolata da traffico esterno

Service Network Assignment

services:
  # Servizi sulla rete principale
  www-emblema:
    networks:
      - emblema

  # Servizi con accesso a multiple reti
  redis-master:
    networks:
      - emblema # Per accesso da altri servizi
      - redis-net # Per comunicazione cluster Redis

  # Servizi isolati
  redis-replica1:
    networks:
      - redis-net # Solo cluster interno

Traefik Reverse Proxy

Entry Points Configuration

# config/traefik/traefik.yml
entryPoints:
  web:
    address: ":80"
    http:
      redirections:
        entryPoint:
          to: websecure
          scheme: https

  websecure:
    address: ":443"

  redis:
    address: ":6379" # Entry point per Redis (se necessario)

Routing Rules

Host-based Routing

# Esempio per www-emblema
labels:
  - "traefik.enable=true"
  - "traefik.http.routers.emblema-web.rule=Host(`${EMBLEMA_WEB_HOSTNAME}`)"
  - "traefik.http.routers.emblema-web.entrypoints=websecure"
  - "traefik.http.routers.emblema-web.tls=true"
  - "traefik.http.services.emblema-web.loadbalancer.server.port=3000"

Path-based Routing (se necessario)

# Esempio per API endpoints
labels:
  - "traefik.http.routers.api.rule=Host(`${API_HOSTNAME}`) && PathPrefix(`/api`)"
  - "traefik.http.routers.api.entrypoints=websecure"

Service Discovery

Traefik utilizza il Docker provider per service discovery automatico:

providers:
  docker:
    endpoint: "unix:///var/run/docker.sock"
    exposedByDefault: false # Solo servizi con label traefik.enable=true
  file:
    directory: "/etc/traefik/dynamic"
    watch: true # Hot reload delle configurazioni

Port Mapping Strategy

Principi di Esposizione

Single Entry Point: Solo Traefik espone porte pubbliche
Internal Communication: Servizi comunicano tramite nomi DNS interni
Development Override: Porte dirette commentate in produzione

# Pattern standard per tutti i servizi
service-name:
  # ports:                    # Commentate in produzione
  #   - "8080:8080"           # Solo per development/debug
  labels:
    - "traefik.http.services.service-name.loadbalancer.server.port=8080"

Port Allocation Matrix

Servizio	Porta Interna	Porta Host (Dev)	Accesso Pubblico
Traefik	80/443/8080	80/443/8080	✅
www-emblema	3000	-	Via Traefik
Hasura	8080	-	Via Traefik
Keycloak	8080	-	Via Traefik
MinIO API	9000	-	Via Traefik
MinIO Console	9090	-	Via Traefik
LiteLLM	4000	-	Via Traefik
Redis Master	6379	6379	Solo interno
PostgreSQL	5432	-	Solo interno
Milvus	19530/9091	19530/9091	Solo interno
MongoDB	27017	-	Solo interno

DNS Configuration

Internal Service Discovery

I servizi utilizzano nomi DNS Docker interni per la comunicazione:

environment:
  # URL interni per comunicazione service-to-service
  HASURA_API_URL: http://graphql-engine:8080/v1/graphql
  MILVUS_API_URL: http://milvus:19530/v2/vectordb
  LITELLM_API_URL: http://litellm:4000/v1
  BACKGROUND_TASK_API_URL: http://background-task
  MINIO_ENDPOINT: http://minio:9000
  REDIS_URL: redis://redis-master:6379

External DNS Requirements

Per il deployment in produzione sono necessari i seguenti record DNS:

# Frontend Services
www.emblema.ai          -> Server IP
doc.emblema.ai          -> Server IP
ui.emblema.ai           -> Server IP

# API Services
hasura.emblema.ai       -> Server IP
litellm.emblema.ai      -> Server IP
task.emblema.ai         -> Server IP

# Storage Services
minio.emblema.ai        -> Server IP
minio-admin.emblema.ai  -> Server IP

# Auth Services
keycloak.emblema.ai     -> Server IP

# Infrastructure
traefik.emblema.ai      -> Server IP
grafana.emblema.ai      -> Server IP

# Notifications
novu-api.emblema.ai     -> Server IP
novu-ws.emblema.ai      -> Server IP
novu-dashboard.emblema.ai -> Server IP

Load Balancing & High Availability

Traefik Load Balancing

# Configurazione load balancing per servizi multipli
labels:
  - "traefik.http.services.service-name.loadbalancer.server.port=8080"
  - "traefik.http.services.service-name.loadbalancer.healthcheck.path=/health"
  - "traefik.http.services.service-name.loadbalancer.healthcheck.interval=30s"
  - "traefik.http.services.service-name.loadbalancer.sticky.cookie=true"

Redis High Availability

# Architettura Master-Replica con Sentinel (configurazione futura)
redis-master:
  command: redis-server --requirepass ${REDIS_MASTER_PASSWORD} --appendonly yes

redis-replica1:
  command: redis-server --replicaof redis-master 6379 --appendonly yes

redis-sentinel1:
  command: redis-sentinel /usr/local/etc/redis/sentinel.conf

Database Redundancy

# PostgreSQL con backup automatico
postgres-vector:
  volumes:
    - emblema-hasura-data:/var/lib/postgresql/data
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
    interval: 30s
    timeout: 10s
    retries: 3

Firewall Rules & Security Groups

Container Network Isolation

# Esempio di isolamento rete per servizi sensibili
redis-net:
  driver: bridge
  internal: true # Non routing verso esterno
  ipam:
    config:
      - subnet: 172.20.0.0/16

Port Security Matrix

Porta	Servizio	Accesso	Protocollo	Sicurezza
80	HTTP Redirect	Pubblico	HTTP	Redirect a HTTPS
443	HTTPS Services	Pubblico	HTTPS	TLS Terminazione
8080	Traefik Dashboard	Admin	HTTP	Basic Auth
6379	Redis	Interno	TCP	Password
5432	PostgreSQL	Interno	TCP	User/Pass
19530	Milvus	Interno	gRPC	Token Auth
9000	MinIO	Interno	HTTP	Access/Secret Key

Middleware Security

# config/traefik/dynamic/cors.yml
http:
  middlewares:
    cors:
      headers:
        accessControlAllowOriginList:
          - "https://${EMBLEMA_WEB_HOSTNAME}"
          - "https://${DOCS_HOSTNAME}"
        accessControlAllowCredentials: true
        accessControlMaxAge: 86400

    security:
      headers:
        frameDeny: true
        contentTypeNosniff: true
        browserXssFilter: true
        forceSTSHeader: true
        stsSeconds: 31536000

SSL/TLS Configuration

Certificate Management

Emblema supporta due modalità di gestione certificati:

1. Custom Certificates (Air-Gap Friendly)

# .env
CERT_RESOLVER=

# docker-compose labels
labels:
  - "traefik.http.routers.service.tls.certresolver="  # Vuoto = certificati custom

Configuration dinamica:

# config/traefik/dynamic/tls.yml
tls:
  stores:
    default:
      defaultCertificate:
        certFile: "/certs/emblema_ai.crt"
        keyFile: "/certs/emblema_ai.key"

2. Let's Encrypt (Internet Required)

# .env
CERT_RESOLVER=letsencrypt

# docker-compose labels
labels:
  - "traefik.http.routers.service.tls.certresolver=letsencrypt"

TLS Security Headers

# Configurazione sicurezza TLS
labels:
  - "traefik.http.routers.service.tls.options=default@file"

# In config/traefik/dynamic/tls.yml
tls:
  options:
    default:
      minVersion: "VersionTLS12"
      cipherSuites:
        - "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"
        - "TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305"

Performance Optimization

Connection Pooling

# Configurazione connection pooling per database
environment:
  # PostgreSQL
  HASURA_GRAPHQL_DATABASE_URL: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres-vector:5432/postgres?pool_timeout=10&pool_size=20

  # Redis
  REDIS_CACHE_URL: redis://redis-master:6379/2?socket_keepalive=true&socket_keepalive_options=1,3,1

Caching Strategy

# Redis caching layers
services:
  redis-master:
    command: redis-server --requirepass ${REDIS_MASTER_PASSWORD} --maxmemory 2gb --maxmemory-policy allkeys-lru

  # Nginx caching per static assets (se necessario)
  nginx-cache:
    image: nginx:alpine
    volumes:
      - ./config/nginx/cache.conf:/etc/nginx/nginx.conf

Network Performance

# Ottimizzazioni rete per servizi AI
vllm-services:
  ipc: host # Shared memory per performance
  shm_size: 2gb # Memoria condivisa per tensor operations
  networks:
    - emblema
  sysctls:
    - net.core.rmem_max=134217728
    - net.core.wmem_max=134217728

Monitoring & Observability

Network Monitoring

# Traefik metrics per Prometheus
traefik:
  command:
    - --metrics.prometheus=true
    - --metrics.prometheus.buckets=0.1,0.3,1.2,5.0
    - --accesslog=true
    - --log.level=INFO

Service Health Checks

# Pattern health check per tutti i servizi
healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 60s

Traffic Analysis

# Log strutturati per analisi traffico
x-logging: &default-logging
  driver: "json-file"
  options:
    max-size: "1g"
    max-file: "3"
    labels: "service,version,environment"

Troubleshooting Network Issues

Common Network Problems

Service Discovery Issues

# Verifica risoluzione DNS interna
docker compose exec www-emblema nslookup graphql-engine

# Test connettività tra servizi
docker compose exec www-emblema curl -I http://graphql-engine:8080/healthz

Port Conflicts

# Verifica porte in uso
docker compose ps
netstat -tlnp | grep :80

# Verifica configurazione Traefik
curl -s http://localhost:8080/api/http/services | jq

SSL/TLS Issues

# Verifica certificati
docker compose logs traefik | grep -i tls

# Test connessione HTTPS
curl -I https://${EMBLEMA_WEB_HOSTNAME}
openssl s_client -connect ${EMBLEMA_WEB_HOSTNAME}:443 -servername ${EMBLEMA_WEB_HOSTNAME}

Debug Commands

# Analisi rete Docker
docker network ls
docker network inspect emblema

# Verifica routing Traefik
curl -s http://localhost:8080/api/http/routers | jq

# Monitor traffico in tempo reale
docker compose logs -f traefik | grep -E "(request|error)"

# Test connettività interna
docker compose exec www-emblema sh -c "nc -zv graphql-engine 8080"

Security Best Practices

Network Segmentation

Principle of Least Privilege: Ogni servizio accede solo alle risorse necessarie
Internal Networks: Servizi sensibili su reti interne
Firewall Rules: Blocco traffico non necessario

Traffic Encryption

TLS Everywhere: Terminazione TLS su Traefik, comunicazione interna cifrata quando possibile
Certificate Rotation: Gestione automatica rinnovo certificati
HSTS Headers: Enforcement HTTPS strict

Access Control

# Middleware autenticazione per servizi admin
labels:
  - "traefik.http.routers.admin.middlewares=auth@file"

# config/traefik/dynamic/auth.yml
http:
  middlewares:
    auth:
      basicAuth:
        users:
          - "admin:$2a$10$encrypted_password"

Riferimenti

Prossimi Passi

Architettura Docker - Dettagli implementazione container
Architettura di Sicurezza - Security patterns e RBAC
Requisiti di Sistema - Network requirements e bandwidth

Architettura di Rete​

Configurazione di Rete Docker​

Network Definitions​

Service Network Assignment​

Traefik Reverse Proxy​

Entry Points Configuration​

Routing Rules​

Host-based Routing​

Path-based Routing (se necessario)​

Service Discovery​

Port Mapping Strategy​

Principi di Esposizione​

Port Allocation Matrix​

DNS Configuration​

Internal Service Discovery​

External DNS Requirements​

Load Balancing & High Availability​

Traefik Load Balancing​

Redis High Availability​

Database Redundancy​

Firewall Rules & Security Groups​

Container Network Isolation​

Port Security Matrix​

Middleware Security​

SSL/TLS Configuration​

Certificate Management​

1. Custom Certificates (Air-Gap Friendly)​

2. Let's Encrypt (Internet Required)​

TLS Security Headers​

Performance Optimization​

Connection Pooling​

Caching Strategy​

Network Performance​

Monitoring & Observability​

Network Monitoring​

Service Health Checks​

Traffic Analysis​

Troubleshooting Network Issues​

Common Network Problems​

Debug Commands​

Security Best Practices​

Network Segmentation​

Traffic Encryption​

Access Control​

Riferimenti​

Prossimi Passi​

Questa pagina ti è stata utile?