Best Practices for Deploying Easegress in Production: A Complete Guide

Deploy Easegress in production using an odd number of primary nodes (3, 5, or 7) with persistent volumes, Helm for orchestration, and proper TLS, monitoring, and backup strategies to ensure high availability and data durability.

Easegress is a cloud-native traffic orchestration system from the easegress-io/easegress repository that supports both single-node and highly-available cluster deployments. When deploying Easegress in production environments, you must carefully plan the cluster topology, storage persistence, security, and observability to prevent data loss and ensure zero-downtime operations.

Choose the Right Cluster Topology for Production

Easegress clusters consist of two distinct roles that determine how nodes participate in consensus and data storage.

Primary Nodes and the Raft Consensus

Primary nodes run an embedded etcd server and persist the cluster state to disk. According to the configuration documentation in docs/05.Administration/5.1.Config-and-Cluster-Deployment.md, you must deploy an odd number of primary nodes (e.g., 3, 5, or 7) to guarantee a majority for Raft consensus and avoid split-brain scenarios.

Raft requires a majority of votes to elect a leader. With an odd number of primaries, the cluster can survive the loss of up to ⌊N/2⌋ nodes while maintaining quorum. For example, a three-primary cluster tolerates one failure, while a five-primary cluster tolerates two.

Secondary Nodes for Read Scaling

Secondary nodes read and write state through a primary but do not participate in consensus. You can add secondary nodes freely to increase read capacity without affecting high availability. As noted in the cluster deployment guide, secondaries do not require persistent storage since they do not store the Raft log.

Configure Persistent Storage for Primary Nodes

Primary nodes must use durable volumes rather than ephemeral storage to prevent data loss during pod restarts or node failures.

In helm-charts/easegress/values.yaml, set cluster.volumeType to persistentVolume and specify each primary node's hostname under cluster.nodeHostnames. This configuration creates a PersistentVolumeClaim (PVC) per primary, ensuring that etcd data survives container restarts.

cluster:
  primaryReplicas: 3
  volumeType: persistentVolume
  nodeHostnames:
    - node-1
    - node-2
    - node-3

Deploy Easegress Using Helm (Recommended)

The Helm chart abstracts complex command-line flags into declarative configuration and handles PVC creation, service exposure, and RBAC automatically.

To install a production-ready three-primary cluster with persistent storage:

helm install easegress -n easegress ./helm-charts/easegress \
  --set cluster.primaryReplicas=3 \
  --set cluster.volumeType=persistentVolume \
  --set 'cluster.nodeHostnames={node-1,node-2,node-3}'

For single-node testing, omit the replica settings to use defaults. The chart documentation in helm-charts/easegress/README.md provides additional configuration options for ingress controllers and resource limits.

Manage Configuration via Files and Environment Variables

Easegress supports two configuration methods that the entry point in cmd/server.go processes via the pkg/option/option.go definitions.

Configuration files provide reproducibility and version control. When you set the EASEGRESS_CONFIG_FILE environment variable, all command-line flags are ignored in favor of the YAML configuration. A minimal primary node configuration looks like:

name: node-1
cluster-name: prod-cluster
cluster-role: primary
api-addr: 0.0.0.0:31255
data-dir: /opt/easegress/data
log-dir: /opt/easegress/log
cluster:
  listen-peer-urls:
    - http://node-1:2380
  listen-client-urls:
    - http://node-1:2379
  advertise-client-urls:
    - http://node-1:2379
  initial-advertise-peer-urls:
    - http://node-1:2380
  initial-cluster:
    - node-1=http://node-1:2380
    - node-2=http://node-2:2380
    - node-3=http://node-3:2380

Environment variables map one-to-one to flags and suit container orchestration platforms that inject dynamic values or secrets. Prefix configuration keys with EASEGRESS_ and use uppercase with underscores.

Secure Your Easegress Deployment

Production deployments require encrypted communications and automated certificate management.

Enable TLS by setting EASEGRESS_TLS=true and providing certificate and key files via EASEGRESS_CERT_FILE and EASEGRESS_KEY_FILE. The Easegress README documents Let’s Encrypt integration for automatic certificate rotation, eliminating manual renewal tasks.

Implement Observability and Monitoring

Easegress exposes Prometheus-compatible metrics on the admin port (default 31255) defined in service.adminPort. Configure your Prometheus instance to scrape this endpoint for real-time traffic and health metrics.

For log persistence, set log.path in your Helm values to a directory backed by persistent storage. This ensures that logs survive pod restarts and can be ingested by centralized logging systems.

Plan for Rolling Upgrades and Maintenance

Easegress supports zero-downtime upgrades through the EASEGRESS_SIGNAL_UPGRADE mechanism. When you send this signal to the current process, the server starts a new instance, drains ongoing requests, and then exits cleanly.

When using Helm, execute helm upgrade to apply new versions. The chart respects the signal flow and updates pods sequentially to maintain availability during the rollout.

Backup and Disaster Recovery Strategy

Protect your cluster state by regularly snapshotting the PVCs that back primary nodes. These volumes contain the embedded etcd data essential for cluster recovery.

Maintain a copy of the initial cluster definition (EASEGRESS_INITIAL_CLUSTER) used during bootstrap. If all primary nodes fail simultaneously, you can recreate the cluster using this definition and restore from PVC snapshots to minimize Recovery Time Objective (RTO).

Summary

• Deploy an odd number of primary nodes (3, 5, or 7) to maintain Raft consensus and tolerate ⌊N/2⌋ failures.
• Use persistent volumes for primary nodes to prevent data loss; set cluster.volumeType: persistentVolume in Helm.
• Use Helm for production deployments to automate PVC creation, RBAC, and service configuration.
• Enable TLS and consider Let’s Encrypt for automated certificate management.
• Monitor via Prometheus on admin port 31255 and persist logs to durable storage.
• Perform rolling upgrades using EASEGRESS_SIGNAL_UPGRADE or helm upgrade for zero downtime.
• Backup PVC snapshots and preserve the EASEGRESS_INITIAL_CLUSTER definition for disaster recovery.

Frequently Asked Questions

How many primary nodes should I run in a production Easegress cluster?

You should run an odd number of primary nodes—typically 3 for small to medium deployments, or 5 for larger, mission-critical systems. Raft consensus requires a majority quorum, so an odd count ensures the cluster can tolerate ⌊N/2⌋ failures without losing availability. For example, a three-node cluster survives one primary failure, while a five-node cluster survives two.

What is the difference between primary and secondary nodes in Easegress?

Primary nodes run an embedded etcd server, participate in Raft consensus, and persist cluster state to disk. They are essential for data durability and cluster coordination. Secondary nodes act as stateless workers that proxy requests to primaries for state reads and writes; they do not store data or vote in elections. You can scale secondaries horizontally to increase traffic capacity without affecting cluster consensus.

How do I ensure data persistence when deploying Easegress with Helm?

Set cluster.volumeType to persistentVolume and provide a list of node hostnames under cluster.nodeHostnames in your values.yaml. This configuration instructs the Helm chart to create a PersistentVolumeClaim (PVC) for each primary node, mounting durable storage at the data directory. Unlike emptyDir, these volumes survive pod restarts and node rescheduling, protecting your etcd data and traffic configurations.

Can I upgrade Easegress without downtime?

Yes. Easegress supports zero-downtime rolling upgrades via the EASEGRESS_SIGNAL_UPGRADE mechanism. When triggered, the current process spawns a new instance, transfers active connections, and gracefully shuts down after draining ongoing requests. When using Helm, simply run helm upgrade; the chart orchestrates the signal flow and updates pods sequentially to maintain service availability throughout the rollout.

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