Anyone done certificate management on running services knows it can be a pain in the behind. Not to mention that certificates are actually pretty expensive. The first problem user typically hits is to select a trusted certificate provider. There are so many of them with varying prices and features. After you've selected a provider to use and got the actual certificate your next problem will be how to provision the certificate to be used by your services. Gets pretty complex really fast if you're running more than a couple services. Oh, and not to mention when things are running in containers. Where would you put your certificates. Certainly it's not a good idea to bake it in the image. Mounting them from the host also can get cumbersome especially if you are planning to have even a hint of dynamic scaling or such. How would you easily change or revoke your certificates when they are going to expire or have been compromised. Certificate management is a tricky business. :)

Luckily the certificate game is going through some big changes as Let's Encrypt (LE) got into the playing field. It's a completely free and open certificate authority with good APIs and tools for automating the whole certificate management process.

As we have had to do the certificate management ourselves in the past, we thought Let's Encrypt support as a "must have" feature in Kontena.

Use Cases

The Kontena Load Balancer can already do SSL termination. So naturally we want to build something that can easily integrate with that. But certificates can be used by any service, so we need to have the support build in such way that any given service deployed in Kontena platform can make use of them.

Luckily, or rather intentionally, we already have a common and secure way of handling any application secrets, the Kontena Vault.

The Process

Let's Encrypt supports two types of flows getting valid certificates. First option is to validate ownership of given domain name by letting LE to make a special request to the domain. Something, usually an acme client, should respond to the query and thus validating that you really own the domain.

The other option is to use something called DNS verification. You can make a request for a new certificate and LE creates a challenge for you. You must then create a special sub-domain TXT DNS record to verify that you control the given domain. So let's assume you want to get certificate for domain You have to create following DNS as the challenge "response":

Record type:TXT
Record content:5m1FCaNvneLduTN4AcPqAbyuQhBQA4ESsar2AQfEYvXIE

Naturally the challenge content is something the LE will generate for each request for the certificate.

Kontena Integration

We've integrated the LE certificate management with Kontena Vault using the DNS challenge flow. That's really the only option as we want to have the certificates commonly usable with any service.

To be able to use Let's Encrypt one must register a client first:

$ kontena certificate register

The email is used by LE to notify about expiring certificates so it should be something that you actually follow.

The process to get the certificate is pretty simple. First you create the domain authorization:

$ kontena certificate authorize
Record name:_acme-challenge
Record type:TXT
Record content:5m1FCaNvneLduTN4AcPqAbyuQhBQA4ESisAQfEYvXIE

Create the needed DNS record in your DNS management system controlling your domain. After that you are ready to get the actual certificate.

$ kontena certificate get --secret-name SSL_CERT_LE_TEST

Kontena calls the LE APIs to get the DNS record verified and a valid certificate issued. For each certificate, three items are stored in the Vault:

  • LE_CERTIFICATE_<domain>_PRIVATE_KEY: The private key for the cert
  • LE_CERTIFICATE_<domain>_CERTIFICATE: The actual server certificate
  • LE_CERTIFICATE_<domain>_BUNDLE: Ready to use bundle of private key and certificate

You can read more detailed documentation on Kontena LE certificate integration here: Kontena certificate management

Using The Certificates

As certificates are stored as any other secret in Kontena Vault you can use them for any service you deploy. For example to use the LE certificate for SSL termination in Kontena LB you can use following example:

  image: kontena/lb:latest
    - 80:80

  image: nginx:latest
    - KONTENA_LB_MODE=http
    - KONTENA_LB_BALANCE=roundrobin
    - internet_lb
    - secret: LE_CERTIFICATE_www.kontena.io_BUNDLE
      name: SSL_CERTS
      type: env

Remember to use the bundled secret as the certificate in LB as HAProxy expects to have the certificate file properly formatted with both private key and the server certificate.

See load balancer config details at

Certificate Expiration

If you've provided a working email in the registration step you will get notifications when your certificates are about to expire. To update a certificate just issue new request for the certificate. No need to do the verification step. When Kontena notices that secrets, in this case the certificate, is updated it automatically updates the service. Including the loadbalancer.

We are planning to add support for Kontena itself also monitoring the certificate expiration and automatic renewal without any user interaction.


Having a free and fully automated certificate authority really brings benefits for all. And as we've integrated it fully into our stack we really empower any service to easily utilize LE issued certificates. The LE support landed in 0.15.0 release of Kontena so it's rather new functionality. Thus it would be great to hear any feedback on its usage.

This is another example of our main goal: Maximise developer happiness, no need to buy expensive certificates and fully integrated and automated certificate management solution for all your services.

About Kontena

Kontena, Inc. is the creator of Kontena, an open source, developer-friendly container and microservices platform. Kontena is built to maximize developer happiness by simplifying running containerized applications on any infrastructure: on-premises, cloud or hybrid. It provides a complete solution for organizations of any size. Founded in March 2015, Kontena was recognized as one of the best new open source projects in the 8th annual Black Duck Open Source Rookies of the Year Awards. For more information, visit:

Image credits: Chains by LEEROY Agency