feat(esphome): deploy ESPHome Device Builder behind an Authentik gate #156

2026-07-12T17:10:24Z

claude-bot commented

2026-07-12 17:10:24 +00:00

What

Deploys the ESPHome Device Builder (ghcr.io/esphome/esphome:2026.6.2, :6052) into the home-assistant namespace, behind an Authentik gate — so ESPHome devices can be built, browser/USB-flashed (ESP Web Tools / Web Serial), and config-managed in-cluster. First use: an M5 Atom Echo Bluetooth proxy for shelly-manager's BLE provisioning (moving that radio off edge-1, which is in a poor spot for BLE range).

Why no macvlan (v1)

Unlike shelly-manager, the dashboard needs no L2 presence on the IoT VLAN: initial flashing is browser-side over USB, builds are offline. This deliberately sidesteps the macvlan-on-0.0.0.0 hole — a gated pod with a macvlan bypasses Cilium policy and exposes its unauthenticated UI on the IoT VLAN (confirmed against shelly-manager/matter-server/otbr). Live status / logs / OTA would need cluster→v30iot reachability (a separate, still-open item); a macvlan can be added later if wanted.

Change set (mirrors the shelly-manager gate pattern)

home-assistant: esphome deployment (Recreate, RWO 10Gi ceph-block PVC for the PlatformIO build cache), service, gate ExternalName, and a Traefik ingress that backends the Authentik esphome-gate outpost (never esphome directly).
authentik: esphome-gate proxy provider + application + dedicated outpost (passkey step-up, git-owned ESPHome Managers group) in blueprints-configmap.yaml, plus esphome-gate-egress CNP (outpost → :6052).
network-policies: home-assistant default-deny-ingress grants only the esphome-gate outpost → :6052. :6052 is unique (no collision with the shared :8080 the vscode/shelly gates ride on).

DNS (esphome.home.renner.uno) + TLS come via external-dns/Traefik + cert-manager, same as shelly-manager.

Validation

kubectl kustomize builds cleanly for the home-assistant, authentik, and network-policies kustomizations, all rendering the new resources.

Post-deploy checks (noted in the manifests)

Confirm the dashboard has no credentials:'omit' service-worker/manifest that 302-loops at the gate — add skip_path_regex if so (the gotcha that bit vscode/paperless).
Confirm the image serves the dashboard on :6052 with its default entrypoint.

Follow-ups (not in this PR)

The ble-agent transport swap to bleak-esphome so shelly-manager provisions through the flashed proxy (shelly-manager repo).
OTA / live-device-status (needs the cluster→IoT-VLAN reachability work).

🤖 Generated with Claude Code

## What Deploys the **ESPHome Device Builder** (`ghcr.io/esphome/esphome:2026.6.2`, `:6052`) into the `home-assistant` namespace, behind an Authentik gate — so ESPHome devices can be built, browser/USB-flashed (ESP Web Tools / Web Serial), and config-managed in-cluster. First use: an **M5 Atom Echo Bluetooth proxy** for shelly-manager's BLE provisioning (moving that radio off edge-1, which is in a poor spot for BLE range). ## Why no macvlan (v1) Unlike shelly-manager, the dashboard needs **no L2 presence on the IoT VLAN**: initial flashing is browser-side over USB, builds are offline. This deliberately sidesteps the macvlan-on-`0.0.0.0` hole — a gated pod with a macvlan bypasses Cilium policy and exposes its unauthenticated UI on the IoT VLAN (confirmed against shelly-manager/matter-server/otbr). Live status / logs / **OTA** would need cluster→v30iot reachability (a separate, still-open item); a macvlan can be added later if wanted. ## Change set (mirrors the shelly-manager gate pattern) - **home-assistant:** `esphome` deployment (Recreate, RWO 10Gi `ceph-block` PVC for the PlatformIO build cache), service, gate `ExternalName`, and a Traefik ingress that backends the Authentik **esphome-gate** outpost (never esphome directly). - **authentik:** `esphome-gate` proxy provider + application + dedicated outpost (passkey step-up, git-owned **ESPHome Managers** group) in `blueprints-configmap.yaml`, plus `esphome-gate-egress` CNP (outpost → `:6052`). - **network-policies:** `home-assistant` default-deny-ingress grants **only** the esphome-gate outpost → `:6052`. `:6052` is unique (no collision with the shared `:8080` the vscode/shelly gates ride on). DNS (`esphome.home.renner.uno`) + TLS come via external-dns/Traefik + cert-manager, same as shelly-manager. ## Validation `kubectl kustomize` builds cleanly for the `home-assistant`, `authentik`, and `network-policies` kustomizations, all rendering the new resources. ## Post-deploy checks (noted in the manifests) 1. Confirm the dashboard has no `credentials:'omit'` service-worker/manifest that 302-loops at the gate — add `skip_path_regex` if so (the gotcha that bit vscode/paperless). 2. Confirm the image serves the dashboard on `:6052` with its default entrypoint. ## Follow-ups (not in this PR) - The **ble-agent transport swap** to `bleak-esphome` so shelly-manager provisions *through* the flashed proxy (shelly-manager repo). - OTA / live-device-status (needs the cluster→IoT-VLAN reachability work). 🤖 Generated with [Claude Code](https://claude.com/claude-code)

claude-bot added 1 commit 2026-07-12 17:10:25 +00:00

feat(esphome): deploy ESPHome Device Builder behind an Authentik gate 948852d83f

Adds the ESPHome Device Builder (ghcr.io/esphome/esphome:2026.6.2, :6052) to the
home-assistant namespace so ESPHome devices — starting with an M5 Atom Echo BLE
proxy for shelly-manager's BLE provisioning — can be built, browser/USB-flashed
(ESP Web Tools / Web Serial), and config-managed in-cluster.

v1 deliberately runs with NO macvlan. Unlike shelly-manager it needs no L2
presence on the IoT VLAN: initial flashing is browser-side over USB and builds
are offline. That also sidesteps the macvlan-on-0.0.0.0 hole (a gated pod with a
macvlan bypasses Cilium policy and exposes its unauthenticated UI on the IoT VLAN
— confirmed against shelly-manager/matter-server/otbr). Live status / logs / OTA
would need cluster→v30iot reachability (a separate, still-open item); a macvlan
can be added later if wanted.

Mirrors the shelly-manager gate pattern exactly:
- home-assistant: esphome deployment (Recreate, RWO 10Gi ceph-block PVC for the
  PlatformIO build cache), service, gate ExternalName, and a Traefik ingress that
  backends the Authentik esphome-gate outpost (not esphome directly).
- authentik: an esphome-gate proxy provider + application + dedicated outpost
  (passkey step-up, "ESPHome Managers" group, git-owned membership) in
  blueprints-configmap.yaml, plus esphome-gate-egress CNP (outpost → :6052).
- network-policies: the home-assistant default-deny-ingress grants ONLY the
  esphome-gate outpost → :6052. :6052 is unique (no collision with the shared
  :8080 the vscode/shelly gates ride on).

Validated: kubectl kustomize builds cleanly for the home-assistant, authentik,
and network-policies kustomizations, all rendering the new resources.

Post-deploy checks: confirm the dashboard has no credentials:'omit' service
worker/manifest that 302-loops at the gate (add skip_path_regex if so); confirm
the image serves the dashboard on :6052 with the default entrypoint.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

k.renner merged commit f9a0d6cd1a into master

2026-07-12 17:11:09 +00:00

k.renner referenced this issue from a commit

2026-07-12 17:11:10 +00:00

Merge pull request 'feat(esphome): deploy ESPHome Device Builder behind an Authentik gate' (#156) from feat/esphome-device-builder into master

claude-bot referenced this pull request

2026-07-12 23:21:21 +00:00

feat(esphome): version the Atom Echo Shelly BLE proxy config #158

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: konairius/homelab#156