Using Let’s Encrypt Wildcards for Micro-services

“person playing with cards” by Sergi Viladesau on Unsplash

Recently, Let’s Encrypt released their wildcard certificates into the, well, wild. We have been breaking our monolith into a cluster of micro-services, and up until this point had been manually applying and updating individual Let’s Encrypt certificates to each service. This quickly became difficult to track, tedious, and time consuming. So we jumped on the wildcards when they arrived.

To generate the wildcard certificates you need to be using a client that is compatible with ACMEv2. The list of these can be found here. We went with Certbot because of the simplicity with which you can renew the certificates.

There are a few things worth noting before we carry on:

• Certbot is not currently available for non-UNIX systems.
• Certbot needs root permissions to write to /etc/letsencrypt, so you’ll need to run most commands with sudo.
• Let’s Encrypt wildcards can only be validated with DNS-01 challenges currently.

On MacOS you can install Certbot with brew:

brew install certbot

and then you can go straight ahead and generate the certificate:

sudo certbot certonly - server https://acme-v02.api.letsencrypt.org/directory \
- manual - preferred-challenges dns -d *.somefancydomain.com

To deconstruct this slightly:

• The certonly option and — manual flag mean Certbot will obtain a new certificate but won’t install it. This is what you want if you are running Certbot on a machine that isn’t the web-server hosting your application or service.
• The — preferred-challenges flag has to be set to dns, due to the limitation on wildcard certificate validation previously mentioned.
• As you can see, the — server value is using the ‘acme-v02’ Let’s Encrypt API, which is also necessary for the wildcards.
• Finally, the -d flag value needs to be the wildcard symbol in front of whatever domain you want the certificate for.

Once you’ve run the command you will need to register an account. You should be aware that the email you register with will be used to send notification emails to, regarding certificates that are about to expire.

After you’ve done this, you should see a message like this:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
Please deploy a DNS TXT record under the name
_acme-challenge.example.comsomefancydomain.com with the following value:
NeiXA1a6dfuDfkC0J_XXXXXXXXXXXXXXXXXXXXXXXXX
Before continuing, verify the record is deployed.
 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Press Enter to Continue

The steps to proceed here will depend on where you have registered the domain.

In our case we are using Route53, so to create this record:

• Select the hosted zone of the domain for which you are adding the wildcard.
• Click the ‘Create Record Set’ button, which should open a side bar on the right side of the screen.
• Copy ‘_acme-challenge’ into the ‘Name’ text box.
• Click the ‘Type’ dropdown and select ‘TXT’
• Copy the value given to you by Certbot, and paste it into the ‘Value’ field.
• Click create.

Once you’ve done this, you’ll need to wait for the DNS record to propagate. One easy way to check whether this is finished is to use dig:

dig -t TXT +short _acme-challenge.somefancydomain.com

You may need to wait a few minutes, but eventually running this command should print the TXT value you copied to the terminal.

If the challenge was successful, you should receive this message:

IMPORTANT NOTES:
 - Congratulations! Your certificate and chain have been saved at:
 /etc/letsencrypt/live/somefancydomain.com/fullchain.pem
 Your key file has been saved at:
 /etc/letsencrypt/live/somefancydomain.com/privkey.pem
 Your cert will expire on 2018–09–06. To obtain a new or tweaked
 version of this certificate in the future, simply run certbot
 again. To non-interactively renew *all* of your certificates, run
 "certbot renew"

NOTE: Although not specified in the Certbot message, there is also a cert.pem file in the directory. But as this is a wildcard certificate, the fullchain.pem will be what you need.

Now the certificate has been issued, the remaining step is to copy this to wherever you are hosting your application or services.

As an example, our micro-services are run on a Kubernetes cluster, and hosted on GCP. The SSL certificates are stored in the Cloud Key Management Service (KMS). The secrets need to be base64 encoded and then copied into a yaml file, which is then encrypted. Therefore, we just need to run:

sudo cat /etc/letsencrypt/live/somefancy.com/fullchain.pem | base64 | pbcopy

…and then paste the value into the file.

If you would like to know more about Cloud KMS and how we use it then check out our post here!

If you like what you read and think you could contribute to our team at Kudos then take a look at our careers page to see what roles we currently have open.