How to Configure Let's Encrypt for Automatic HTTPS Certificates with Easegress

Easegress provides a built-in AutoCertManager controller that automatically obtains, stores, and renews TLS certificates from Let's Encrypt by solving ACME challenges via HTTP-01, TLS-ALPN-01, or DNS-01.

Easegress simplifies TLS termination by integrating directly with Let's Encrypt through the AutoCertManager business controller. This guide explains how to configure automatic HTTPS certificates in Easegress using the controller's singleton architecture and ACME challenge resolution capabilities.

Understanding the AutoCertManager Architecture

The AutoCertManager is implemented as a singleton controller in pkg/object/autocertmanager/autocertmanager.go. The init() function registers a validation hook that enforces only one instance can exist per Easegress cluster. This design ensures centralized certificate management and prevents conflicting ACME registrations.

The controller handles the complete certificate lifecycle: initial ACME registration, challenge solving, certificate storage in internal memory, and scheduled renewal. The default renewBefore value is 720h (30 days), meaning certificates are automatically renewed one month before expiration.

Configuring Let's Encrypt Automatic Certificates

1. Define the AutoCertManager Specification

Create a YAML specification that includes your Let's Encrypt registration email, enabled challenge types, and domain configurations. The Spec.Validate method in autocertmanager.go enforces that DNS-01 challenges are required for wildcard domains (*.example.com).

name: autocert
kind: AutoCertManager
email: admin@example.com
directoryURL: https://acme-v02.api.letsencrypt.org/directory
renewBefore: 720h
enableHTTP01: true
enableTLSALPN01: false
enableDNS01: true
domains:
  - name: api.example.com
    dnsProvider:
      name: cloudflare
      zone: example.com
      apiToken: <your-cloudflare-api-token>
  - name: "*.example.com"
    dnsProvider:
      name: cloudflare
      zone: example.com
      apiToken: <your-cloudflare-api-token>

2. Apply the AutoCertManager Configuration

Use the egctl CLI tool to apply the configuration to your Easegress cluster:

egctl apply -f auto-cert.yaml

3. Configure HTTPServer to Use Automatic Certificates

In pkg/object/httpserver/spec.go, the HTTPServer specification supports the autoCert boolean field. When set to true, the server injects a GetCertificate callback into its TLS configuration that queries the global AutoCertManager for certificates during the TLS handshake.

name: my-httpserver
kind: HTTPServer
https: true
autoCert: true
listen:
  - address: ":443"

4. Apply the HTTPServer Configuration

egctl apply -f httpserver.yaml

How Certificate Renewal and Handshake Handling Work

Once configured, the AutoCertManager runs a background goroutine that periodically checks certificate expiry against the renewBefore threshold. When a certificate approaches expiration, the controller automatically initiates a new ACME order and replaces the stored certificate.

During TLS handshakes, the HTTPServer's TLS configuration invokes AutoCertManager.GetCertificate. This method either returns the cached certificate for the requested domain or, if tokenOnly is enabled, returns a temporary self-signed token for TLS-ALPN-01 challenge solving. The controller also exposes HTTP endpoints via HandleHTTP01Challenge to respond to HTTP-01 validation requests.

Summary

• Easegress uses a singleton AutoCertManager controller to handle Let's Encrypt certificate lifecycle, enforced in pkg/object/autocertmanager/autocertmanager.go.
• Configuration requires your email, at least one enabled challenge type (HTTP-01, TLS-ALPN-01, or DNS-01), and domain specifications with DNS provider details for wildcard domains.
• HTTPServer integration requires setting autoCert: true and https: true to enable automatic certificate retrieval during TLS handshakes.
• Renewal is automatic with a default 30-day (720h) renewal window, requiring no manual intervention.

Frequently Asked Questions

Can I use multiple AutoCertManager instances in one Easegress cluster?

No. The AutoCertManager is designed as a singleton controller. The init() function in pkg/object/autocertmanager/autocertmanager.go registers a validation hook that explicitly prevents creating more than one instance, ensuring centralized certificate management and avoiding conflicting ACME registrations.

Why is my wildcard domain certificate request failing?

Wildcard domains (*.example.com) require the DNS-01 challenge type. The Spec.Validate method in autocertmanager.go enforces that DNS-01 is enabled and configured with a valid DNS provider when wildcard domains are specified. HTTP-01 and TLS-ALPN-01 challenges cannot validate wildcard certificates.

How do I know when my certificates will be renewed?

The AutoCertManager uses the renewBefore parameter (default 720h or 30 days) to determine when to initiate renewal. The controller periodically checks certificate expiry in a background goroutine. You can monitor renewal activity through Easegress logs or by checking the certificate expiry dates on your HTTPS endpoints.

Can I use AutoCertManager with custom ACME servers other than Let's Encrypt?

Yes. The directoryURL field in the AutoCertManager specification allows you to specify any ACME v2 compatible directory endpoint. While it defaults to https://acme-v02.api.letsencrypt.org/directory, you can configure it to use staging environments, private ACME servers, or other public CAs that support the ACME protocol.

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