Home Assistant helm chart

Who doesn't need more home assistant helm charts? This is a home assistant chart with some quality of life features.

Features

• values are documented here using helm-docs
• Put a default configuration.yaml, themes.yaml, automations.yaml, and scenes.yaml in a place of your choosing with either:
  • your own ConfigMap
  • specifying an in-line yaml string for us to render as a ConfigMap for you
• 🆕 Create an initial "owner" admin user (disables the registration page)
  • supports existing k8s Secret for credentials
• 🆕 post install job to setup hacs
• Kept up to date by RenovateBot

TLDR

# add the chart repo to your helm repos
helm repo add codeberg.org https://codeberg.org/api/packages/open-engineering/helm
helm repo update
# download the values.yaml and edit it with your own values such as YOUR hostname
helm show values codeberg.org/home-assistant > values.yaml
# install the chart
helm install --namespace home-assistant --create-namespace codeberg.org/home-assistant --values values.yaml

• Tips
  • Creating an initial owner user
    • User creation using an existing secret
    • Troubleshooting User creation
  • Setup hacs
  • Unit system, Temp Unit, and Time Zone
  • Making Ingress Nginx work for public domains
  • Using an existing ConfigMap for configuration.yaml
  • USB Devices
    • Values.yaml
  • Bluetooth devices
  • Mobile config
• Status

Tips

Creating an initial owner user

Creating a user using plain text values. This would be your values:

homeAssistant:owner:# -- whether to create an initial owner user to disable registrationcreate:true# -- enable debug mode for the user creation job. WARNING: This reveals secret datadebug:false# -- name of the owner user, ignored if owner.existingSecret is setname:"admin"# -- login username of the owner user, ignored if owner.existingSecret is setusername:"admin"# -- login password of the owner user, ignored if owner.existingSecret is setpassword:""# -- language of the owner user, ignored if owner.existingSecret is setlanguage:"en"# -- if your home assistant is using ingress, this is the external url you connect to# NOTE: if using ingress, this should be the same hostname you specified for that# if using an internal IP for connecting, please use your IP for the url, like https://192.168.42.42/externalURL:"https://home-assistant.cooldogsonline.net/"

NOTE: for user creation to work successfully, you need to have a configuration.yaml file in place with all the basic info filled out. For more basic config defaults, see: home-assistant.io/docs/configuration/basic

User creation using an existing secret

This would be your values:

homeAssistant:owner:create:trueexistingSecret:"home-assistant-owner"

This would be an example secret containing the important environment variables:

apiVersion:v1kind:Secretmetadata:name:home-assistant-owner# this should be the namespace you deploy this helm chart intonamespace:home-assistanttype:Opaquedata:ADMIN_LANGUAGE:ZW4=ADMIN_NAME:YWRtaW4=ADMIN_PASSWORD:YWRtaW4=ADMIN_USERNAME:YWRtaW4=EXTERNAL_URL:aHR0cHM6Ly9oYS5leGFtcGxlLmNvbS8=

Troubleshooting User creation

Sometimes, the user creation job is buggy, as it is a hack anyway, so we take a DEBUG variable to output everything we get back from every command. If something has gone wrong, try deleting the helm release and then re-install with the following values:

homeAssistant:owner:create:true# -- enable debug mode for the user creation job. WARNING: This reveals secret datadebug:true

⚠️ WARNING: Enabling the debug variable for the user creation job will print sensitive data including authorization codes and bearer tokens!

Setup hacs

We provide a post install hook job to setup hacs for you. You can enable it like this:

# persistence MUST be enabled to do thispersistence:# set to your preferred storageClass, this examples sets# storageClass to local-path which is default on k3sstorageClass:"local-path"enabled:truehomeAssistant:setupHacsJobs:enabled:true

Unit system, Temp Unit, and Time Zone

homeAssistant:configuration:| homeassistant:
 time_zone: Europe/Amsterdam
 temperature_unit: C
 unit_system: metric

For more basic config defaults, see: home-assistant.io/docs/configuration/basic

Making Ingress Nginx work for public domains

I had to add the IP range of the k8s cluster to my trusted proxies in my home assistant configuration.yaml (also since this was public, I needed to declare an external_url). This is what I added to my values.yaml to do that through this chart:

homeAssistant:configuration:| # this sets your extenral url
 homeassistant:
 external_url: 'https://iot.examplesforgooddogs.com'
 # this enables proxies such as the ingress nginx controller
 http:
 use_x_forwarded_for: true
 trusted_proxies:
 - 10.0.0.0/8

Using an existing ConfigMap for configuration.yaml

For the ConfigMap, make sure your ConfigMap has a key called configuration.yaml with in-line yaml data like this:

apiVersion:v1kind:ConfigMapmetadata:name:my-home-assistant-configmapnamespace:home-assistantdata:configuration.yaml:| http:
 trusted_proxies:
 - 10.0.0.0/8
 use_x_forwarded_for: true

Then, you'd specify the name of your ConfigMap in your values.yaml like this:

homeAssistant:existingConfigMap:"my-home-assistant-configmap"

USB Devices

If you're on metal, make sure your device is accessible, which in the case of a USB device e.g. conbee II, will require you to install the generic device plugin:

kubectl apply -f https://raw.githubusercontent.com/squat/generic-device-plugin/main/manifests/generic-device-plugin.yaml

Values.yaml

Tip from pajikos/home-assistant for passing in USB devices via values.yaml:

extraVolumes:- name:usbhostPath:path:>- /dev/serial/by-id/usb-ITEAD_SONOFF_Zigbee_3.0_USB_Dongle_Plus_V2_20230509111242-if00type:CharDeviceextraVolumeMounts:- name:usbmountPath:/dev/ttyACM0# note that this is readonly to prevent security issuesreadOnly:true

Keep in mind that if you're using a USB device, you may only be able to use it with one pod at a time, so you would need to also set the deployment strategy to "Recreate" so that the Deployment deletes one pod before creating another, instead of "RollingUpdate" which is the default Deployment behavior which will create another pod and make sure it's ready before deleting the old pod. If set to "RollingUpdate" (the default for all Deployments), the old pod may indefinitely hold device and prevent the new pod from spinning up as the device is not available. Example for your values.yaml:

strategy:type:Recreate

Bluetooth devices

If you're on metal and using a USB bluetooth apator of some sort, the process is a little different from the above USB Devices section. You probably want to mount dbus. See a values.yaml example here:

extraVolumes:- name:bluetoothhostPath:path:/run/dbusextraVolumeMounts:- name:bluetoothmountPath:/run/dbus# note that this is readonly to prevent security issuesreadOnly:true

Mobile config

If you're new to home assistant, you may be wondering how you connect to the companion app on your phone. This requires you to put a key with no value called mobile: in the configuration.yaml. This would break your values.yaml depending on the gitops solution you're using, so we take the configuration as an in-line yaml block string instead like this:

homeAssistant:configuration:| # this has no value
 mobile:

Status

Seemingly stable. Feel free to submit PRs and Issues though :) It was originally written for use via this Argo CD app which we deploy on metal with smol-k8s-lab, but it can be used anywhere. The docker image is kept up to date with RenovateBot.