Documentation - Jetpath

Getting Started

Jetpath is a high-performance kernel-level load balancer designed as a drop-in replacement for NGINX Ingress Controller. It provides kernel-level packet processing for sub-millisecond latency.

Prerequisites

Linux kernel 5.4+ with BPF support
Kubernetes 1.24+ (for K8s deployment)
Docker or containerd runtime
Privileged container access (for kernel integration)

Installation

Docker Deployment

# Pull the latest image
docker pull edgenexus/jetpath:latest

# Run with host networking (required for kernel integration)
docker run -d --name jetpath \
  --privileged \
  --network host \
  -v /etc/jetpath:/etc/jetpath \
  edgenexus/jetpath:latest

Kubernetes Deployment

# Add Helm repository
helm repo add jetpath https://edgenexus.github.io/Jetpath_Public
helm repo update

# Install Jetpath
helm install jetpath jetpath/jetpath \
  --namespace jetpath-system \
  --create-namespace \
  --set ddos.enabled=true \
  --set metrics.enabled=true

Configuration Examples

Basic Load Balancing with Round Robin

# Create an instance
curl -X POST "http://localhost:8080/v1/instances" \
  -H "Content-Type: application/json" \
  -d '{
    "interface": "eth0",
    "modes": ["load_balancing"]
  }'

# Add a service with round-robin load balancing
curl -X POST "http://localhost:8080/v1/services?instance_id=inst-1" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web",
    "protocol": "tcp",
    "listeners": [{"vip": "10.0.0.100", "port": 80}],
    "lb_policy": {"type": "round_robin"},
    "destinations": [
      {"id": "web-1", "ip": "10.0.1.10", "port": 80, "weight": 1},
      {"id": "web-2", "ip": "10.0.1.11", "port": 80, "weight": 1}
    ]
  }'

HTTP Host-Based Routing

{
  "id": "svc-web",
  "name": "web",
  "protocol": "tcp",
  "service_type": "http",
  "listeners": [{"vip": "10.0.0.100", "port": 80}],
  "lb_policy": {"type": "round_robin"},
  "destinations": [
    {"id": "web-1", "ip": "10.0.1.10", "port": 80, "weight": 1},
    {"id": "web-2", "ip": "10.0.1.11", "port": 80, "weight": 1}
  ],
  "http": {
    "verbs": ["GET", "POST"],
    "host_policy": ["example.com", "api.example.com"],
    "host_match": "exact"
  }
}

Cookie Persistence (Session Affinity)

{
  "id": "svc-app",
  "name": "app-with-sessions",
  "protocol": "tcp",
  "service_type": "http",
  "listeners": [{"vip": "10.0.0.100", "port": 8080}],
  "lb_policy": {"type": "cookie_persistent"},
  "persistence": {
    "enabled": true,
    "type": "cookie",
    "timeout_sec": 3600,
    "cookie_name": "SERVERID"
  },
  "forwarding_mode": "proxy",
  "destinations": [
    {"id": "app-1", "ip": "10.0.1.10", "port": 8080, "weight": 1},
    {"id": "app-2", "ip": "10.0.1.11", "port": 8080, "weight": 1}
  ]
}

Source IP Persistence

{
  "id": "svc-api",
  "name": "api-source-persist",
  "protocol": "tcp",
  "listeners": [{"vip": "10.0.0.100", "port": 443}],
  "lb_policy": {"type": "source_persistent"},
  "persistence": {
    "enabled": true,
    "type": "source",
    "timeout_sec": 7200,
    "source_key": "src_ip"
  },
  "destinations": [
    {"id": "api-1", "ip": "10.0.1.10", "port": 443, "weight": 1},
    {"id": "api-2", "ip": "10.0.1.11", "port": 443, "weight": 1}
  ]
}

L7 Routing Rules

Route traffic based on HTTP host headers:

{
  "routes": [
    {
      "id": "route-api",
      "name": "API traffic",
      "priority": 100,
      "match": {"host": "api.example.com", "host_match": "exact"},
      "action": {"service_id": "svc-api"}
    },
    {
      "id": "route-web",
      "name": "Web traffic",
      "priority": 50,
      "match": {"host": "*.example.com", "host_match": "wildcard"},
      "action": {"service_id": "svc-web"}
    }
  ]
}

DDoS Protection

Built-in kernel-level DDoS protection:

Block Malicious IPs

# Block a single IP
curl -X POST "http://localhost:8080/v1/drop-list?instance_id=inst-1" \
  -H "Content-Type: application/json" \
  -d '{"ip": "198.51.100.5", "reason": "DDoS source"}'

# Block an IP range
curl -X POST "http://localhost:8080/v1/drop-list?instance_id=inst-1" \
  -H "Content-Type: application/json" \
  -d '{"ip_range": {"start": "198.51.100.0", "end": "198.51.100.255"}, "reason": "abuse"}'

Rate Limiting

curl -X PUT "http://localhost:8080/v1/ddos/rate-limit?instance_id=inst-1" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "pps": 10000,
    "burst": 20000
  }'

SYN Flood Protection

curl -X PUT "http://localhost:8080/v1/ddos/syn-protection?instance_id=inst-1" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

Full DDoS Configuration

{
  "ddos": {
    "rate_limit": {
      "enabled": true,
      "pps": 10000,
      "burst": 20000
    },
    "syn_protection": {
      "enabled": true
    }
  },
  "drop_list": [
    {"ip": "198.51.100.5", "reason": "abuse"},
    {"ip_range": {"start": "203.0.113.0", "end": "203.0.113.255"}, "reason": "blocked network"}
  ]
}

Migrating from NGINX Ingress

Jetpath provides compatibility with NGINX Ingress annotations. Most configurations can be migrated directly:

# Your existing Ingress resources work with Jetpath
# Just update the ingress class:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-app
  annotations:
    kubernetes.io/ingress.class: jetpath
spec:
  rules:
  - host: myapp.example.com
    http:
      paths:
      - path: /
        backend:
          service:
            name: my-service
            port: 80

API Reference

Full API documentation is available on SwaggerHub:

View API on SwaggerHub →

Troubleshooting

Common issues and solutions:

Kernel module not loading: Ensure kernel 5.4+ and privileged mode
High CPU usage: Check if native mode is supported by NIC
Connection drops: Review DDoS thresholds in configuration