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

> Discover the Easegress controller role as the orchestration brain. It defines, watches, and reconciles resource state, translating intent into traffic-handling primitives for your system.

- Repository: [easegress-io/easegress](https://github.com/easegress-io/easegress)
- Tags: deep-dive
- Published: 2026-03-01

---

**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`](https://github.com/easegress-io/easegress/blob/main/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:

```bash

# 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:

```go
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`](https://github.com/easegress-io/easegress/blob/main/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:

```bash
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`](https://github.com/easegress-io/easegress/blob/main/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`](https://github.com/easegress-io/easegress/blob/main/docs/07.Reference/7.01.Controllers.md)** — Comprehensive documentation describing all controller types, their responsibilities, and configuration schemas.

- **[`pkg/object/meshcontroller/ingresscontroller/ingresscontroller.go`](https://github.com/easegress-io/easegress/blob/main/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`](https://github.com/easegress-io/easegress/blob/main/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`](https://github.com/easegress-io/easegress/blob/main/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`](https://github.com/easegress-io/easegress/blob/main/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`](https://github.com/easegress-io/easegress/blob/main/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`](https://github.com/easegress-io/easegress/blob/main/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`](https://github.com/easegress-io/easegress/blob/main/pkg/object/meshcontroller/ingresscontroller/ingresscontroller.go) and [`pkg/object/meshcontroller/spec/ingresscontroller.go`](https://github.com/easegress-io/easegress/blob/main/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`](https://github.com/easegress-io/easegress/blob/main/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`](https://github.com/easegress-io/easegress/blob/main/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.