Skip to content
6 min read

Home Assistant on k3s: Smart Home Without the Cloud

Home Assistant Core as a hardened k3s Deployment: local-path storage for its SQLite recorder, reverse-proxy config behind Traefik, Velero backups, and a tested restore.


Disclosure: This post contains Amazon affiliate links (marked with *). As an Amazon Associate I earn from qualifying purchases. Buying through them costs you nothing extra.

Home Assistant OS is the easiest way to run Home Assistant. It’s also an appliance: it wants a whole machine or VM, backups live in its own backup system, and remote TLS means an add-on or a Nabu Casa subscription. I run Home Assistant Core as a plain Deployment on my k3s cluster instead, on the same BMAX Mini PC* as everything else. Traefik and cert-manager handle TLS, Authelia guards the UI, Velero backs it up, and ArgoCD deploys the manifest.

Three things took real work: the SQLite recorder can’t live on NFS, the container needs a writable /run under a read-only root filesystem, and Home Assistant rejects proxied requests until you tell it about the proxy.

View the complete homelab infrastructure source on GitHub

The Deployment

One container, one PVC, in the apps namespace:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: home-assistant
  namespace: apps
spec:
  replicas: 1
  selector:
    matchLabels:
      app: home-assistant
  strategy:
    type: Recreate
  template:
    metadata:
      labels:
        app: home-assistant
    spec:
      containers:
        - name: home-assistant
          image: ghcr.io/home-assistant/home-assistant:2026.7.1
          securityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
            seccompProfile:
              type: RuntimeDefault
            capabilities:
              drop: ["ALL"]
          ports:
            - containerPort: 8123
          env:
            - name: TZ
              value: Europe/Berlin
          volumeMounts:
            - name: config
              mountPath: /config
            - name: tmp
              mountPath: /tmp
            - name: run
              mountPath: /run
          readinessProbe:
            httpGet:
              path: /manifest.json
              port: 8123
            initialDelaySeconds: 30
            periodSeconds: 15
          livenessProbe:
            httpGet:
              path: /manifest.json
              port: 8123
            initialDelaySeconds: 300
            periodSeconds: 30
            failureThreshold: 6
      volumes:
        - name: config
          persistentVolumeClaim:
            claimName: home-assistant-config
        - name: tmp
          emptyDir: {}
        - name: run
          emptyDir: {}

A few choices in there are not defaults:

  • Pinned tag, not stable. Renovate opens a PR per release, so an update is a Git commit with CI and a soak period instead of a surprise on the next pod restart.
  • strategy: Recreate. The PVC is ReadWriteOnce and the recorder database must never have two writers. A rolling update would start the new pod while the old one still holds the volume.
  • Read-only root filesystem with an emptyDir on /run. The image uses s6-overlay v3, and its init runs rm -rf /run/s6 on startup. Without a writable /run the container dies with Read-only file system.
  • Probes on /manifest.json. It returns 200 without an auth token once the frontend is up, unlike /api/*.
  • A 300-second liveness delay. After a restore or an unclean shutdown, the recorder can spend minutes recovering its SQLite database. A short liveness probe kills the pod in the middle of that and starts the recovery over.

Storage: local-path, Not NFS

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: home-assistant-config
  namespace: apps
spec:
  accessModes: [ReadWriteOnce]
  storageClassName: local-path
  resources:
    requests:
      storage: 5Gi

/config holds the configuration, automations, and home-assistant_v2.db, the recorder’s SQLite database in WAL mode. Home Assistant started on nfs-client like most of my apps. It was the last of six SQLite apps I moved to local-path after an audit found them all on NFS, for the reasons in the NFS vs local-path SQLite trap. Before the move I ran PRAGMA integrity_check, copied the data over, and checked again on the live container afterward. The recorder logged its usual unclean-shutdown warning on first start and recovered on its own.

local-path ties the pod to one node. For a single-writer workload that writes state constantly, I’ll take node-local latency over the ability to reschedule.

If you’d rather move the recorder off SQLite entirely, the setting lives under recorder: in configuration.yaml, not under homeassistant::

recorder:
  db_url: postgresql://homeassistant:PASSWORD@home-assistant-db.apps.svc:5432/homeassistant

A CNPG cluster works as the backend. I haven’t needed it: SQLite on local storage is fine for one house.

Behind Traefik and Authelia

The UI is published through a Traefik IngressRoute with the CrowdSec bouncer and Authelia in front:

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: ha-final
  namespace: apps
spec:
  entryPoints: [websecure]
  routes:
    - match: Host(`ha.woitzik.dev`)
      kind: Rule
      middlewares: [{name: crowdsec-bouncer}, {name: authelia}]
      services: [{name: home-assistant, port: 8123}]

The Companion app can’t complete an Authelia redirect, so it is meant to connect over the Headscale VPN instead, the same pattern as Jellyfin’s native clients.

The first version of this returned 400 Bad Request for every request. Home Assistant’s own log said why: “A request from a reverse proxy was received … but your HTTP integration is not set-up for reverse proxies”. The fix is an http: block in configuration.yaml:

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 10.42.0.0/16

10.42.0.0/16 is the whole k3s pod CIDR, because Traefik’s pod IP changes on every restart. configuration.yaml lives on the PVC and is edited through Home Assistant’s own file editor, not in Git, so I documented the fix as a comment in the Kubernetes manifest. Otherwise the next person to read the repo has no idea why it works.

Backups and Restore

The PVC is covered by the cluster-wide Velero schedules, with file-system backup through the node-agent:

  • daily-backup at 05:00 UTC to Garage, kept 7 days
  • daily-offsite at 04:00 UTC to Cloudflare R2, which includes the apps namespace, kept 3 days

Before a risky change I take an on-demand copy from the schedule template:

velero backup create ha-before-change --from-schedule daily-backup

velero backup create has no --schedule flag. Recurring backups are velero schedule create or a Schedule manifest, and --from-schedule reuses that template for a one-off run.

The restore I’ve actually tested is file-level: scale the Deployment to 0, mount the PVC in a throwaway pod, copy the saved /config directory in, scale back to 1. After the August 2026 rebuild I verified it by comparing file counts and contents against the pre-disaster copy, not by checking that the pod showed Running.

What This Setup Doesn’t Do

No Zigbee or Bluetooth. Home Assistant OS manages radios for you; on k3s a USB coordinator means pinning the pod to the node that has the stick and passing the device through, and my three k3s VMs have no radio attached today. You also lose the add-on store, since add-ons are a Supervisor feature that Home Assistant Core doesn’t have.

What you gain is a Home Assistant that is versioned, reviewed, backed up, and TLS-terminated the same way as the other workloads on the cluster. If you already run k3s, that’s the better trade.

Was this helpful?
Share
DW

David Woitzik

Hybrid Cloud Engineer

I work mostly with Azure, Terraform, and Zero-Trust network design, and publish the Terraform templates and write-ups I wanted when I was solving the same problems.

Keep Reading

More Like This in Your Inbox

New Terraform modules and articles by email. No spam.