Easegress Configuration Format: A Complete Guide to YAML Server and Resource Configs

Easegress uses YAML for all configuration, including server instance settings (node-level) and resource definitions (pipelines, filters, HTTPServers), parsed via pkg/option/option.go and applied through egctl or startup flags.

The configuration format for Easegress (from the easegress-io/easegress repository) is entirely YAML-based, split into two distinct categories: server configuration that controls how an Easegress instance starts and joins clusters, and resource configuration that declaratively defines traffic management objects like pipelines and HTTP servers.

Server Instance Configuration Format

Server configuration files control node-level settings such as cluster membership, storage locations, and networking parameters. These files are typically passed to the binary via the --config-file flag handled in cmd/server/main.go.

Core Configuration Sections

The top-level fields define the node's identity and operational directories. According to the documentation in docs/05.Administration/5.1.Config-and-Cluster-Deployment.md, the essential fields include:

• name: Human-readable identifier for the member
• cluster-name: Logical cluster grouping
• cluster-role: Either primary (persists state) or secondary (does not persist)
• api-addr: Administration API endpoint
• data-dir: Location for persistent data
• log-dir: Location for log files
• debug: Boolean flag for verbose logging

Cluster Networking Parameters

The cluster section contains etcd-compatible networking settings that control peer-to-peer and client communication. These map directly to the underlying etcd configuration parsed by pkg/option/option.go:

cluster:
  listen-peer-urls:
    - http://<CURRENT-HOST>:2380
  listen-client-urls:
    - http://<CURRENT-HOST>:2379
  advertise-client-urls:
    - http://<CURRENT-HOST>:2379
  initial-advertise-peer-urls:
    - http://<CURRENT-HOST>:2380
  initial-cluster:
    - machine-1: http://<HOST-1>:2380
    - machine-2: http://<HOST-2>:2380
    - machine-3: http://<HOST-3>:2380

All fields in the server configuration are optional unless explicitly required for clustering, with missing values falling back to defaults defined in the binary.

Resource Configuration Format

Resource configurations describe the actual traffic management objects—pipelines, HTTP servers, ingress controllers—that Easegress manages. These files use a Kubernetes-like API structure with apiVersion, kind, metadata, and spec sections.

API Version and Kind Declaration

Every resource YAML begins with standard header fields that identify the schema version and object type. The apiVersion is typically easegress.io/v1, and the kind corresponds to the controller name (e.g., Pipeline, HTTPServer).

Pipeline and Filter Specifications

The spec field contains the controller-specific configuration. For example, a Pipeline resource (from example/config/pipeline-example.yaml) defines a sequence of filters:

apiVersion: easegress.io/v1
kind: Pipeline
metadata:
  name: hello-pipeline
spec:
  filters:
    - kind: Proxy
      spec:
        httpServer:
          name: hello-http-server
        pools:
          - name: main
            servers:
              - url: http://127.0.0.1:8080

Similarly, an HTTPServer resource binds ports to pipelines:

apiVersion: easegress.io/v1
kind: HTTPServer
metadata:
  name: hello-http
spec:
  ports:
    - 8080
  pipelines:
    - hello-pipeline

The schema for each kind is defined in the corresponding controller's spec.go file (e.g., pkg/controllers/httpserver/spec.go).

How Easegress Parses YAML Configuration

The configuration format for Easegress relies on a two-stage parsing process implemented in the source code.

Server Configuration Parsing occurs in pkg/option/option.go via the LoadFromFile function. This unmarshals the server YAML into Go structs that define cluster membership, storage paths, and network addresses.

Resource Configuration Parsing uses the yaml.v3 package to unmarshal resource files into controller-specific Spec structs located in files like pkg/controllers/*/spec.go. After parsing, the pkg/v validation package runs Validate() methods to ensure required fields are present and values are within acceptable ranges before the objects are stored in the runtime state.

Practical Configuration Examples

Minimal Server Config

Create a config.yaml for a single-node development instance:

name: my-node
cluster-name: demo
cluster-role: primary
api-addr: 127.0.0.1:2381
data-dir: ./data
log-dir: ./log
debug: true

cluster:
  listen-peer-urls:
    - http://127.0.0.1:2380
  listen-client-urls:
    - http://127.0.0.1:2379
  advertise-client-urls:
    - http://127.0.0.1:2379
  initial-advertise-peer-urls:
    - http://127.0.0.1:2380
  initial-cluster:
    - my-node: http://127.0.0.1:2380

Start the instance:

easegress-server --config-file config.yaml

HTTPServer Resource Definition

Define an HTTP server in httpserver.yaml:

apiVersion: easegress.io/v1
kind: HTTPServer
metadata:
  name: hello-http
spec:
  ports:
    - 8080
  pipelines:
    - hello-pipeline

Apply it with egctl:

egctl apply -f httpserver.yaml

Combined Startup with Resources

Launch a server and preload resources in one command:

easegress-server \
  --config-file config.yaml \
  --initial-object-config-files httpserver.yaml,pipeline.yaml

This approach, handled in cmd/server/main.go, is useful for GitOps workflows where the desired state is defined in version-controlled YAML files.

Summary

• Easegress configuration format is entirely YAML-based, split between server instance settings and resource definitions.
• Server configuration (config.yaml) controls node identity, clustering, storage, and networking via fields like cluster-role, api-addr, and the cluster section.
• Resource configuration uses Kubernetes-style manifests with apiVersion: easegress.io/v1, kind, metadata, and spec to define pipelines, HTTP servers, and filters.
• Parsing occurs via pkg/option/option.go for server configs and yaml.v3 for resources, with validation in pkg/v before runtime storage.
• Deployment uses --config-file for server startup and --initial-object-config-files or egctl apply for resources.

Frequently Asked Questions

What file extension does Easegress configuration use?

Easegress configuration files use the .yaml extension. While the server configuration file can be named arbitrarily (commonly config.yaml), resource definition files typically use descriptive names like httpserver.yaml or pipeline.yaml to indicate their contents.

How do I validate my Easegress YAML configuration before applying it?

The Easegress binary performs validation automatically when loading configurations. For server configs, pkg/option/option.go checks structural validity, while resource configs are validated by the pkg/v package against the Spec structs defined in each controller (e.g., pkg/controllers/httpserver/spec.go). Run easegress-server --config-file config.yaml in a test environment to catch parsing errors before production deployment.

Can I use environment variables in Easegress configuration files?

The raw YAML parser in Easegress does not natively expand environment variables during file loading. However, you can preprocess YAML files using external tools like envsubst before passing them to Easegress, or use orchestration platforms (Kubernetes, Docker Compose) that handle environment substitution before mounting configs into the container.

Where are the configuration schemas defined for Easegress resources?

Resource schemas are defined in Go struct files within the controllers directory. For example, HTTPServer specifications are defined in pkg/controllers/httpserver/spec.go, while Pipeline specifications reside in pkg/controllers/pipeline/spec.go. These structs are unmarshaled from YAML using the yaml.v3 package and validated by methods in the pkg/v package before being stored in the cluster state.

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