# Core Components of Easegress: Architecture Deep Dive for the Cloud-Native Gateway > Explore the core components of Easegress, a cloud-native gateway. Understand its architecture including Cluster, Supervisor, Objects, Filters, Resilience, and Registry for robust API management. - Repository: [easegress-io/easegress](https://github.com/easegress-io/easegress) - Tags: architecture - Published: 2026-03-01 --- **The core components of Easegress comprise the Cluster for distributed state synchronization, the Supervisor for object lifecycle management, four distinct Object types (System Controllers, Business Controllers, Traffic Gates, and Pipelines), pluggable Filters for request processing, Resilience policies for fault tolerance, and the Registry for dynamic plugin discovery.** Easegress is a cloud-native traffic orchestration system that functions as a highly extensible API gateway and service mesh. Understanding the core components of Easegress is essential for developers building custom traffic management solutions. This article examines the architecture based on the `easegress-io/easegress` source code, detailing how these components interact to process HTTP, gRPC, MQTT, and other protocol traffic. ## The Cluster: Distributed Configuration and State Management The **Cluster** component synchronizes configuration and state across all Easegress nodes and persists data to survive restarts. According to the developer guide in [`docs/06.Development-for-Easegress/6.1.Developer-Guide.md`](https://github.com/easegress-io/easegress/blob/main/docs/06.Development-for-Easegress/6.1.Developer-Guide.md), the Cluster ensures that every node in the deployment shares a consistent view of the system configuration without requiring an external datastore for basic operation. ## The Supervisor: Central Lifecycle Orchestrator The **Supervisor** serves as the global manager that creates, registers, and controls the lifecycle of all objects within the system. As defined in [`pkg/registry/registry.go`](https://github.com/easegress-io/easegress/blob/main/pkg/registry/registry.go), the Supervisor maintains the authority to instantiate controllers, traffic gates, and pipelines, ensuring they follow the correct initialization and shutdown sequences. ## The Four Object Types: Building Blocks of Traffic Management The Supervisor manages four distinct kinds of objects that form the operational backbone of Easegress: ### System Controllers **System Controllers** provide essential system-level services such as service registry integration and certificate management. These controllers run continuously to maintain infrastructure-level capabilities required by the gateway. ### Business Controllers **Business Controllers** allow users to define custom controllers for domain-specific business logic. These objects extend Easegress functionality beyond standard traffic management to handle specialized use cases. ### Traffic Gate The **Traffic Gate** receives incoming traffic across multiple protocols including HTTP, gRPC, and MQTT, then forwards requests to appropriate pipelines for processing. This component acts as the entry point into the Easegress processing chain. ### Pipeline The **Pipeline** represents the core processing chain that executes an ordered sequence of filters. According to [`docs/06.Development-for-Easegress/6.1.Developer-Guide.md`](https://github.com/easegress-io/easegress/blob/main/docs/06.Development-for-Easegress/6.1.Developer-Guide.md), pipelines define how requests flow through the system and how responses are generated. ## Pipelines and Filters: The Traffic Processing Engine Pipelines implement the primary request/response manipulation logic through an ordered list of **Filters**. In [`pkg/object/pipeline/pipeline.go`](https://github.com/easegress-io/easegress/blob/main/pkg/object/pipeline/pipeline.go), the Pipeline structure executes filters sequentially, with each filter capable of manipulating the request, producing a result, and optionally jumping to another filter via the `jumpIf` mechanism. ### Filter Execution Flow The execution flow defined in [`pkg/object/pipeline/pipeline.go`](https://github.com/easegress-io/easegress/blob/main/pkg/object/pipeline/pipeline.go) (lines 33-44 and 80-86) processes each filter in sequence. Filters can return results that trigger conditional jumps, allowing for complex routing logic without hardcoded paths. ### Defining Pipelines in Configuration You define a pipeline using YAML configuration that specifies the flow and filter parameters: ```yaml name: my-pipeline kind: Pipeline flow: - filter: headerCounter jumpIf: { invalidHeader: END } filters: - kind: HeaderCounter name: headerCounter headers: ["Cookie", "Authorization"] ``` The `flow` section uses the built-in `END` filter to terminate processing when a filter returns `invalidHeader`. ### Programmatic Pipeline Creation For dynamic scenarios, you can construct pipelines programmatically in Go: ```go // Build a pipeline spec (normally loaded from YAML) spec := &pipeline.Spec{ Filters: []map[string]interface{}{ {"kind": "HeaderCounter", "name": "headerCounter", "headers": []string{"Cookie"}}, }, Flow: []pipeline.FlowNode{ {FilterName: "headerCounter"}, {FilterName: pipeline.BuiltInFilterEnd}, }, } // Create a Supervisor and register the pipeline object superSpec := supervisor.NewSpec("my-pipeline", pipeline.Kind, spec) p := &pipeline.Pipeline{} p.Init(superSpec, nil) // Simulate a request context (e.g., HTTP) ctx := context.NewContext() ctx.InputRequest().(*httpprot.Request).HTTPHeader().Set("Cookie", "session=abc") // Run the pipeline result := p.Handle(ctx) fmt.Println("Pipeline finished with result:", result) ``` This code mirrors the `Init` and `Handle` flow implemented in [`pkg/object/pipeline/pipeline.go`](https://github.com/easegress-io/easegress/blob/main/pkg/object/pipeline/pipeline.go). ## Resilience: Fault Tolerance Policies **Resilience** components provide fault-tolerance policies including circuit breakers, retry logic, and timeouts. As implemented in [`pkg/object/pipeline/pipeline.go`](https://github.com/easegress-io/easegress/blob/main/pkg/object/pipeline/pipeline.go) (lines 24-30), these policies can be attached to individual filters or entire pipelines to ensure high availability under adverse conditions. ### Configuring Resilience Policies Resilience policies are defined in YAML and referenced by filters: ```yaml resilience: - name: retryPolicy type: retry retryTimes: 3 interval: "100ms" ``` When the pipeline loads, the `reload` method parses `spec.Resilience` and stores policies in `p.resilience`. Filters implementing the `filters.Resiliencer` interface automatically receive the policy via `InjectResiliencePolicy`. ## The Registry: Dynamic Plugin Discovery The **Registry** serves as the central plugin mechanism that imports all built-in filters and objects. Located in [`pkg/registry/registry.go`](https://github.com/easegress-io/easegress/blob/main/pkg/registry/registry.go) (lines 18-71), the Registry enables the Supervisor to discover and load components at startup without hardcoded references. This modular approach allows developers to add custom filters to `pkg/filters/` and register them via the Registry, making them available for pipeline construction immediately upon system initialization. ## Summary - The **Cluster** maintains distributed state and configuration consistency across Easegress nodes. - The **Supervisor** orchestrates the lifecycle of all objects, ensuring proper initialization and shutdown. - Four **Object types**—System Controllers, Business Controllers, Traffic Gates, and Pipelines—provide the structural framework for traffic management. - **Pipelines** execute **Filters** in sequence, supporting conditional jumps via the `jumpIf` mechanism defined in [`pkg/object/pipeline/pipeline.go`](https://github.com/easegress-io/easegress/blob/main/pkg/object/pipeline/pipeline.go). - **Resilience** policies (circuit breaker, retry, timeout) attach to pipelines and filters to provide fault tolerance. - The **Registry** in [`pkg/registry/registry.go`](https://github.com/easegress-io/easegress/blob/main/pkg/registry/registry.go) enables dynamic discovery of plugins and built-in components. ## Frequently Asked Questions ### What is the role of the Supervisor in Easegress? The Supervisor acts as the global manager that creates, registers, and controls the lifecycle of all objects in the system, including controllers, traffic gates, and pipelines. It ensures that components follow proper initialization sequences and maintains authority over object instantiation as defined in [`pkg/registry/registry.go`](https://github.com/easegress-io/easegress/blob/main/pkg/registry/registry.go). ### How does the Pipeline `jumpIf` mechanism work? The `jumpIf` mechanism allows filters to conditionally alter the execution flow by jumping to a specific filter or the built-in `END` filter based on the result they return. This enables dynamic routing within the pipeline without hardcoded paths, as implemented in [`pkg/object/pipeline/pipeline.go`](https://github.com/easegress-io/easegress/blob/main/pkg/object/pipeline/pipeline.go) lines 80-86. ### Can custom filters be added to Easegress? Yes, developers can create custom filters by implementing the filter interface and registering them through the **Registry** in [`pkg/registry/registry.go`](https://github.com/easegress-io/easegress/blob/main/pkg/registry/registry.go). The Registry imports all built-in and custom filters, making them discoverable by the Supervisor at startup for use in pipeline definitions. ### How are resilience policies applied to traffic processing? Resilience policies defined in the pipeline specification are parsed during the `reload` phase and stored in the pipeline's resilience map. Filters that implement the `filters.Resiliencer` interface automatically receive their assigned policies via the `InjectResiliencePolicy` method, enabling circuit breakers, retries, and timeouts without modifying filter logic.