Free SSL for Every Environment: How the Let's Encrypt Add-On Issues, Installs and Renews Certificates on PaaS

Certificates used to expire at the worst moment because a human forgot. Let's Encrypt fixed the cost and the automation, but on a platform with dozens of environments someone still has to make the automation happen everywhere, consistently. This post is a platform administrator's explanation of the Let's Encrypt add-on on MassiveGRID PaaS, which is built on Virtuozzo Application Platform, formerly Jelastic: what it does, how, and the handful of ways it can go wrong.

The administrator manages about forty environments for a digital agency we will call Sable Row, each with a client's custom domain. The Let's Encrypt Free SSL add-on installs a certificate management agent on a load balancer or application server layer, requests certificates for the domains you list, applies them to the stack's SSL configuration and renews them on a schedule.

Where it installs

The add-on installs directly on the layers that terminate TLS: load balancers (NGINX, Apache, HAProxy, Varnish), Java servers (Tomcat, TomEE, GlassFish, Payara, Jetty), PHP servers (Apache PHP, NGINX PHP) and Ruby servers. For other stacks, including custom Docker containers and Node.js in most layouts, you put a load balancer in front and install the add-on there, which in clustered topologies is where TLS terminates anyway. The administrator's rule for the agency is that every production environment has an NGINX balancer layer, and the add-on lives on it, so the procedure is identical across forty environments regardless of what runs behind.

What happens at install

You give the add-on the domain names. It downloads and configures the certificate management agent, requests a certificate from Let's Encrypt, installs the certificate and key into the stack's SSL configuration, enables HTTPS, optionally redirects HTTP to HTTPS, and adds a scheduled job that renews the certificate before expiry. The whole sequence typically takes a few minutes. The one prerequisite is DNS: the domain's A record (or CNAME) must already point at the environment's entry point, because Let's Encrypt is going to check.

How validation works behind the scenes

Let's Encrypt validates that you control a domain with the HTTP challenge: it fetches a token from the domain on port 80. The add-on handles this without you opening anything permanently. During validation, incoming HTTP traffic to the environment's entry point is routed internally to a port where the agent's proxy is listening, using temporary DNAT rules; if the layer has several nodes, traffic is also routed to the master node where the agent runs. Once ownership is confirmed the temporary rules are removed. The agent generates the key pair, receives the certificate, and propagates it to every node in the layer through the platform API, so a scaled balancer or application layer gets the same certificate on every node, and nodes added later by scaling receive it too.

Renewal, which is the point

Let's Encrypt certificates are valid for 90 days. The add-on's scheduled task attempts renewal well before expiry, and when it succeeds the web server is reloaded gracefully, without dropping connections, in the same way the platform's NGINX safe-reload works. The agency has run forty environments for two years with no expiry, and the administrator's monitoring is external: a certificate-expiry check from a monitoring service against every domain, set to alert at 20 days, which has never fired. The add-on also emails on renewal problems, which brings us to the failures.

The four ways it fails

1. DNS does not point at the entry point. The most common. The challenge cannot reach the environment. Fix DNS, wait for propagation, run the add-on's update action.
2. A CDN or proxy sits in front. If a CDN proxies the domain, the HTTP challenge hits the CDN, not the environment. Either use the DNS challenge (below), disable proxying during issuance, or terminate TLS at the CDN and use the platform's built-in certificate for the origin.
3. Rate limits. Let's Encrypt limits certificates per registered domain per week. An agency testing many subdomains of one client domain can hit it; the administrator issues one certificate covering several subdomains rather than one per subdomain, or uses a wildcard.
4. The entry point changed. Moving from the shared load balancer to a public IP, or vice versa, changes where the domain must point. Update DNS first, then re-run the add-on.

Wildcards and the DNS challenge

For *.client.example the HTTP challenge is not enough; Let's Encrypt requires the DNS challenge, proving control by publishing a TXT record. The add-on supports it: you add the record it gives you at your DNS provider, and the certificate covers every subdomain. Renewal of a wildcard also uses DNS, so for automated renewal the DNS provider needs to be one the agent can update through an API, or the administrator renews the TXT record when the add-on's notice arrives. Sable Row uses wildcards for two clients with dozens of microsites and plain multi-domain certificates for everyone else.

Where this leaves the purchased certificate

It has a place. Organisation-validated and extended-validation certificates, which Let's Encrypt does not issue, still matter to some clients' compliance teams, and MassiveGRID sells commercial certificates that can be uploaded to a layer as a custom certificate. For the ordinary case of a website that needs to be HTTPS and stay HTTPS, the administrator's two years of zero expiries across forty domains is the argument for the add-on.

Frequently Asked Questions

Does the add-on work without a public IP, on the shared load balancer?

Yes. The environment's entry point can be the shared load balancer, and the domain is bound to the environment with a CNAME or A record per the custom domains guide. The challenge is routed to the environment as described. A public IP is needed for some other features, but not for Let's Encrypt.

What happens to the certificate when I scale the layer?

The agent runs on the master node and propagates the certificate to every node in the layer via the platform API, and new nodes added by horizontal scaling receive it automatically. You do not reissue anything.

Can I add a domain later?

Yes. Edit the add-on's domain list and run its update action; it requests a new certificate covering the full list and installs it. Make sure the new domain's DNS already points at the environment first.