Setting up Home Assistant within a Kubernetes K3s cluster

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:

Home Assistant Container running in K3s

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:

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 10.42.1.0/24
    - 127.0.0.1
    - ::1

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 /etc/hosts file!

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.