jlab-cluster/helm-charts
3
0 Fork 0
Code Issues 15 Pull Requests 3 Actions Packages Wiki Activity

feat(homeassistant): Gateway-API as an alternative to the Ingress

Browse Source 
Group 3 of the #114 sweep, and the one chart where the convention had to bend
rather than the chart. homeassistant is the DOCUMENTED INGRESS EXCEPTION
(README): upstream's flexible values, a list of hosts each with its own list
of paths, instead of the repo's required domain/clusterIssuer pair. The
exception stays - nothing here unifies it.

NO httpRoute.hostnames KEY, which is the freesailarr shape from group 2 and
for the same reason: there is no ingress.domain to fall back to, and a
chart-global hostname list could not say which host entry - and therefore
which set of paths - it belonged to. So httpRoute carries only enabled and
parentRefs, the hostnames come from ingress.hosts, and the chart renders ONE
HTTPRoute PER ENTRY with one rule per path of that entry. One object with
several hostnames would be wrong, not merely different: an HTTPRoute's rules
apply to every hostname of the object, and per-host paths are this chart's
whole point. The schema rejects httpRoute.hostnames outright, so the absence
is enforced rather than merely intended.

ingress.hosts is therefore read in BOTH modes and is not an Ingress-only
value. ingress.className, ingress.tls and ingress.annotations are not read in
Gateway mode: class and certificate belong to the Gateway's listener, and
there is no annotation channel.

pathType IS THE SHARP EDGE, AND THE CHART'S DEFAULT IS THE AWKWARD VALUE.
Ingress has Exact/Prefix/ImplementationSpecific; the Gateway API has
Exact/PathPrefix/RegularExpression. Exact and Prefix map cleanly.
ImplementationSpecific - the default in values.yaml - means "ask the
controller" and has NO counterpart, so:

  - on "/" it renders as PathPrefix. Every controller treats a root
    ImplementationSpecific path as a prefix match, so the chart's own default
    works in this mode unchanged (verified: the untouched default renders a
    valid route).
  - on ANY OTHER path the render ABORTS, naming the value and asking for
    Prefix or Exact. In ingress-nginx - this chart's default class - an
    ImplementationSpecific sub-path is a REGEX, and PathPrefix is not one.
    Mapping it silently would change how the path matches while the render
    stayed green, which is exactly the class of defect #118 was.

RegularExpression is deliberately not offered as an escape hatch: its support
level is Implementation-specific, which decision 1 of #114 forbids.

NOTHING WAS MEASURED ON THE LIVE CLUSTER FOR THIS CHART, because there is
nothing to measure: homeassistant is NOT DEPLOYED in jk-cluster (checked
2026-10-12 - 23 Ingress objects cluster-wide, none this chart's, and no
workload of it in any namespace). So it is the one chart of the six with no
operator-supplied annotation to lose. values.yaml and NOTES.txt say that as
an absence of evidence about this installation rather than as a property of
the chart.

Route NAMES carry the entry's INDEX, not its hostname - a hostname is not a
dependable object-name fragment. Consequence named in values.yaml and in the
template: reordering ingress.hosts renames routes and therefore recreates
rather than edits them. Harmless, since a route holds no state and no
certificate.

ci/httproute/homeassistant.yaml has to SUPPLY HOSTS, which no other overlay in
the sweep does, and it adds coverage the install-test never had: this chart's
ingress.enabled defaults to FALSE and the fixture does not switch it on, so
no routing object was exercised at all before. Two entries on purpose - a
plain one, and one with two paths including an Exact - because that second
entry is what proves the chart renders one object per host rather than one
object with several hostnames. 5 assertions over 2 routes and 3 rules.

NOTES.txt asks $published where it asked ingress.enabled, and the
trusted_proxies section now warns that moving from an Ingress to a Gateway
CHANGES the proxy's pod network: a list carried over unchanged turns every
request into a 400 if the CIDR differs, or silently keeps attributing every
client to one address if it does not.

Minor: additive, defaults unchanged. Empty helm template diff against
origin/main, both with the fixture as it stands and with ingress.enabled=true.

Part of #114
This commit is contained in:
jklein authored and jklein committed 2026-10-13 08:59:09 +00:00
1 parent 3e969c5659
commit b10800da2a
6 files changed
+453 -22
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

homeassistant/templates/NOTES.txt
+102 -19
View File
@@ -18,7 +18,20 @@ print as "1e+06" here just as it did in the rendered manifest.
{{- $ctr := fromYaml (include "homeassistant.containerSecurityContext" .Values.securityContext) -}}
{{- $caps := (index $ctr "capabilities") | default dict -}}
{{- $netRaw := has "NET_RAW" ((index $caps "add") | default list) -}}
{{- /*
NOTHING IN CI READS THIS FILE. `helm template` does not emit notes and no
workflow or script under ci/ reads it, so every claim below carries
review-only assurance - it is checked by being read, not by a stage. A
rendering ERROR here does fail `helm template`, which is all the pipeline can
see of it.
*/ -}}
{{- $ing := .Values.ingress -}}
{{- $httpRoute := .Values.httpRoute | default dict -}}
{{- /*
"Published" rather than "has an Ingress": the two modes are alternatives, and
both read ingress.hosts (Gitea #114).
*/ -}}
{{- $published := or $ing.enabled $httpRoute.enabled -}}
{{- $hosts := $ing.hosts | default list -}}
{{- $tls := $ing.tls | default list -}}
{{- $ann := $ing.annotations | default dict -}}
@@ -33,7 +46,7 @@ Home Assistant {{ .Chart.AppVersion }} — release {{ .Release.Name }} in namesp
{{- if $ing.enabled }}
ACCESS
ACCESS — INGRESS MODE (ingress.enabled: true, httpRoute.enabled: false)
{{- range $h := $hosts }}
{{- $scheme := "http" }}
{{- range $t := $tls }}
@@ -75,11 +88,73 @@ ACCESS
kubectl -n {{ .Release.Namespace }} get certificate {{ $certName | default "<your ingress.tls secretName>" }}
{{- end }}
{{- else if $httpRoute.enabled }}
ACCESS — GATEWAY MODE (httpRoute.enabled: true, ingress.enabled: false)
{{- range $h := $hosts }}
{{- range $p := ($h.paths | default list) }}
https://{{ $h.host }}{{ $p.path }}
{{- end }}
{{- end }}
ONE HTTPRoute PER ENTRY of ingress.hosts, and nothing else of the routing
path — no Gateway, no class, no Certificate, no policy object:
{{- range $i, $h := $hosts }}
{{ $.Release.Name }}-{{ $.Chart.Name }}-httproute{{ if $i }}-{{ $i }}{{ end }} {{ $h.host }}
{{- end }}
This chart has no ingress.domain — it is the documented ingress exception and
keeps upstream's flexible host list — so there is no httpRoute.hostnames
either: the hostnames and the paths above come from ingress.hosts, which is
read in BOTH modes. ingress.className, ingress.tls and ingress.annotations
are NOT read in this mode.
Three things therefore belong to the cluster, and if any is missing the
hostnames above simply do not answer:
1. The Gateway-API CRDs. Without them this install would have failed, so
they are present — nothing to check.
2. The Gateway named in httpRoute.parentRefs
{{- range $httpRoute.parentRefs }}
{{ .name }}{{ if .namespace }} in namespace {{ .namespace }}{{ end }}{{ if .sectionName }}, listener {{ .sectionName }}{{ end }}
{{- end }}
must exist AND its listener must allow routes from this namespace
({{ .Release.Namespace }}) in allowedRoutes. A rejected attachment is visible only
in the route's status:
kubectl -n {{ .Release.Namespace }} get httproute {{ .Release.Name }}-{{ .Chart.Name }}-httproute -o yaml
Read status.parents[].conditions — "Accepted: True" and
"ResolvedRefs: True" is what a working attachment looks like. An empty
status means no controller has looked at the route at all.
3. The TLS certificates for those hostnames, on the Gateway's listeners.
THE URLS ABOVE SAY https BECAUSE THAT IS WHAT A GATEWAY LISTENER
NORMALLY TERMINATES, not because this release arranged it: ingress.tls
is not read in this mode and this chart requests no certificate in
either mode (see the Ingress-mode text — it never did).
WHAT IS GONE IN THIS MODE, generally rather than specifically: the Gateway
API has no annotation channel for controller behaviour, so everything in
ingress.annotations is inert. For THIS chart there is no measured loss to
report — the installation this repository serves does not deploy
homeassistant at all, so unlike its five siblings in this sweep it had no
operator-supplied annotation to lose. That is an absence of evidence about
that installation, not a property of the chart: whatever YOU put in
ingress.annotations disappears here.
AND ONE THING TO CHECK IN HOME ASSISTANT ITSELF, because no Kubernetes object
reports it: Home Assistant refuses requests whose Host header is not in its
own configuration and builds absolute URLs from it, and it needs the proxy's
address in trusted_proxies to read X-Forwarded-For at all. Changing the data
path changes that address — the Gateway's data-plane pods are not the ingress
controller's. See the trusted-proxies section below; it applies to the
Gateway exactly as it did to ingress-nginx, with a different CIDR.
{{- else }}
ACCESS — NO INGRESS
ingress.enabled is false, so this release has no Ingress. Nothing else in
this chart reads ingress.hosts, so no other setting silently depends on it.
ACCESS — NEITHER INGRESS NOR HTTPROUTE
ingress.enabled and httpRoute.enabled are both false, so this release
publishes nothing. Nothing else in this chart reads ingress.hosts, so no
other setting silently depends on it.
Reach the instance inside the cluster with
kubectl -n {{ .Release.Namespace }} port-forward svc/{{ .Release.Name }}-{{ .Chart.Name }}-service 8123:{{ .Values.service.port }}
@@ -89,21 +164,25 @@ ACCESS — NO INGRESS
because a browser that has already talked to another Home Assistant on
localhost:8123 will otherwise mix up the stored tokens.
{{- end }}
{{- if and $ing.enabled $placeholder }}
{{- if and $published $placeholder }}
THE INGRESS IS PUBLISHED UNDER THE CHART'S PLACEHOLDER HOST
ingress.enabled is true while ingress.hosts still contains the default entry
"chart-example.local". That name resolves nowhere, so the Ingress exists,
ingress-nginx accepts it, and no request ever arrives. Set ingress.hosts to
THIS RELEASE IS PUBLISHED UNDER THE CHART'S PLACEHOLDER HOST
{{ if $ing.enabled }}ingress.enabled{{ else }}httpRoute.enabled{{ end }} is true while ingress.hosts still contains the default entry
"chart-example.local". That name resolves nowhere, so the {{ if $ing.enabled }}Ingress{{ else }}HTTPRoute{{ end }} exists,
{{ if $ing.enabled }}ingress-nginx accepts it{{ else }}the Gateway accepts it{{ end }}, and no request ever arrives. Set ingress.hosts to
the name you actually serve — for example example.com — before assuming the
release is unreachable for some deeper reason.
{{ if $httpRoute.enabled }}ingress.hosts is read in Gateway mode too; it is not an "Ingress-only"
value.{{ end }}
{{- end }}
{{ if eq $replicas "0" }}
SCALED TO ZERO
{{ if .Values.scaleDown }}scaleDown: true{{ else }}replicas: 0{{ end }} — the StatefulSet runs with replicas: 0, so nothing answers
until you set it back and upgrade again. The PVC, the OnePasswordItem and
the Service{{ if $ing.enabled }} and Ingress stay in place, so no state is lost and no
certificate is re-issued.{{ else }} stay in place, so no state is lost.{{ end }}
certificate is re-issued.{{ else if $httpRoute.enabled }} and the HTTPRoutes stay in place, so no state is
lost — the routes keep pointing at a Service with no endpoints, and the
Gateway answers with an error of its own rather than with nothing.{{ else }} stay in place, so no state is lost.{{ end }}
Bringing this release back up is not a no-op: the pod re-reads the config
item from the vault as it starts, and it starts on whatever app version the
@@ -155,23 +234,27 @@ THE CONFIGURATION IS A 1PASSWORD ITEM, AND IT IS READ-ONLY IN THE CONTAINER
kubectl -n {{ .Release.Namespace }} rollout restart statefulset/{{ $sfs }}
BEHIND AN INGRESS, THE http BLOCK DECIDES BETWEEN 400 AND WRONG CLIENT IPs
Every request reaching Home Assistant through ingress-nginx arrives from the
controller's pod IP, not from the browser. The http-config field is where
that is dealt with, and both ways of getting it wrong are quiet in their own
way:
BEHIND A PROXY, THE http BLOCK DECIDES BETWEEN 400 AND WRONG CLIENT IPs
Every request reaching Home Assistant through {{ if $httpRoute.enabled }}the Gateway{{ else }}ingress-nginx{{ end }} arrives from
{{ if $httpRoute.enabled }}its data-plane pod IP{{ else }}the controller's pod IP{{ end }}, not from the browser. The http-config field is
where that is dealt with, and both ways of getting it wrong are quiet in
their own way:
use_x_forwarded_for: true without the proxy's address in trusted_proxies
makes Home Assistant reject the request outright — the browser gets
400 Bad Request and the log names the untrusted address it saw.
Neither setting at all means every client looks like the ingress
controller. Nothing fails; you simply get one address in the logbook for
Neither setting at all means every client looks like {{ if $httpRoute.enabled }}the Gateway{{ else }}the ingress
controller{{ end }}. Nothing fails; you simply get one address in the logbook for
everyone, and Home Assistant's login-attempt ban then locks out all users
at once because they share that address.
The value belongs to the ingress controller's POD network, not to the nodes
and not to the clients:
The value belongs to the {{ if $httpRoute.enabled }}GATEWAY's{{ else }}ingress controller's{{ end }} POD network, not to the nodes
and not to the clients{{ if $httpRoute.enabled }} — and switching from an Ingress to a Gateway CHANGES
that network, because a Gateway's data plane normally runs in a namespace of
its own. A trusted_proxies list carried over unchanged from Ingress mode
turns every request into a 400 if the pod CIDR differs, or silently keeps
attributing all clients to one address if it does not{{ end }}:
use_x_forwarded_for: true
trusted_proxies: