# Best Practices for Deploying Easegress in Production: A Complete Guide

> Deploy Easegress in production with confidence. Learn best practices for high availability and data durability using persistent volumes, Helm, and robust security and monitoring.

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

---

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

```yaml
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:

```bash
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`](https://github.com/easegress-io/easegress/blob/main/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`](https://github.com/easegress-io/easegress/blob/main/cmd/server.go) processes via the [`pkg/option/option.go`](https://github.com/easegress-io/easegress/blob/main/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:

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