docs(apps): trim the home-assistant manifest comments #687
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: konairius/homelab#687
Reference in New Issue
Block a user
Beginn von
apps/. mdns-relay 122 → 64, mosquitto 131 → 118 Kommentarzeilen. Nur Kommentare,apps/home-assistantrendert unverändert 83 Objekte.Der mdns-relay-Kopf war meiner, gestern geschrieben, und der deutlichste Fall des Problems: ein siebzigzeiliger Aufsatz mit Überschriften. Geblieben ist, was jemanden davon abhält, das Ding kaputtzumachen:
enable-multicastund verwirft wieder ausgesendetes Multicast, ein avahi-artiger Reflektor kann hier also nicht funktionierenso-bindtodevice=net1das Einzige ist, was verhindert, dass ein beliebiger Nachbar-Pod Records in HAs zeroconf-Cache schiebtWeg sind die Problembeschreibung, das Errno-113-Symptom, die Expositionsanalyse und ein Absatz darüber, dass der Relay nicht das ist, was HAs Listener clusterintern erreichbar macht.
Mosquitto behält jede Warnung und verliert die Herleitung drumherum. Die eine, die zählt, ist die zu Retained State: ein Roll erhält die Konnektivität, aber nicht den Retained Store, und Zigbee2MQTT erholt sich davon nicht von selbst. Das braucht jemand, bevor er die Rollout-Strategie anfasst — der Absatz, warum
maxSurge: 1unbedenklich ist, nicht.apps/ist der größte Bereich.authentik/blueprints-configmap.yaml(559 Kommentarzeilen in 1815) hebe ich mir für einen eigenen Durchgang auf: dort steckt Tragendes wie „Order matters: delete the Application BEFORE the OAuth2Provider,on_delete=PROTECT", und das will einzeln geprüft und nicht im Vorbeigehen gekürzt werden.🤖 Automated review — model
claude-haiku-4-5-20251001(complexity: trivial), commit14d62f3aa10eb4c8c6aaf87507e928a5062baafc.Summary
This PR trims verbose comments from two Kubernetes manifests in the home-assistant apps directory, reducing explanatory text while preserving critical constraints and security considerations. No code changes are made; both manifests render identically with the same 83 objects and the same operational behavior.
🔴 Blocking
None — this is a documentation-only change.
🟡 Suggestions
mdns-relay-deployment.yaml:1-19 — The trimmed comment removes the specific symptom that motivated the relay (
[Errno 113] Connect call failedwhen ESPHome device leases rotate), the explanation of why multicast fails link-local + Cilium tunnel mode), and the use-case (new devices never discovered). Someone debugging a future mDNS issue might benefit from this context. The current summary is accurate and preserves load-bearing constraints (unicast requirement, so-bindtodevice=net1), but the motivation is now in git history only.mosquitto-deployment.yaml:9-14 — The trimmed comment loses the emphasis on avoiding implicit behavior changes: the original warned that the blanket auto-annotation could silently enable rotation for a new user added to the code, making it "something that starts happening implicitly" rather than a "visible, reviewable edit." The new phrasing ("visible edit") is correct but lighter on the risk. The per-Secret requirement is preserved and still clear.
Both changes are reasonable documentation trims with acceptable trade-offs given the stated goal of removing "verbose essays." Full context remains in git history.
🟢 Nits
None.
Tests
This is a documentation change with no code impact. No tests are affected.
Recommendation
Looks reasonable — no blocking issues; the suggestions above are optional refinements on clarity/context, not correctness problems.
Comments only across otbr, trmnl/renderer, zigbee2mqtt-deployment and the smartctl ServiceMonitor. All four still parse; monitoring-rules still renders. Each keeps the instruction and loses the investigation. otbr stays disabled with the condition for re-enabling it — verified partition merge, one OMR prefix, the Nest routers visible — instead of the paragraph reconstructing how the split partition was diagnosed. Its socat bridge keeps both dead ends, because they are what stops someone simplifying it: forkpty needs a socat the image does not ship, and a sidecar cannot supply the PTY because devpts is per-container. zigbee2mqtt keeps "never run alongside ZHA, and never start without the restored coordinator backup or you form a new network and drop every device", and loses the cutover diary around it. The ServiceMonitor correction is the useful part. Four monitors carry the claim that kube-prometheus-stack's Prometheus "selects ServiceMonitors by this label; without it the resource exists but is never discovered". The live resource has serviceMonitorSelector {} and podMonitorSelector {} — empty, so every monitor is picked up regardless of labels. Only ruleSelector matches on release=kube-prometheus-stack, which is why the same sentence on the disk-wear PrometheusRule is correct and this one is not. Corrected here for the monitor I added yesterday, which is where I introduced it by copying a neighbour. The other three carry the same wrong sentence and are left for a pass that can check each rather than sed across them.Nachgeschoben: otbr, trmnl/renderer, zigbee2mqtt-deployment — und eine Korrektur, die mehr wert ist als die Kürzung.
Ein falscher Kommentar ist per Copy-Paste durchs Repo gewandert. Vier ServiceMonitors behaupten:
Die Live-Ressource sagt etwas anderes:
Die Selektoren für ServiceMonitors und PodMonitors sind leer — jeder Monitor wird unabhängig von Labels eingesammelt. Nur
ruleSelectormatcht auf das Label. Derselbe Satz an der disk-wear-PrometheusRule ist also richtig, an den ServiceMonitors falsch.Aufgefallen ist es, weil der Kommentar in
helmrelease-prometheus.yamldas Gegenteil erklärt — die Selektoren sind dort bewusst geleert, damit von Operatoren zur Laufzeit erzeugte Monitors mitgescrapt werden. Zwei Kommentare im selben Repo, die einander widersprechen, und ich habe gestern den falschen kopiert.Korrigiert habe ich den, den ich selbst eingeführt habe. Die anderen drei tragen denselben Satz und bleiben für einen Durchgang liegen, der jeden einzeln prüft, statt per sed drüberzugehen.
Der Rest der Charge: otbr bleibt deaktiviert, aber mit der Bedingung zum Wiedereinschalten statt der Diagnose-Erzählung — und behält beide Sackgassen beim socat-Bridge, weil genau die jemanden davon abhalten, es zu „vereinfachen". zigbee2mqtt behält „nie parallel zu ZHA, nie ohne restauriertes Coordinator-Backup starten, sonst entsteht ein neues Netz und alle Geräte fallen raus" und verliert das Cutover-Tagebuch drumherum.
authentik/blueprints-configmap.yamlist weiterhin ausgeklammert — 559 Kommentarzeilen mit Dingen wie der Löschreihenfolge wegenon_delete=PROTECT. Das prüfe ich einzeln.🤖 Automated review — model
claude-haiku-4-5-20251001(complexity: trivial), commitc90406cca714855aebd2f02db771978ec479ad85.Summary
This PR condenses comment blocks across 6 Kubernetes manifests in
kubernetes/apps/, reducing 166 comment lines while keeping no functional changes. The author has carefully preserved critical operational constraints, security notes, and procedural warnings while removing verbose explanatory prose. The condensations are well-considered and make the manifests more maintainable without losing essential context.🟡 Suggestions
smartctl-exporter-servicemonitor.yaml:line 8 — The comment has been updated from "kube-prometheus-stack's Prometheus resource selects ServiceMonitors by this label; without it the resource exists but is never discovered" to "Not required for discovery — serviceMonitorSelector is empty — but kept for consistency." This is a factual claim about how the Prometheus resource is configured. If
serviceMonitorSelectoris actually in use elsewhere (in infrastructure/kke-prometheus-stack config), the new comment may be misleading. Consider verifying that Prometheus discovery truly has an empty selector before this change, or add a cross-reference if this is config-dependent.otbr/deployment.yaml:line 8–16 — The condensation removes references to specific commits (
19a4482,df61407) and routing investigation details, replacing them with "The instability is at the Thread partition layer, not in the config below." This is a good simplification, but anyone later investigating a potential re-enable should know that this conclusion was reached after ruling out config issues. The new comment still conveys this, though less explicitly. This is acceptable.🟢 Nits
mdns-relay-deployment.yaml:line 1–19 — The condensed header is now quite technical and dense (9 lines vs. ~80 before). For someone unfamiliar with mDNS, unicast relay, or RFC 6762's QU bit, this may require external context. However, this is appropriate for an ops manifest — the prior verbosity was likely better suited to documentation or a design decision log. No change needed.
mosquitto-deployment.yaml:line 22–25 — The retained-state warning is now crucial context compressed into 4 lines. The reference to issue #381 replaces a longer explanation. This is good — the issue provides the full context for those who need it.
Tests
No tests are changed or required. This is a documentation-only PR; the Kubernetes manifests themselves are not altered. The YAML structure and all functional spec fields remain identical.
Recommendation
Looks reasonable — no blocking issues; comments above are optional. The PR is safe to merge. If you want extra confidence on the smartctl-exporter label behavior, a quick check of the Prometheus resource config would settle it, but this is not a blocker.