Automatic Certificates for Openshift Routes
It will manage all
routes with (by default)
butter.sh/letsencrypt-managed=yes labels in the project/namespace, it's deployed in.
Certificates will be stored in secrets starting with
For now, there are the following limitations.
- It only supports domain names of length smaller than 64 characters.
- It only implements
http-01-type verification, better known as "Well-Known".
- Multiple domains per certificate are not supported. See issue #1.
- It will not create the letsencrypt account.
It needs to be created before deploying.
See Section Installation below.
- It doesn't work cross-namespace. See issue #4.
The following env variables can be used.
LETSENCRYPT_ROUTE_SELECTOR(optional, defaults to
butter.sh/letsencrypt-managed=yes), to filter the routes to use;
LETSENCRYPT_RENEW_BEFORE_DAYS(optional, defaults to
30), renew this number of days before the certificate is about to expire;
LETSENCRYPT_CONTACT_EMAIL(required for account generation), the email that will be used by the ACME CA;
LETSENCRYPT_CA(optional, defaults to
LETSENCRYPT_KEYTYPE(optional, defaults to
rsa), the key algorithm to use;
LETSENCRYPT_KEYSIZE(optional, defaults to
4096), the size in bit for the private keys (if applicable);
The ACME key is stored in
The pod consists of three containers, each doing exactly one thing.
They share the filesystem
/var/www/acme-challenge to store the challenges.
watches routes and either generates a new certificate or set the already generated certificate.
periodically checks whether the certificates need to be regenerated.
When Kubernetes cron jobs are implemented, this will move outside the pod.
.well-known/acme-challengewhen asking to sign the certificate.
Create the template as usual.
> oc create -f template.yaml
Instanciate the template.
> oc new-app --template=letsencrypt -p LETSENCRYPT_CONTACT_EMAILfirstname.lastname@example.org
The "letsencrypt" service account needs to be able to manage its secrets and manage routes.
For now, the admin role can be used, but that should be tightened considerably.
> oc policy add-role-to-user edit system:serviceaccount:letsencrypt:default
Let's encrypt credentials
Given an account-key (from running dehydrated or any other tool), create a secret as follows.
> oc secrets new letsencrypt-creds account-key=/path/to/account-key.pem
In the future that part should be done by the container itself.
It is necessary to pin at least one key to use for disaster recovery, outside the cluster!
n keys and pin all of them.
On key rollover, delete the previous key, use the oldest of the remaining keys to sign the certificate, generate a new key and pin the new keys.
That way, the pin can stay valid for
(n-1)* lifetime of a key.
That is, if no key gets compromised!
Should be done with
/var/lib/letsencrypt-container/$DOMAINNAME, whenever a certificate is to be touched.