How to Secure Communication with Easegress Using TLS: A Complete Guide

To secure communication with Easegress using TLS, configure TLS certificates for the Management API via command-line flags, enable HTTPS with certificate base64 strings or automatic Let's Encrypt for HTTPServer objects, and set useTLS for MQTTProxy objects.

Easegress is a cloud-native traffic orchestration system that handles both administrative and data-plane traffic. Securing communication with Easegress using TLS involves configuring encryption at multiple layers: the management API, HTTP server objects, and MQTT proxy objects. This guide covers each layer with specific configuration examples and source code references from the Easegress repository.

TLS for the Easegress Management API

The management API handles administrative traffic and can be secured using TLS to encrypt HTTP traffic and optionally enforce mutual TLS (mTLS) for client authentication.

Command-Line TLS Configuration

In pkg/option/option.go, the server defines flags for TLS configuration:

opt.flags.BoolVar(&opt.TLS, "tls", false, "Flag to use secure transport protocol(https).")
opt.flags.StringVar(&opt.CertFile, "cert-file", "", "Flag to set the certificate file for https.")
opt.flags.StringVar(&opt.KeyFile,  "key-file",  "", "Flag to set the private key file for https.")
opt.flags.BoolVar(&opt.ClientCAFile, "client-ca-file", "", "File containing client CA certificates for mTLS.")

When --tls is enabled, the server creates a tls.Config using the supplied certificate and key files. If --client-ca-file is provided, the server enables mutual TLS by setting ClientAuth to RequireAndVerifyClientCert.

Example startup command:

./easegress-server \
  --tls \
  --cert-file=/etc/easegress/server.crt \
  --key-file=/etc/easegress/server.key \
  --client-ca-file=/etc/easegress/ca.crt

TLS for HTTPServer Data Plane Traffic

HTTPServer objects handle inbound traffic and support multiple TLS modes: static certificates, automatic Let's Encrypt certificates, and mutual TLS.

Static Certificate Configuration

The HTTPServer specification in pkg/object/httpserver/spec.go defines fields for TLS configuration:

type Spec struct {
    HTTPS      bool   `json:"https" jsonschema:"required"`
    CertBase64 string `json:"certBase64,omitempty"`
    KeyBase64  string `json:"keyBase64,omitempty"`
    Certs      map[string]string `json:"certs,omitempty"`
    Keys       map[string]string `json:"keys,omitempty"`
    // ...
}

The tlsConfig() method (lines 97-164) builds the TLS configuration by loading certificates from base64-encoded strings or domain-specific maps.

Configuration example with static certificates:

kind: HTTPServer
name: my-https-server
spec:
  https: true
  address: 0.0.0.0
  port: 443
  certBase64: <base64-encoded-certificate>
  keyBase64: <base64-encoded-private-key>

Automatic Let's Encrypt Certificates

Easegress supports automatic certificate issuance via ACME TLS-ALPN-01. Enable this by setting autoCert: true:

kind: HTTPServer
name: auto-https
spec:
  https: true
  autoCert: true
  address: 0.0.0.0
  port: 443

When enabled, the GetCertificate callback in pkg/object/autocertmanager/autocertmanager.go handles the ACME flow, either returning cached certificates or initiating the TLS-ALPN-01 challenge.

Mutual TLS for Client Authentication

To enforce client certificate authentication, add caCertBase64 to the HTTPServer spec:

spec:
  https: true
  certBase64: <server-cert>
  keyBase64: <server-key>
  caCertBase64: <base64-ca-cert>  # Requires clients to present valid certs

The tlsConfig() method sets ClientAuth: tls.RequireAndVerifyClientCert and populates ClientCAs when this field is present.

TLS for MQTT Proxy Objects

The MQTT proxy supports TLS encryption for MQTT connections. Configuration is defined in pkg/object/mqttproxy/spec.go:

type Spec struct {
    UseTLS     bool          `json:"useTLS,omitempty"`
    Certificate []Certificate `json:"certificate,omitempty"`
}

type Certificate struct {
    Name string `json:"name"`
    Cert string `json:"cert"`  // PEM encoded
    Key  string `json:"key"`   // PEM encoded
}

The tlsConfig() method (lines 8-22) builds the TLS configuration from the provided certificate list.

Example configuration:

kind: MQTTProxy
name: mqtt-secure
spec:
  port: 8883
  useTLS: true
  certificate:
    - name: default
      cert: |
        -----BEGIN CERTIFICATE-----
        ...
        -----END CERTIFICATE-----
      key: |
        -----BEGIN PRIVATE KEY-----
        ...
        -----END PRIVATE KEY-----

Auto-Certificate Management Architecture

The global auto-cert manager (pkg/object/autocertmanager/autocertmanager.go) handles ACME certificate lifecycle:

1. Initialization: Creates an ACME client and registers with the Let's Encrypt directory
2. Certificate Cache: Stores valid certificates in memory and persistent storage
3. TLS-ALPN-01 Challenge: Handles the ACME protocol handshake during TLS connections
4. Renewal: Automatically renews certificates before expiration

When an HTTPServer specifies autoCert: true, the GetCertificate callback retrieves certificates from this manager rather than static configuration.

Complete Deployment Example

The following configuration demonstrates securing all three layers simultaneously:

# Management API (HTTPS with client-auth)

# Start server with:

# ./easegress-server --tls --cert-file=/etc/easegress/api.crt \

#   --key-file=/etc/easegress/api.key --client-ca-file=/etc/easegress/api-ca.crt

# Public HTTPS with automatic certificates

objects:
  - kind: HTTPServer
    name: public-site
    spec:
      https: true
      autoCert: true
      address: 0.0.0.0
      port: 443
      routerKind: Ordered
      rules:
        - path: /
          backend: my-backend

  # Internal API with mutual TLS

  - kind: HTTPServer
    name: internal-api
    spec:
      https: true
      certBase64: "<base64-encoded-server-cert>"
      keyBase64: "<base64-encoded-server-key>"
      caCertBase64: "<base64-encoded-ca-cert>"
      address: 10.0.0.0/24
      port: 8443
      rules:
        - path: /admin
          backend: admin-service

  # Secure MQTT broker

  - kind: MQTTProxy
    name: mqtt-secure
    spec:
      port: 8883
      useTLS: true
      certificate:
        - name: mqtt-cert
          cert: |
            -----BEGIN CERTIFICATE-----
            MIIDXTCCAkWgAwIBAgIJAKoK/heBjcOuMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV
            ...
            -----END CERTIFICATE-----
          key: |
            -----BEGIN PRIVATE KEY-----
            MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC...
            -----END PRIVATE KEY-----

Deploy this configuration using the Easegress CLI:

easegress create -f config.yaml

Key Source Files Reference

Feature	File	Key Implementation
Management API TLS flags	pkg/option/option.go	TLS, CertFile, KeyFile, ClientCAFile flags
HTTPServer TLS config	pkg/object/httpserver/spec.go	tlsConfig() method (lines 97-164)
HTTPServer runtime	pkg/object/httpserver/runtime.go	TLS listener creation using r.spec.tlsConfig()
Auto-cert manager	pkg/object/autocertmanager/autocertmanager.go	GetCertificate() ACME implementation
MQTTProxy TLS	pkg/object/mqttproxy/spec.go	tlsConfig() method (lines 8-22)
MQTTProxy listener	pkg/object/mqttproxy/broker.go	tls.Listen("tcp", addr, cfg)

Summary

• Management API: Enable TLS using --tls, --cert-file, and --key-file flags when starting easegress-server. Add --client-ca-file to enforce mutual TLS for administrative access.
• HTTPServer: Set https: true in the spec. Provide certificates via certBase64/keyBase64 for static configuration, or enable autoCert: true for automatic Let's Encrypt issuance. Add caCertBase64 to require client certificate authentication.
• MQTTProxy: Set useTLS: true and provide PEM-encoded certificates in the certificate list to encrypt MQTT broker connections.
• Auto-Cert: The global auto-cert manager handles ACME TLS-ALPN-01 challenges, certificate caching, and automatic renewal when autoCert is enabled.

Frequently Asked Questions

How do I enable TLS for the Easegress admin API?

Start the Easegress server with the --tls flag and provide the certificate and key files using --cert-file and --key-file. For mutual TLS, add --client-ca-file pointing to your CA certificate. This encrypts all administrative traffic on the API port and optionally requires client certificates for authentication.

Can Easegress automatically obtain TLS certificates?

Yes. Set autoCert: true in your HTTPServer specification. Easegress will use the auto-cert manager (pkg/object/autocertmanager/autocertmanager.go) to automatically obtain and renew certificates from Let's Encrypt using the ACME TLS-ALPN-01 challenge protocol. No manual certificate management is required.

How do I configure mutual TLS (mTLS) in Easegress?

For the Management API, use the --client-ca-file flag when starting the server. For HTTPServer objects, add the caCertBase64 field containing a base64-encoded CA certificate to the spec. This sets ClientAuth: tls.RequireAndVerifyClientCert in the TLS configuration, requiring clients to present valid certificates signed by the specified CA.

What TLS versions and cipher suites does Easegress support?

Easegress uses the Go standard library's crypto/tls package. By default, it supports TLS 1.2 and TLS 1.3 with secure cipher suites. The specific cipher suites and minimum TLS version can be configured through the Go runtime environment or by modifying the source code in the TLS configuration builders found in pkg/object/httpserver/spec.go and related files.

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