Easegress: a Go traffic orchestration system that chains filters into pipelines

The problem Easegress solves for platform teams

Most teams end up running a reverse proxy, an API gateway, a service mesh control plane and a set of resilience libraries as four separate systems. Each has its own config format, its own upgrade cycle and its own failure modes. Easegress targets that sprawl by describing itself as a cloud native traffic orchestration system: one Go binary that proxies traffic through user-defined pipelines built from filters.

The intended audience is platform and infrastructure engineers running microservices, usually on Kubernetes. The README lists integration points for Kubernetes Ingress, the EaseMesh sidecar and workflow systems, which tells you the project assumes a container-orchestrated environment rather than a single VM. It also lists service discovery integrations with Eureka, Consul, Etcd and Zookeeper, so it expects an existing registry rather than asking you to adopt a new one.

There is an AI angle in the feature list as well: proxying requests to LLM providers such as OpenAI, DeepSeek and Anthropic, adapting Anthropic API requests and responses to OpenAI format, and caching against vector databases. That is a narrower use case, but it means the same process can front both ordinary HTTP services and model endpoints.

How the pipeline and filter mechanism actually routes traffic

The core abstraction is the pipeline. A pipeline is an ordered chain of filters, and each filter performs one job on the request or response as it passes through. The README names filters for load balancing (round-robin, random, weighted random, IP hash, header hash, with sticky sessions), caching, compression, circuit breaking, rate limiting, retry and time limiting. Routing rules match on exact path, path prefix, path regular expressions, method, headers and client IPs.

Because filters are chained rather than configured as independent subsystems, ordering is a design decision you own. A rate limiter placed before authentication rejects traffic earlier and cheaper; placed after, it counts only authenticated requests. The documentation does not appear to prescribe a canonical order, so the sequence in your pipeline config is the behaviour.

Availability comes from a different layer. Easegress embeds Raft consensus and leader election, so nodes are either primary or secondary, and the README describes node-level observability for role, Raft leader status, health and last heartbeat time. Configuration lives in the cluster rather than in a local file that each node reads independently. The README also claims hot update of both config and binary in place without losing connections, which is the operational counterpart to that design.

Extensibility runs two ways. You can write a filter or controller in a high-level language and rebuild, or execute user-developed WebAssembly code through the wasmhost build tag. The Makefile shows that including wasmhost forces CGO_ENABLED=1, so the pure-Go static build story changes the moment you want Wasm filters.

Installing Easegress and proxying your first backend

The README points to docs/01.Getting-Started/1.2.Install.md for installation, and states that Easegress can be installed from pre-built binaries or from source. It does not reproduce the steps in the README itself, so treat the docs directory as the source of truth for versions and download URLs. Building from source is the path the repository makes explicit: the Makefile defines build targets and pins RELEASE to v2.11.0, and go.mod requires Go 1.26.0 with toolchain go1.26.1.

make build

That target produces binaries under the bin directory defined in the Makefile. The server binary is easegress-server and the client is egctl; both names come from the Makefile's TARGET_SERVER and TARGET_CLIENT variables. To start a single-node instance, the example directory contains a primary-single configuration, which is the simplest way to get a running process without forming a cluster.

Once the server is up, the basic usage described in the README is to set up a proxy for backend servers. The example directory ships shell helpers for this: create_objects.sh, update_objects.sh and delete_objects.sh, plus a config directory and a check_cluster_status.sh script. Those scripts drive egctl, which the README lists alongside the Easegress Portal, curl and Postman as supported ways to talk to the running instance. The workflow is to apply a pipeline definition, confirm the object exists, then send traffic through the listener and watch the backend receive it.

Where Easegress is the wrong tool

The Raft requirement is the first real constraint. Every deployment needs a cluster of nodes agreeing on configuration, which is more moving parts than a single-process proxy. If your traffic is a handful of virtual hosts and a static upstream list, you are paying for consensus you will never use.

The second constraint is the configuration surface. Filters, pipelines, routing rules and controllers are separate object types, and the README does not present a minimal single-file example that exercises all of them. The learning curve is the object model, not the YAML syntax. Teams expecting to drop in an nginx.conf equivalent will find the mental model different.

The third is build complexity. The default build disables CGO, but the Makefile explicitly switches CGO_ENABLED to 1 when the wasmhost tag is present. If you want WebAssembly filters, you give up the straightforward static binary and take on a C toolchain in your build image. The Makefile also carries a workaround note that Go 1.26.1 crashes before tests start when -race and -gcflags=all=-l are combined, which is a reminder that the test matrix has sharp edges tied to specific toolchain versions.

Finally, the README makes performance claims such as lightweight and essential features speed up performance, but it publishes no benchmark numbers. Treat throughput as something you measure on your own hardware.

Easegress compared with Envoy and nginx

Envoy solves a similar problem with a different model. Its unit of configuration is the listener, cluster and filter chain assembled through xDS, and its control plane is a separate process you supply yourself. Easegress folds the control plane into the same binary through Raft, so there is no external xDS server to run. The trade-off is that Envoy's ecosystem of third-party control planes and its data plane API are far more widely deployed, and Easegress expects you to use its own object model and egctl.

nginx is the other common comparison. It is a mature reverse proxy with a configuration file and a reload signal. Easegress replaces the file-and-reload cycle with a distributed object store and hot update, and adds filters nginx does not ship, such as circuit breaking and API orchestration. What nginx gives you instead is decades of operational familiarity and a much smaller process to reason about when something goes wrong at 3am.

If your requirement is a Kubernetes ingress controller specifically, note that Easegress lists Kubernetes Ingress integration as one of several integration points rather than its primary identity. The mesh features, including Mesh Master, Mesh Sidecar and the mesh ingress controller, are noted in the README as being leveraged by EaseMesh, so that path assumes you are also adopting that project.

Licence, releases and upgrade cost

Easegress is Apache-2.0, and the repository carries a .licenserc.json file alongside the LICENSE, which is the configuration for licence header checks in the codebase. Apache-2.0 permits commercial use and modification and includes a patent grant; it also requires that you preserve notices. That is a summary of the licence text, not legal advice, and the go.mod dependency list includes libraries under other licences that you should review if you redistribute a built binary.

The release cadence visible here is roughly two releases a year: v2.9.4 on 2025-08-25, v2.10.1 on 2025-09-18, and v2.11.0 on 2026-03-18. The last push to the repository was on 2026-07-20, and the repository is not archived. The Makefile pins RELEASE to v2.11.0 and the builder image to megaease/golang:1.26.1-alpine, so a source build tracks the current release unless you override the variable.

Upgrade cost centers on the hot-update claim in the README: config and binary update in place without losing connections. The README does not document rollback, so plan for how you would revert a bad pipeline definition before you rely on that. Because configuration is replicated through Raft, a bad object propagates to every node rather than staying local to one.

Editorial conclusion

Adopt Easegress if you already run Kubernetes or a cluster of Go services and want routing, resilience filters and deployment strategies in one configurable data plane rather than three separate tools. Do not adopt it if all you need is a single static reverse proxy for a handful of hosts, or if you cannot operate a Raft cluster. Before committing, verify the install path in docs/01.Getting-Started/1.2.Install.md, then build one pipeline by hand with egctl and confirm the filter order and fallback behaviour match your expectations.

Frequently asked questions

Official sources

1. easegress-io/easegress on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases