This guide (with commentary) is meant to provide one way to manually configure automatic renewal (with a later automatic HA restart, as necessary) of your Let’s Encrypt certificate via the HAOS GUI after initial configuration has been completed. This guide is fairly complicated and may seem daunting, but completing it could teach you multiple new functions that could also be useful in other automations. Parts of this guide are based on my memory, because I did not document things early in the process and wanted to test before publishing. I will also include some commentary on things that won’t work for educational purposes. It should be noted that you can also simply schedule an automation to start the Let’s Encrypt service daily and renewal will occur automatically once the due date is near enough (an automatic HA restart wouldn’t occur in that case). In preparing this guide, it has also come to my attention that a blueprint is available should you prefer to import one of those instead of setting up your own system manually. I have not used the blueprint, but based on a quick glance, it looks like it would provide sliders and toggles to configure renewal to your preferences. However, the blueprint appears to be designed for HASSIO, so I’m not sure if it would even install or function properly in HAOS.
Tracking Cert Expiry
In order to schedule renewal, you need to know when expiration will occur. The Certificate Expiry integration is a great tool to help you meet that requirement. If I remember correctly, the steps to use it are intuitive, simply add it from the Integrations section and follow the on-screen prompts to select your LE cert in order to create a sensor showing when said cert will expire. I didn’t take notes on this process, so if you want more detail, see the Manual configuration steps section of the integration page linked earlier in this paragraph.
In order to complete this guide, you will need the entity ID for the sensor you just created. It will likely be something like sensor.cert_expiry_timestamp_yourdomain_tld_8123 and you can find it from the Integrations section by clicking/tapping 1 entity and then clicking/tapping the entity that is displayed to bring up a window showing the full ID. Save this ID for later.
Automating Renewal
Automations can trigger based on a timestamp, but it is advisable to renew before expiry. In fact, Let’s Encrypt recommends renewing when one third of the cert’s lifetime remains. Certs currently last 90 days, so renewing with 30 days remaining follows this recommendation. I chose to use a datetime helper to achieve this, as that seemed most efficient vs other methods (that are arguably efficient enough). Here are the steps:
-
Navigate: Settings → Devices & Services → Helpers
-
Click/tap + CREATE HELPER
-
Choose Date and/or time
-
Provide a name such as “Next Cert Renewal”
-
Optionally, choose an icon such as “mdi:certificate”
-
Choose the “Date and time” option under “What do you want to input?”
-
Click/tap Create
Helpers don’t maintain their values after power failures or full system reboots (vs HA restarts), and these values also need updated after renewals anyway, so I used automations to maintain these values. I originally configured the automations to trigger at HomeAssistant start, and this worked whenever a full system reboot occurred, but I noticed in final testing that the values weren’t updating after HA restarts because the sensor wasn’t available when the automations ran. As such, I changed the automations to run with a state trigger that, based on entity history in my HAOS instance, should theoretically only trigger on reboot. That having been said, here are the steps to create the automation for populating the helper created above:
-
Navigate: Settings → Automations & Scenes
-
Click/tap + CREATE AUTOMATION
-
Click/tap Start with an empty automation
-
Click/tap + ADD TRIGGER
-
Click/tap State
-
Choose the sensor you created to track cert expiry as the entity
-
Choose “Unavailable” in the “From (optional)” dropdown so this automation will only trigger when the state of the sensor changes from unavailable (this happen shortly after each HA restart)
-
Click/tap + ADD ACTION
-
Click/tap Call Service
-
Find and choose “Input datetime: Set”
-
Click/tap + Choose Entity
-
Select the helper you created in steps 2-7
-
Click/tap the three dots in the top right corner and switch to “Edit in YAML”
-
Replace
data: {}withdata_template: -
Remove
target: -
Now you need to refer to the ID that I told you to save for later when adding the Cert Expiry integration. Replace
sensor.cert_expiry_timestamp_yourdomain_tld_8123with that ID to add a new indented line at the bottom liketimestamp: "{{as_timestamp(states('sensor.cert_expiry_timestamp_yourdomain_tld_8123'))-(30*24*60*60)}}"
This last line sets your helper to 30 days before expiration by subtracting 30 days worth of seconds from the expiration time using multiplication to calculate the seconds as 30(days)*24(hours/day)*60(minutes/hour)*60(seconds/minute). You could also replace -(30*24*60*60) with -2592000 to increase efficiency further. You should now have YAML that looks like this for your “Input datetime: Set” action:
service: input_datetime.set_datetime
data_template:
entity_id: input_datetime.next_cert_renewal
timestamp: "{{as_timestamp(states('sensor.cert_expiry_timestamp_yourdomain_tld_8123'))-(30*24*60*60)}}"
It will look different if you come back later after saving, but that is OK.
-
Click/tap SAVE
-
Provide a name for your automation such as “Schedule cert renewal”
Now we have the time when we want to renew, but we still need to automate renewal. Here are the steps necessary to do that:
-
Repeat steps 8-11
-
Click/tap Time
-
Choose “Value of a date/time helper” for the “Mode”
-
Select the helper you created in steps 2-7
-
Repeat steps 15-16
-
Find and choose Home Assistant Supervisor: Start add-on"
-
Choose the “Let’s Encrypt” add-on in the “Add-on” dropdown.
-
Click/tap SAVE
-
Provide a name for your automation such as “Let’s Encrypt Cert Renewal”
Congratulations, your cert should now automatically renew 30 days before it expires. However, when it renews, your HA instance will still be using the old cert until it is restarted. Given 30 days, there is probably a good chance your instance will be restarted for one reason or another before the cert expires anyway, but if you believe having an expired cert would cause you more grief than having an automated restart, you can schedule a restart to occur when the cert expires.
Automating HA Restart
This optional step is very similar to the steps just performed, and because the helpers will be reset each time HA restarts, this automation will only ever be triggered if your HA instance is still up and running when a previously renewed cert expires. When I was designing this solution for my HAOS instance, I was under the impression that the sensor created with the Certificate Expiry integration would update when the certificate renewed, but that doesn’t appear to be the case. As such, it may be possible to use the actual sensor from the Certificate Expiry integration to trigger an automation at expiration, which would negate negate the need for an additional helper and reduce the number of additional automations to 1, but I wasn’t able to quickly find a way to do that while compiling this guide, so I am using another datetime helper here. Even if the sensor could be used, a helper might be more efficient (since the sensor would presumably involve HA processing a template far more frequently than the sensor is set via automation, even as processing that template would arguably be efficient enough). Since the process for scheduling the restart is nearly identical under these circumstances, I am only providing the steps that are different. You can refer to the previous set of steps for each number that isn’t listed here:
-
Provide a name such as “Active Cert Expiration”
-
Now you need to refer to the ID that I told you to save for later when adding the Cert Expiry integration. Replace
sensor.cert_expiry_timestamp_yourdomain_tld_8123with that ID to add a new indented line at the bottom liketimestamp: "{{as_timestamp(states('sensor.cert_expiry_timestamp_yourdomain_tld_8123'))}}"
This last line sets your helper to match the sensor. You should now have YAML that looks like this for your “Input datetime: Set” action:
service: input_datetime.set_datetime
data_template:
entity_id: input_datetime.next_cert_renewal
timestamp: "{{as_timestamp(states('sensor.cert_expiry_timestamp_yourdomain_tld_8123'))}}"
- Provide a name for your automation such as “Record Active Cert Expiration”
Now we have the time when we want to renew, but we still need to automate renewal. Here are the steps necessary to do that:
-
Find and choose “Home Assistant Core Integration: Restart”
-
Click/tap SAVE
-
Provide a name for your automation such as “Reload @ Active Cert Expiry”
Congratulations, your HA instance will now restart when the cert in memory expires. In the future, it may not be necessary to restart HA, as the only component that really needs restarted is the web server, but when I started working on this, there wasn’t an obvious way to restart the web server, and restarting HA was effective, so that’s what I’ve chosen to do. Also note that there is currently no “error handling” here. I didn’t bother with “error handling” because Let’s Encrypt will automatically e-mail me when my cert hasn’t been renewed (I gave it a real e-mail address and didn’t test my automations until after the e-mail came through). However, if you are concerned that you might not get such a notification, the simpler option of running the Let’s Encrypt service once a day may be a better choice for ensuring renewal does occur in the unlikely event that your HA system or Internet connection is down or the Let’s Encrypt system is malfunctioning at the time of the scheduled renewal. Even then, you could still use these same steps to schedule a restart at expiration if you wanted to. On the other hand, if you’ve made it this far and understand what you’ve achieved, you may well be able to mitigate that on your own in a number of ways. For instance, here are two theoretical options:
-
Add a trigger to the renewal automation against the sensor changing from unavailable and add a condition that the helper must match the current time or be in the past. This would make sure that the cert renews if HA was down when the target time passed, but it wouldn’t handle a situation where renewal failed (Internet down, Let’s Encrypt malfunction).
-
Add a notification automation that triggers a number of days before the old cert expires to give yourself time to manually reboot and verify renewal occurred.
-
Adjust the reboot schedule automation to trigger ahead of expiry so that it can work in tandem with the options above to trigger renewal again and/or allow you to check based on a notification.
I’m sure there are plenty of other possibilities, and each one of them can potentially help in other actual home automation tasks, so I’d recommend figuring out what’s right for you.