Files
homeassistant-gitops/README.md
T

2.8 KiB

homeassistant-gitops

Helm chart for Home Assistant (container install) on the single-node cluster (loki), deployed by ArgoCD via the apps-in-apps repo into the namespace homeassistant.

URL: https://homeassistant.smokyzone.de - public, like git: the DNS record is a Cloudflare-proxied CNAME to git.smokyzone.de (public IP kept current by the ddns CronJob), the router forwards 443 to the ingress. The companion app works without VPN. Protection is HA itself: every user needs MFA (TOTP), and the HTTP settings ban an IP after 5 failed logins (Traefik keeps Cloudflare's X-Forwarded-For, HA trusts the pod network and the Cloudflare ranges as proxies). The ingress only accepts connections from Cloudflare (Middleware traefik/cf-only). Certificate from letsencrypt-dns-cloudflare (DNS-01).

Design

  • hostNetwork: HA runs in the node's network namespace so LAN discovery (mDNS/SSDP: Chromecast, Hue, Sonos, HomeKit, ...) works. Side effect: plain HTTP is also served on http://192.168.2.218:8123 in the LAN. Set hostNetwork: false if you don't need discovery.
  • Config lives on the local-path PVC homeassistant-config (/config), which is kept when the app is deleted. Back it up (users, integrations, history are in there).
  • Reverse proxy: since 2026.10 HA keeps its HTTP settings in /config/.storage/http (managed in the UI under Settings → System → Network). An http: block in configuration.yaml is only imported once as an unconfirmed trial and silently reverted after 5 minutes (then HA answers 400 Bad Request through the ingress). The init container therefore seeds that store on first start with use_x_forwarded_for: true and trustedProxies from values.yaml (pod network 10.1.0.0/16). An existing store is never overwritten.
  • configuration.yaml is seeded once (seedConfiguration). After the first start the file is yours; the chart never overwrites it. Edit it with kubectl -n homeassistant exec -it deploy/homeassistant -- vi /config/configuration.yaml and restart the pod (or Developer tools → YAML → Restart in the UI).
  • USB radios (Zigbee/Z-Wave): list the device under devices: (prefer /dev/serial/by-id/...) and set privileged: true.
  • This is the container install: there is no add-on store (Supervisor). Add-ons such as Mosquitto or Zigbee2MQTT would run as their own deployments in the cluster.

First start

  1. Open https://homeassistant.smokyzone.de and create the owner account during onboarding (first visitor becomes the owner, so do this right away).
  2. Home location / units / language (Deutsch) in the onboarding wizard.
  3. Companion app: server URL https://homeassistant.smokyzone.de (works at home and via Tailscale).

Upgrades

Bump image.tag in values.yaml (see the release notes for breaking changes first).