# How to Configure Let's Encrypt for Automatic HTTPS Certificates with Easegress > Easily configure Let's Encrypt for automatic HTTPS certificates with Easegress. Learn how Easegress's AutoCertManager handles acquisition, storage, and renewal via ACME challenges. - Repository: [MegaEase/easegress](https://github.com/megaease/easegress) - Tags: how-to-guide - Published: 2026-03-07 --- **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`](https://github.com/megaease/easegress/blob/main/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`](https://github.com/megaease/easegress/blob/main/autocertmanager.go) enforces that **DNS-01 challenges are required for wildcard domains** (`*.example.com`). ```yaml 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: - name: "*.example.com" dnsProvider: name: cloudflare zone: example.com apiToken: ``` ### 2. Apply the AutoCertManager Configuration Use the `egctl` CLI tool to apply the configuration to your Easegress cluster: ```bash egctl apply -f auto-cert.yaml ``` ### 3. Configure HTTPServer to Use Automatic Certificates In [`pkg/object/httpserver/spec.go`](https://github.com/megaease/easegress/blob/main/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. ```yaml name: my-httpserver kind: HTTPServer https: true autoCert: true listen: - address: ":443" ``` ### 4. Apply the HTTPServer Configuration ```bash 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`](https://github.com/megaease/easegress/blob/main/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`](https://github.com/megaease/easegress/blob/main/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`](https://github.com/megaease/easegress/blob/main/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.