Automatically renewed Let's Encrypt certificates - yes please!

Back in late summer of 2016, we wrote the first version of Kontena and Let's Encrypt integration. The most important step in getting a certificate is called domain verification. It's a process of LE verifying that you actually own and control the domain for which you are requesting a certificate for. Back then, LE only supported two modes of domain verification, either done with special HTTP call to the domain or by setting up special DNS TXT entry for the domain.

We decided to make the first integration with the DNS based verification mode as it's generally more applicable for any service, not just for Kontena Loadbalancer.

Let's Encrypt certificates are valid for only 90 days, which means that one has to renew the certificates every three months or so. Naturally, it would be nice if the platform itself could handle the renewal, but as the domain verification is done using DNS TXT entries, it's practically impossible for the platform to do so. Well, technically doable, but would be lot of maintenance work to integrate to many different DNS providers to manage the related entries.

TLS-SNI-01 verifications

Later on, LE started to support another verification mode called tls-sni-01.

The TLS with Server Name Indication (TLS SNI) validation method proves control over a domain name by requiring the client to configure a TLS server referenced by an A/AAAA record under the domain name to respond to specific connection attempts utilizing the Server Name Indication extension {{!RFC6066}}. The server verifies the client's challenge by accessing the reconfigured server and verifying a particular challenge certificate is presented.

In practice, the server responding to a particular domain name must respond with a specially made certificate to prove that you control the domain.

That we can automate.

For operating Let's Encrypt certificates with Kontena, see the docs for details.

New way to store certificates

During the initial LE integration, we stored the certificates in plain vault secrets. When refactoring the LE integration to support the tls-sni way of challenge verification we decided that certificates require more (meta)data to make the management easier, both for the users and also for the platform itself. Thus we refactored certificates to be resources of their own. They are still stored in the vault securely.

With the new way of handling certificates, the users have better visibility of their certificates:

$ kontena certificate ls
⊛     46 days      true
⊛   73 days      true

This also means that these new certificates are "injected" into services slightly differently:

    image: kontena/lb:latest
      - 443:443
      - subject:
        type: env

As you see, the syntax is pretty similar to the way plain vault secrets are injected into services.


The AUTO_RENEWABLE? flag shows whether or not Kontena Platform can handle the automatic renewal of the certificates. The platform can only renew certificates that have been requested with tls-sni challenge mode. Currently Kontena Platform starts to do the renewal 7 days prior to the certificate expiration. During the renewal Kontena automatically requests new challenge certificate (the special certificate to prove you control the domain), deploys it to the given service (usually Kontena Loadbalancer), requests LE to make the verification and the finally requests the certificate itself. All this is now fully automated and happens in the background. So every three months or so you just see your certificates been automatically renewed. Handy.

Going forward

As with any service, people working with Let's Encrypt are making changes to their services. During January 2018 they are planning to ship out v2 of the ACME API that powers the service. There's no concrete plans for end-of-life for the v1 API so there's no immediate actions planned for Kontena regarding the LE integration. But of course we will refactor the internals to use the v2 API at some point.

Maybe the biggest driver for moving to v2 ACME API is the support for wildcard certificates.

A wildcard certificate can secure any number of subdomains of a base domain (e.g. * This allows administrators to use a single certificate and key pair for a domain and all of its subdomains, which can make HTTPS deployment significantly easier.

Let's Encrypts plan is to support wildcard certificates only with DNS based challenge verification mode. This means that it will be up to the user to renew your certificates once in every three months or so as Kontena will not be able to integrate with every single DNS provider out there. But as many other things in life, there's tradeoffs. Running couple of commands on CLI every three months gets you a wildcard certificate. In my opinion that's not too bad tradeoff to make. :)