Setting up Home Assistant within a Kubernetes K3s cluster
January 01, 2024
I have recently set up a 2 node K3s cluster on 2 Raspberry Pi’s at home in order to self host a few side projects. One popular thing to self host is Home Assistant - an open source home automation tool. Home Assistant is an alternative to tools like Apple HomeKit or Ring, both of which limit the control over what devices and software can be used to control your smart home.
The recommended way to manage Home Assistant on a Raspberry Pi is to use the Home Assistant OS, and while this is an incredibly easy way to managed HA, it means dedicating a Raspberry Pi. Considering HA isn’t that resource intensive I feel it’s a bit of a waste, especially when I’m already self hosting other applications.
This post will show how I integrated Home Assistant into my K3s cluster so it’s accessible on my home network.
Drawbacks of running Home Assistant in K3s
Running HA within K3s is done by installing using the Docker image, and running HA within a container. A detailed list of features that are included with each installation method is here:
From my experience, the biggest drawback of using a container for HA is that “Add-ons” are not included. An Add-on is an easy way to integrate third party services that work alongside HA to extend it’s functionality. There are thousands of Add-ons such as Dynamic DNS tools, databases, and other specific home automation tools like Zigbee2MQTT which allows HA to integrate Zigbee devices (more on that in the next post).
Even though we don’t get the official Add-on functionality in Home Assistant, we are able to integrate these tools manually in K3s.
Benefits of running Home Assistant in K3s
On the other side, running within K3s I think is a great option, as it means you get to organise everything HA related alongside existing projects. If you have K3s set up already, you’ll likely already have your own way to manage inter-pod communication and the ability to allow external traffic to the cluster using a LoadBalancer or Ingress solution.
You also get to keep using the Pi’s for other things, which is the best part in my opinion.
Installing Home Assistant
Here’s the repo I’ll be referencing for the rest of this post:
This shows how my HA is set up. I have stripped out all of my Helm config so it’s easier to read. Running a simple
kubectl apply -f ./ should get it up and running.
The remainder of this post will show a few issues I encountered, and how I approached them.
Selecting the correct image - don’t use the Raspberry Pi image
I initially used the Raspberry Pi Home Assistant image which seemed like the best thing to do at the time. This installed fine, but starting behaving unexpectedly when I started adding my Zigbee devices. For example, I wouldn’t get options to control my Philips Hue bulbs on/off state or brightness when integrated using MQTT, even though I was able to control them fine in Zigbee2MQTT integration.
I later found this was because the Raspberry Pi image had not been updated since June 2023, and the primary image should be used, which is the main Home Assistant image.
Reverse proxy error
As we’re running HA in a Kubernetes cluster, we need to manage what services can be accessed. We want to access Home Assistant from outside the cluster because we open the dashboard in a browser. My setup means running incoming traffic through a LoadBalancer and ingress, which shows an error - “A request from a reverse proxy was received… but your HTTP integration is not set-up for reverse proxies”:
In my case the reverse proxy is from my Traefik ingress running on IP
10.42.1.27, which is being blocked by HA by default. The config for HA can be updated to allow connections, so shell into the HA pod and edit the config file which can be found at
/config/configuration.yaml. Here you can add the trusted proxies:
I have added the localhost IP and also the IP addresses of relevant pods within my K8s cluster. Note from the k3s config files earlier that the
/config directory is mounted to a persistent volume, so changes to the
configuration.yaml will persist across pod and host machine restarts.
Be sure to restart pod or service in order for config file changes to take effect.
One could use a ConfigMap to achieve a more permanent solution for the above.
Testing Home Assistant is working
You’ll then be able to log in to the dashboard. My ingress configures incoming host of
http://homeassistant.local to route to our HA service. Be sure to add this host to your machine’s
Hitting that URL should open the HA login screen. From here you can have a browse and see what HA has detected on your local network. This may be things like an existing Philips Hue Hub, a Plex server, or a smart TV.
At this point it will be worth configuring something small to test, and then rebooting your host machine to ensure everything still runs as it should after the reboot. Better get that nailed down before adding the more complex stuff and trying to figure out any persistence problems.
Adding additional integrations
Now everything is working at a basic level, it’s time to do the fun stuff! As this is a K3s installation, add-ons can’t be used in the same way as the traditional HA OS installation. One of the most powerful parts of Home Assistant is being able to link Zigbee and Z-wave devices. Doing so means you can purchase much cheaper hardware like sensors, bulbs etc. rather than overpriced hardware stuck to a specific vendor.
The next post will cover how I integrated Zigbee2MQTT to Home Assistant.
Senior Engineer at Haven