Edgion

Chinese | English

What is Edgion?

A high-performance API Gateway built on Pingora and Gateway API. Designed for both Kubernetes and standalone (bare-metal / VM) environments. A modern Rust-native alternative to Kong, APISIX, Traefik, Envoy, and HAProxy.

Feature Highlights

• Rust-native performance — Built on Cloudflare's Pingora and Tokio. Memory-safe, no GC pauses, predictable latency under load.
• Gateway API support — Native implementation of the Kubernetes Gateway API standard. Runs in Kubernetes or standalone mode from the same binary.
  • v1 GA: GatewayClass · Gateway · HTTPRoute · GRPCRoute · TLSRoute · ReferenceGrant · BackendTLSPolicy
  • v1alpha2 Experimental: TCPRoute · UDPRoute
• Multi-protocol — HTTP/1.1, HTTP/2, gRPC, TCP, UDP, WebSocket, SNI proxy.
• Dynamic hot reload — Every change to routes, backends, plugins, or certificates propagates across all gateways instantly. No restart.
• Production-ready Kubernetes controller — Full reconciliation loop, status reporting, and CRD lifecycle management out of the box.
• High-performance routing — Radix tree with cache optimization and path variable support for Exact/Prefix matching. Priority-based rule evaluation per Gateway API spec.
• Advanced TLS — mTLS, ACME auto-provisioning (HTTP-01 / DNS-01), per-domain TLS version and cipher suite control.
• Traffic management — Weighted canary routing; multiple load balancing algorithms (Round Robin, EWMA, Least Connections, Consistent Hashing, Weighted).
• Powerful plugin system — Composable via plugin reference, with a built-in DSL for custom logic.
  • HTTP plugins: Authentication · Security · Traffic management · Observability (25+)
  • Stream plugins: TCP/UDP traffic control
  • DSL: OpenResty/Lua-level expressiveness with native Rust performance
• Deep observability — Structured logs across the full request lifecycle. One line, full picture. AI friendly.
  • Access log: routing/upstream details and per-plugin behaviors in a single JSON line
  • TLS log: SSL handshake and certificate details per connection
  • Stream log: connection lifecycle events for long-lived connections (WebSocket, TCP)
  • Flexible output: local file or remote Kafka / Elasticsearch
• Kubernetes-free deployment — Runs standalone on bare-metal or VMs. Local file or etcd as the config backend — no Kubernetes required.
• Federated cluster design — A stateless Center connects multiple Controllers across regions, enabling cluster-wide and region-level advanced routing control.
• For full documentation, see English Docs · Chinese Docs.

Architecture

Gateway API Configuration

Edgion implements the Kubernetes Gateway API spec. Currently supports v1.5.1.

Gateway API Support

• v1.HTTPRoute
• v1.GRPCRoute
• v1.TLSRoute
• v1.ReferenceGrant
• v1.BackendTLSPolicy
• v1alpha2.TCPRoute
• v1alpha2.UDPRoute

Edgion Custom Resources

• edgion.io/v1.EdgionTls
• edgion.io/v1.EdgionPlugins
• edgion.io/v1.EdgionStreamPlugins

Pingora Request Lifecycle

Edgion's data plane is built on Pingora, Cloudflare's battle-tested Rust proxy framework. Pingora models each request as a pipeline of well-defined phases, giving precise control over every step — from connection acceptance to access log emission. Each phase is an async hook that runs in order; any phase can short-circuit the pipeline and send a response directly.

Edgion hooks into the following phases:

Phase	What Edgion does
early_request_filter	Client timeout and keepalive setup; graceful shutdown detection
request_filter	Route matching; full HTTP/gRPC plugin chain execution (auth, rate limit, rewrite, etc.)
upstream_peer	Backend selection via load balancing; session persistence; retry deadline check
upstream_request_filter	Upstream request header modification
request_body_filter	Request body plugins (e.g. bandwidth limit)
upstream_response_filter	Upstream response header inspection and rewrite
response_filter	Response plugin chain; gRPC-Web bridging
logging	Structured access log emission (local file / Kafka / Elasticsearch)

graph TD;
    start("new request")-->early_request_filter;
    early_request_filter-->request_filter;
    request_filter-->upstream_peer;

    upstream_peer-->Connect{{IO: connect to upstream}};

    Connect--connection success-->connected_to_upstream;
    Connect--connection failure-->fail_to_connect;

    connected_to_upstream-->upstream_request_filter;
    upstream_request_filter --> request_body_filter;
    request_body_filter --> SendReq{{IO: send request to upstream}};
    SendReq-->RecvResp{{IO: read response from upstream}};
    RecvResp-.feature: adjust_upstream_modules.->adjust_upstream_modules;
    adjust_upstream_modules-->upstream_response_filter-->response_filter-->upstream_response_body_filter-->response_body_filter-->logging-->endreq("request done");

    fail_to_connect --can retry-->upstream_peer;
    fail_to_connect --can't retry-->fail_to_proxy--send error response-->logging;

    RecvResp--failure-->IOFailure;
    SendReq--failure-->IOFailure;
    error_while_proxy--can retry-->upstream_peer;
    error_while_proxy--can't retry-->fail_to_proxy;

    request_filter --send response-->logging

    Error>any response filter error]-->error_while_proxy
    IOFailure>IO error]-->error_while_proxy

Loading

Components & Cluster Topology

Component	Binary	Role
Center	edgion-center	Federated control plane. Connects multiple Controllers across clusters or regions, enabling global routing policies and cross-cluster visibility.
Controller	edgion-controller	Watches Kubernetes CRDs or local YAML, validates and pre-parses resources, streams configuration to Gateways via gRPC. Handles ACME and status updates.
Gateway	edgion-gateway	Stateless data plane built on Pingora. Receives config from Controller, executes routing, plugin chains, load balancing, TLS, and access logging.
CLI	edgion-cli	Management tool for inspecting and operating Controller and Gateway instances.

graph TD
    Center[Center] --> C1[Controller 1]
    Center --> C2[Controller 2]
    Center --> C3[Controller 3]

    C1 --> G1[Gateway]
    C1 --> G2[Gateway]
    C1 --> G3[...]

    C2 --> G4[Gateway]
    C2 --> G5[Gateway]

    C3 --> G6[Gateway]
    C3 --> G7[Gateway]
    C3 --> G8[...]

Loading

Configuration Examples

A minimal end-to-end setup: route HTTPS traffic, enforce JWT authentication and rate limiting, and attach a TLS certificate — each as a standalone Kubernetes resource.

HTTPRoute — path-based routing

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-api
  namespace: default
spec:
  parentRefs:
    - name: my-gateway
  hostnames:
    - "api.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api/
      filters:
        - type: ExtensionRef
          extensionRef:
            group: edgion.io
            kind: EdgionPlugins
            name: api-plugins
      backendRefs:
        - name: api-service
          port: 8080

EdgionPlugins — JWT auth + rate limiting

apiVersion: edgion.io/v1
kind: EdgionPlugins
metadata:
  name: api-plugins
  namespace: default
spec:
  requestPlugins:
    - enable: true
      type: JwtAuth
      config:
        secret: "your-jwt-secret"
    - enable: true
      type: RateLimit
      config:
        key:
          - type: clientIp
        limit: 100
        window: "60s"

EdgionTls — HTTPS certificate binding

apiVersion: edgion.io/v1
kind: EdgionTls
metadata:
  name: api-tls
  namespace: default
spec:
  hosts:
    - "api.example.com"
  secretRef:
    name: api-tls-secret   # kubernetes.io/tls Secret
    namespace: default

Plugins

Built-in Plugins

25+ built-in plugins via EdgionPlugins CRD, composable through Plugin Composition:

Authentication — Basic Auth · JWT Auth · Key Auth · HMAC Auth · LDAP Auth · Forward Auth · OpenID Connect · JWE Decrypt · Header Cert Auth

Security — CORS · CSRF · IP Restriction · Request Restriction

Traffic Management — Rate Limit · Rate Limit (Redis) · Proxy Rewrite · Response Rewrite · Bandwidth Limit · Request Mirror · Direct Endpoint · Dynamic Upstream

Observability & Utilities — Real IP · Ctx Setter · Mock

Gateway API Standard Filters — Request Header Modifier · Response Header Modifier · Request Redirect · URL Rewrite

Stream Plugins (TCP/UDP) — IP Restriction

DSL Extension

OpenResty achieves gateway extensibility by embedding Lua scripts into Nginx phases via LuaJIT. This works well but carries inherent trade-offs: Lua is a separate runtime, scripts share the process memory space without isolation, and resource consumption is difficult to bound per request.

Edgion takes a different approach. The DSL plugin runs scripts in a sandboxed VM written in Rust, isolated from the host process. Each script execution is strictly bounded by configurable limits:

Limit	Default	Description
maxSteps	10,000	Total execution steps
maxLoopIterations	100	Per-loop iterations
maxCallCount	500	Function call count
maxStackDepth	128	Call stack depth
maxStringLen	8,192	String length

Scripts can be deployed as source code or pre-compiled to bytecode (Base64) for faster startup and obfuscation.

Request phase — enforce an API token:

apiVersion: edgion.io/v1
kind: EdgionPlugins
metadata:
  name: require-token
  namespace: default
spec:
  requestPlugins:
    - enable: true
      type: Dsl
      config:
        name: "require-api-token"
        errorPolicy: Deny
        source: |
          let token = req.header("X-Api-Token")
          if token == nil {
            return deny(401, "missing X-Api-Token header")
          }
          ctx.set("api_token", token)
          return next()

Request phase — inject routing tag from query param:

        source: |
          let region = req.query("region")
          if region != nil {
            req.set_header("X-Route-Region", region)
          }
          return next()

Response phase — append upstream timing header:

  upstreamResponseFilterPlugins:
    - enable: true
      type: Dsl
      config:
        name: "add-timing-header"
        source: |
          let token = ctx.get("api_token")
          if token != nil {
            resp.set_header("X-Authenticated-Token", token)
          }
          return next()

For full DSL API reference and advanced usage, see the DSL Plugin Documentation.

Deployment

All deployment manifests, Helm charts, and scripts are maintained in a dedicated repository: Pandaala/edgion-deploy.

The following deployment modes are supported:

• Kubernetes — Standard production deployment. Runs Controller and Gateway as separate workloads in a Kubernetes cluster, watching CRDs via the Kubernetes API.

• Standalone (Bare-Metal / VM) — Runs Controller and Gateway as native processes without Kubernetes. Configuration is sourced from local YAML files or etcd.

• All-in-One Container — A single container image bundling Controller, Gateway, and the management frontend. Designed for quick evaluation, demos, and single-node environments.

Documentation

	Guide	Description
📘	User Guide	HTTPRoute, GRPCRoute, plugins, load balancing, resilience, and traffic management
🔧	Ops Guide	Gateway configuration, TLS, observability, ACME, and production operations
🛠️	Dev Guide	Architecture internals, adding resources/plugins, coding conventions
🚀	Getting Started	Installation, first gateway, and core concepts

Roadmap

• Body Cache & Processing — Request/response body caching and transformation support
• HTTP/3 — Native HTTP/3 support across the gateway stack
• WAF — Web Application Firewall integration
• edgion-cli AI Enhance — AI-powered inspection, diagnostics, and operation assistance in the CLI
• Mesh — Service mesh capabilities

Contributing

Contributions are welcome! Please check out:

• Developer Documentation
• Adding New Resources Guide

License

Edgion is licensed under the Apache License, Version 2.0.