What Is the Role of the Easegress Controller? A Deep Dive into System and Business Controllers

The Easegress controller is the core runtime abstraction that defines, watches, and reconciles resource state, operating as the orchestration brain that translates high-level intent into low-level traffic-handling primitives.

In the easegress-io/easegress architecture, the controller pattern underpins every aspect of dynamic configuration and traffic management. Whether handling essential platform functions or translating Kubernetes Ingress rules into executable pipelines, the Easegress controller ensures consistency, namespace isolation, and zero-downtime reloading without server restarts.

Easegress Controller Architecture: System vs. Business Controllers

The Easegress controller layer divides into two distinct operational groups, each serving a specific lifecycle and purpose within the cluster.

System controllers run as singletons per Easegress node and manage essential platform-level infrastructure. These controllers cannot be deleted through administrative operations and handle critical functions such as service discovery, traffic gate lifecycles, and internal state synchronization. Key examples include the ServiceRegistry, TrafficController, RawConfigTrafficController, and StatusSyncController.

Business controllers (also referred to as non-traffic controllers) implement higher-level features through create-update-delete operations via the admin API. These controllers consume the traffic-gate primitives provided by the TrafficController to translate external abstractions—such as Kubernetes Ingress, FaaS functions, AI-gateway policies, and WAF rules—into concrete Easegress pipelines, servers, and policies. Notable implementations include the IngressController, FaaSController, AIGatewayController, WAFController, various service-registry drivers, and the AutoCertManager.

How Easegress Controllers Orchestrate Traffic

The interaction between system and business controllers follows a strict reconciliation pattern that ensures declarative state management across the data plane.

The TrafficController System Controller

At the foundation lies the TrafficController, a system controller that owns the concrete traffic gates—HTTPServer, GRPCServer, and Pipeline—tracking them namespace-wise within the Easegress instance. This controller maintains the actual runtime objects that handle network traffic, providing the primitive building blocks upon which all higher-level functionality depends.

Business Controller Workflow: IngressController Example

Business controllers such as the IngressController demonstrate the full reconciliation lifecycle:

1. Watch External Resources: The IngressController monitors Kubernetes resources including Ingress, Service, Endpoint, and Secret objects within specified namespaces.

2. Generate Specifications: Upon detecting changes, the controller invokes IngressControllerHTTPServerSpec and IngressControllerPipelineSpec functions defined in pkg/object/meshcontroller/spec/ingresscontroller.go to translate Kubernetes Ingress rules into Easegress-native HTTPServer and Pipeline specifications.

3. Push to TrafficController: The generated specifications are pushed into the TrafficController, which acts as the source of truth for traffic gate configurations.

4. Reconcile Runtime State: The TrafficController reconciles the desired specifications against the current runtime state, creating, updating, or removing servers and pipelines dynamically without requiring process restarts.

The ServiceRegistry system controller complements this workflow by providing a unified service-discovery interface that business controllers query to resolve backend endpoints, abstracting the complexity of various discovery backends.

Implementing and Deploying Easegress Controllers

Deploying an IngressController with egctl

Create a business controller instance using the command-line interface:

# Create a controller object that watches the default namespace

cat <<EOF > ingresscontroller.yaml
kind: IngressController
name: ingress-controller-example
namespace: default

# optional TLS settings …

EOF

# Apply it to the cluster

egctl create -f ingresscontroller.yaml

Once created, the IngressController begins watching Kubernetes resources in the specified namespace. Each detected change triggers the controller to generate corresponding HTTPServer and Pipeline specifications and push them to the TrafficController.

Programmatic Controller Creation in Go

For custom plugin development, interact with controller specifications programmatically:

import (
    "github.com/easegress-io/easegress/pkg/object/meshcontroller/spec"
    "github.com/easegress-io/easegress/pkg/supervisor"
)

// Build an HTTPServer spec for port 80 with a simple rule
spec, err := spec.IngressControllerHTTPServerSpec(80, []*spec.IngressRule{
    {
        Host: "example.com",
        Paths: []spec.IngressPath{
            {
                PathPrefix: "/",
                Backend:    "my-pipeline",
            },
        },
    },
})
if err != nil {
    panic(err)
}

// Register the spec with the TrafficController (handled internally by the IngressController)
_ = supervisor.NewSpecFromYAML(spec.YAML())

The IngressControllerHTTPServerSpec function in pkg/object/meshcontroller/spec/ingresscontroller.go demonstrates how business controllers translate high-level routing rules into concrete traffic gate configurations.

Listing Active Controllers via API

Query the runtime state of all controllers through the REST API:

curl http://127.0.0.1:12381/apis/v2/controllers

This endpoint returns both system and business controllers, exposing their current status and configuration. The endpoint is served by the generic controller management code in cmd/server/main.go.

Key Source Files and Implementation Details

Understanding the Easegress controller implementation requires familiarity with these critical files:

• docs/07.Reference/7.01.Controllers.md — Comprehensive documentation describing all controller types, their responsibilities, and configuration schemas.

• pkg/object/meshcontroller/ingresscontroller/ingresscontroller.go — Core implementation of the IngressController business controller, including Kubernetes resource watchers, event handlers, and hot-reloading logic.

• pkg/object/meshcontroller/spec/ingresscontroller.go — Helper functions that generate HTTPServer and Pipeline specifications from Ingress resources, bridging the gap between Kubernetes and Easegress abstractions.

• pkg/object/meshcontroller/service/service.go — Persistence layer for controller instance specifications and certificates, utilized by mesh-level controllers for state management.

• cmd/server/main.go — Server entry point that initializes the controller manager and exposes the REST API for controller lifecycle operations.

• helm-charts/ingress-controller/templates/Deployment.yaml — Helm chart manifest for deploying the IngressController as a Kubernetes workload, demonstrating production deployment patterns.

These files collectively demonstrate how the controller abstraction serves as the foundation of Easegress architecture, enabling dynamic traffic orchestration, extensible business logic, and seamless integration with external systems.

Summary

• The Easegress controller is the fundamental runtime abstraction that defines, watches, and reconciles resource state, acting as the orchestration layer between configuration intent and traffic handling.

• System controllers manage platform-level infrastructure including the TrafficController, ServiceRegistry, and StatusSyncController, running as permanent node singletons.

• Business controllers implement domain-specific features like IngressController, FaaSController, and AIGatewayController by translating external resources into traffic gate specifications.

• Controllers interact through a reconciliation pattern where business controllers generate specs and push them to the TrafficController, which manages the actual HTTPServer, GRPCServer, and Pipeline runtime objects.

• The controller architecture enables dynamic reloading, namespace isolation, and extensibility without requiring server restarts.

Frequently Asked Questions

What is the difference between system controllers and business controllers in Easegress?

System controllers are core infrastructure components that run as singletons per Easegress node and cannot be deleted through administrative operations. They manage essential functions such as the TrafficController (which owns concrete traffic gates), ServiceRegistry (for service discovery), and StatusSyncController. Business controllers, conversely, are user-managed resources created via the admin API or egctl that implement higher-level features. They watch external resources like Kubernetes Ingress or FaaS functions and translate them into traffic gate configurations that are pushed to the system controllers for execution.

How does the IngressController interact with the TrafficController?

The IngressController operates as a business controller that watches Kubernetes resources including Ingress, Service, Endpoint, and Secret objects. When it detects changes, it invokes functions such as IngressControllerHTTPServerSpec and IngressControllerPipelineSpec from pkg/object/meshcontroller/spec/ingresscontroller.go to generate Easegress-native specifications. These specifications are then pushed to the TrafficController, which acts as the system controller responsible for reconciling the desired state with the actual runtime objects—creating, updating, or removing HTTPServer and Pipeline instances dynamically without requiring a process restart.

Can I create custom business controllers for Easegress?

Yes, Easegress supports extensibility through custom business controllers. You can implement new controllers by leveraging the supervisor package and following the patterns established by existing controllers like the IngressController or FaaSController. The implementation involves defining a controller struct that implements the controller interface, handling configuration specs via supervisor.NewSpecFromYAML, and interacting with system controllers such as the TrafficController to register generated traffic gate configurations. The source files pkg/object/meshcontroller/ingresscontroller/ingresscontroller.go and pkg/object/meshcontroller/spec/ingresscontroller.go provide reference implementations for how to translate external domain models into Easegress runtime specifications.

Where are controller specifications stored in the Easegress codebase?

Controller specifications are persisted and managed through the supervisor layer, with specific implementations located in pkg/object/meshcontroller/service/service.go. This file handles the storage and retrieval of controller instance specifications, certificates, and related configuration data for mesh-level controllers. When controllers are created via the admin API or egctl, their specifications are processed through cmd/server/main.go, which initializes the controller manager and exposes REST endpoints at /apis/v2/controllers for listing active controller states. The specifications themselves are YAML-based configurations that define the desired state for both system and business controllers.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}