Skip to content

README.md

Latest commit

 

History

History
170 lines (118 loc) · 6.9 KB

README.md

File metadata and controls

170 lines (118 loc) · 6.9 KB

orion-proxy-logo

Introduction

Orion Proxy is a high performance and memory safe implementation of popular Envoy Proxy. Orion Proxy is implemented in Rust using high-quality open source components.

Key Features

Memory Safety

Rust programming language allows to avoid a whole lot of bugs related to memory management and data races making Orion Proxy a very robust and secure application.

Performance

Orion Proxy offers 2x-4x better throughput and latency than Envoy Proxy. Refer to Performance to see performance figures and for more details how we tested Orion Proxy.

HTTP Benchmark Results
HTTP Requests per Second

Requests per Second

 HTTP Latency

Latency (microseconds)
HTTPS Benchmark Results
HTTPS Requests per Second

Requests per Second

 HTTPS Latency

Latency (microseconds)

Compatibility

Orion Proxy configuration is generated from Envoy's xDS protobuf definitions. Orion Proxy aims to be a drop in replacement for Envoy.

Architecture

Orion Proxy is designed as a high-performance L7 proxy compatible with Envoy's xDS API while delivering superior performance through Rust's zero-cost abstractions and memory safety guarantees.

Orion Architecture

Core Components

  • xDS Client: Subscribes to and processes Envoy xDS APIs (LDS, RDS, CDS, EDS) for dynamic configuration updates
  • Configuration Manager: Manages runtime configuration, converts Envoy protobuf definitions to Orion's internal representation
  • Listener Manager: Handles incoming connections, applies listener filters (TLV, Proxy Protocol, TLS Inspector)
  • Router (L7): HTTP routing, header manipulation, retries, timeouts, and traffic shifting
  • Cluster Manager: Manages upstream clusters, implements load balancing algorithms (round-robin, least-request, random)
  • Transport Layer: High-performance async I/O using Tokio, supports HTTP/1.1, HTTP/2, and raw TCP
  • TLS Engine: Powered by rustls for memory-safe TLS/mTLS, client certificate validation
  • Observability: Prometheus metrics export, OpenTelemetry tracing integration
  • Admin Interface: HTTP API for runtime configuration inspection, metrics, and health checks

Key Design Principles

  • Zero-Copy I/O: Minimizes memory allocations and copies through Rust's ownership system and Bytes buffers
  • Async Runtime: Built on Tokio for efficient handling of thousands of concurrent connections
  • Memory Safety: Eliminates entire classes of bugs (use-after-free, data races) through Rust's type system
  • Envoy Compatibility: Direct protobuf compatibility with Envoy xDS APIs for seamless integration with Istio and other control planes

Quick Start

Building

git clone https://github.com/kmesh-net/orion
cd orion
git submodule init
git submodule update --force
cargo build

Running

cargo run --bin orion -- --config orion/conf/orion-runtime.yaml

Docker

Build and run with Docker:

# Build
docker build -t orion-proxy -f docker/Dockerfile .

# Run
docker run -p 8000:8000 --name orion-proxy orion-proxy

# Verify service
curl -v http://localhost:8000/direct-response # Should return HTTP 200 with "meow! 🐱"

For detailed Docker configuration options, see docker/README.md.

CPU/Thread Limit Configuration

Orion can be configured to use a specific number of CPU cores/threads by setting the ORION_CPU_LIMIT environment variable. This is especially useful in containerized environments where access to /sys/fs may be restricted.

Kubernetes Example (Downward API)

Add the following to your container spec to set ORION_CPU_LIMIT to the container's CPU limit:

env:
    - name: ORION_CPU_LIMIT
      valueFrom:
          resourceFieldRef:
              resource: limits.cpu
              divisor: "1"

Orion will automatically use this value to determine the number of threads/cores.

Testing with Backend Servers

For testing load balancing with real backend servers:

# Start two nginx containers
docker run -d -p 4001:80 --name backend1 nginx:alpine
docker run -d -p 4002:80 --name backend2 nginx:alpine

# Start Orion Proxy (uses host networking to access localhost:4001/4002)
docker run -d --network host --name orion-proxy orion-proxy

# Test load balancing
curl http://localhost:8000/  # Proxies to nginx backends!

# Cleanup
docker rm -f backend1 backend2 orion-proxy

Examples and Demos

TLV Listener Filter Demo

Orion includes a comprehensive TLV (Type-Length-Value) listener filter demo compatible with the Kmesh project for service mesh integration. This demo provides end-to-end testing of the TLV filter functionality.

To test the TLV filter:

cd examples/tlv-filter-demo
./test_tlv_config.sh

This demo will:

  • Start Orion with TLV filter configuration matching Kmesh format
  • Load the TLV listener filter using TypedStruct configuration
  • Send actual TLV packets to test the filter functionality
  • Extract and verify original destination information from TLV data
  • Show debug logs confirming successful TLV processing
  • Verify compatibility with Kmesh TLV configuration format

For detailed information, see examples/tlv-filter-demo/README.md.

License

Orion Proxy is licensed under the Apache License, Version 2.0.

FOSSA Status