diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..5406209c --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,30 @@ +**What type of PR is this?** + + + +**What this PR does / why we need it**: + +**Which issue(s) this PR fixes**: +Fixes # + +**Special notes for your reviewer**: + +**Does this PR introduce a user-facing change?**: + +```release-note + +``` diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..108059c3 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,5 @@ +# Orion Proxy Community Code of Conduct + +Orion Proxy follows the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md). + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at `kmesh.net@gmail.com`. diff --git a/README.md b/README.md index 7b1d6b06..fa436df7 100644 --- a/README.md +++ b/README.md @@ -2,65 +2,72 @@ ## Introduction -Orion Proxy is a high performance and memory safe implementation of popular [Envoy Proxy](https://www.envoyproxy.io/). Orion Proxy is implemented in Rust using high-quality open source components. +Orion Proxy is a high performance and memory safe implementation of popular [Envoy Proxy](https://www.envoyproxy.io/). Orion Proxy is implemented in Rust using high-quality open source components. -### Key features +### 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. - +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](docs/performance/performance.md) to see performance figures and for more details how we tested Orion Proxy . - +Orion Proxy offers 2x-4x better throughput and latency than Envoy Proxy. Refer to [Performance](docs/performance/performance.md) 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. -## Quick Start - -**Note:** To control how many CPU cores/threads Orion uses (especially in containers), set the `ORION_CPU_LIMIT` environment variable. In Kubernetes, use the Downward API: +Orion Architecture -```yaml -env: - - name: ORION_CPU_LIMIT - valueFrom: - resourceFieldRef: - resource: limits.cpu - divisor: "1" -``` +### Core Components -## CPU/Thread Limit Configuration +- **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 -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. +### Key Design Principles -### Kubernetes Example (Downward API) - -Add the following to your container spec to set `ORION_CPU_LIMIT` to the container's CPU limit: - -```yaml -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. +- **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 + ```console git clone https://github.com/kmesh-net/orion cd orion @@ -70,6 +77,7 @@ cargo build ``` ### Running + ```console cargo run --bin orion -- --config orion/conf/orion-runtime.yaml ``` @@ -89,7 +97,28 @@ docker run -p 8000:8000 --name orion-proxy orion-proxy curl -v http://localhost:8000/direct-response # Should return HTTP 200 with "meow! 🐱" ``` -### Testing with Backend Servers +For detailed Docker configuration options, see [docker/README.md](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: + +```yaml +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: @@ -108,8 +137,6 @@ curl http://localhost:8000/ # Proxies to nginx backends! docker rm -f backend1 backend2 orion-proxy ``` -For detailed Docker configuration options, see [docker/README.md](docker/README.md). - ## Examples and Demos ### TLV Listener Filter Demo @@ -131,7 +158,6 @@ This demo will: - Show debug logs confirming successful TLV processing - Verify compatibility with Kmesh TLV configuration format - For detailed information, see [examples/tlv-filter-demo/README.md](examples/tlv-filter-demo/README.md). @@ -139,8 +165,6 @@ For detailed information, see [examples/tlv-filter-demo/README.md](examples/tlv- ## License -Orion Proxy is licensed under the -[Apache License, Version 2.0](./LICENSE). - +Orion Proxy is licensed under the [Apache License, Version 2.0](./LICENSE). -[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fkmesh-net%2Forion.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fkmesh-net%2Forion?ref=badge_large) \ No newline at end of file +[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fkmesh-net%2Forion.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fkmesh-net%2Forion?ref=badge_large) diff --git a/docs/pics/architecture/orion_architecture.png b/docs/pics/architecture/orion_architecture.png new file mode 100644 index 00000000..ab2a3342 Binary files /dev/null and b/docs/pics/architecture/orion_architecture.png differ