# Easegress Configuration Format: A Complete Guide to YAML Server and Resource Configs > Master Easegress configuration format with this comprehensive YAML guide. Learn to manage server and resource settings efficiently using egctl or startup flags. - Repository: [easegress-io/easegress](https://github.com/easegress-io/easegress) - Tags: how-to-guide - Published: 2026-03-01 --- **Easegress uses YAML for all configuration, including server instance settings (node-level) and resource definitions (pipelines, filters, HTTPServers), parsed via [`pkg/option/option.go`](https://github.com/easegress-io/easegress/blob/main/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`](https://github.com/easegress-io/easegress/blob/main/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`](https://github.com/easegress-io/easegress/blob/main/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`](https://github.com/easegress-io/easegress/blob/main/pkg/option/option.go): ```yaml cluster: listen-peer-urls: - http://:2380 listen-client-urls: - http://:2379 advertise-client-urls: - http://:2379 initial-advertise-peer-urls: - http://:2380 initial-cluster: - machine-1: http://:2380 - machine-2: http://:2380 - machine-3: http://: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`](https://github.com/easegress-io/easegress/blob/main/example/config/pipeline-example.yaml)) defines a sequence of filters: ```yaml 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: ```yaml 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`](https://github.com/easegress-io/easegress/blob/main/spec.go) file (e.g., [`pkg/controllers/httpserver/spec.go`](https://github.com/easegress-io/easegress/blob/main/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`](https://github.com/easegress-io/easegress/blob/main/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`](https://github.com/easegress-io/easegress/blob/main/config.yaml) for a single-node development instance: ```yaml 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: ```bash easegress-server --config-file config.yaml ``` ### HTTPServer Resource Definition Define an HTTP server in [`httpserver.yaml`](https://github.com/easegress-io/easegress/blob/main/httpserver.yaml): ```yaml apiVersion: easegress.io/v1 kind: HTTPServer metadata: name: hello-http spec: ports: - 8080 pipelines: - hello-pipeline ``` Apply it with `egctl`: ```bash egctl apply -f httpserver.yaml ``` ### Combined Startup with Resources Launch a server and preload resources in one command: ```bash easegress-server \ --config-file config.yaml \ --initial-object-config-files httpserver.yaml,pipeline.yaml ``` This approach, handled in [`cmd/server/main.go`](https://github.com/easegress-io/easegress/blob/main/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`](https://github.com/easegress-io/easegress/blob/main/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`](https://github.com/easegress-io/easegress/blob/main/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`](https://github.com/easegress-io/easegress/blob/main/config.yaml)), resource definition files typically use descriptive names like [`httpserver.yaml`](https://github.com/easegress-io/easegress/blob/main/httpserver.yaml) or [`pipeline.yaml`](https://github.com/easegress-io/easegress/blob/main/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`](https://github.com/easegress-io/easegress/blob/main/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`](https://github.com/easegress-io/easegress/blob/main/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`](https://github.com/easegress-io/easegress/blob/main/pkg/controllers/httpserver/spec.go), while `Pipeline` specifications reside in [`pkg/controllers/pipeline/spec.go`](https://github.com/easegress-io/easegress/blob/main/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.