Skip to content

feat: define deferred non-core service follow-up for Home Assistant-class workloads #199

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
clubanderson wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat: define deferred non-core service follow-up for Home Assistant-class workloads #199

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
106 changes: 103 additions & 3 deletions docs/homelab-contracts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,9 @@

This document defines the in-cluster workload validation contracts for the
testing-lab QA factory. It covers the workload matrix (#57), shared-storage
and RWX limits (#62), storage observability surface (#70, #78), and the
fleet-client vs. cluster-node boundary (#72).
and RWX limits (#62), storage observability surface (#70, #78), the
fleet-client vs. cluster-node boundary (#72), and the deferred non-core
service follow-up for Home Assistant-class workloads (#69).

---

Expand Down Expand Up @@ -187,13 +188,112 @@ The lab validates the following hostname/routing pattern for exposed in-cluster

---

## 6. Known Blockers and Deferred Work
## 6. Deferred Non-Core Service Follow-Up: Home Assistant-Class Workloads (#69)

This section formally defines **Home Assistant-class workloads** as deferred
scope under the service-catalog epic (#51). These are non-core homelab
services that have significant infrastructure requirements beyond what the
current lab validates. This section exists to make the deferral explicit and
managed rather than implied.

### What "Home Assistant-class" means

Home Assistant is the representative example, but this class covers any
homelab service that exhibits most of these characteristics:

| Characteristic | Example |
|---|---|
| **Long-lived stateful service** | Home Assistant, Node-RED, Zigbee2MQTT |
| **Persistent configuration database** | SQLite/PostgreSQL on a PVC |
| **Web UI requiring auth-gated HTTPS** | HA dashboard, Node-RED editor |
| **Hardware/peripheral integration** | Zigbee/Z-Wave USB dongles, Bluetooth |
| **LAN service discovery** | mDNS, SSDP, multicast |
| **Addon/plugin ecosystem** | HA integrations, HACS, custom components |
| **Upgrade-sensitive state** | DB migrations on version bump |

### Why this is deferred

Non-core service validation depends on infrastructure that the lab has not
yet proven. Attempting to validate Home Assistant-class workloads before
the prerequisites are durable would either produce false confidence (testing
against ad hoc workarounds) or block on unresolved substrate gaps.

### Entry criteria — all must be met before this work becomes active

| # | Criterion | Tracks to |
|---|---|---|
| 1 | **Shared service-catalog workload contract is defined and implemented** — the minimum deployment, persistence, reachability, and teardown evidence that every service lane must prove | #66 (contract), #79 (pipeline) |
| 2 | **At least one durable media-service lane is running** — proving the service-catalog pipeline works end-to-end with a real workload | #59 → #80 |
| 3 | **At least one durable non-media service lane is running** — proving the pipeline generalizes beyond media workloads | #64 → #81 |
| 4 | **HTTPS exposure lane is validated** — the access/TLS infrastructure that any auth-gated UI depends on | #58 |
| 5 | **Auth-gating lane is validated** — the credential-enforcement layer that any exposed service UI depends on | #61 |
| 6 | **Storage persistence survives restart** — proven by the homelab-storage lane; non-core services depend on this for config/DB durability | `homelab-storage` lane |

### What this repo will validate when entry criteria are met

Once active, the Home Assistant-class lane should validate:

- **Deployment**: Service deploys via raw manifests into a dedicated namespace
using the shared service-catalog pipeline (#79).
- **Persistence**: Configuration database survives `rollout restart` (same
contract as homelab-storage, applied to the service's config PVC).
- **HTTPS reachability**: Web UI is reachable over HTTPS within the cluster
(reuses the access-probe infrastructure from #58).
- **Auth-gating**: Web UI rejects unauthenticated access and accepts valid
credentials (reuses the auth-gating infrastructure from #61).
- **Health endpoint**: Service-specific health or readiness endpoint returns
a healthy status after deployment.

### What remains explicitly out of scope even when active

| Concern | Why deferred further |
|---|---|
| **USB/Zigbee/Z-Wave device passthrough** | Requires KubeVirt device passthrough or privileged containers; tracked under #67 |
| **mDNS/SSDP LAN discovery** | Requires host-network or multicast support; tracked under #67 |
| **Addon/plugin ecosystem validation** | Product-scope, not infrastructure validation |
| **Home Assistant OS or Supervised installs** | This repo validates k8s-native container workloads only |
| **VM-backed role validation** | Tracked under #54, explicitly not a blocker for k8s-first lanes |
| **Identity provider / SSO integration** | Deferred from the auth-gating lane; applies here too |

### Relationship to the service-catalog epic (#51)

This issue is child #6 of #51, deliberately sequenced last:

1. ~~Shared workload contract~~ → #66
2. ~~Shared pipeline~~ → #79
3. ~~Media-service lane~~ → #59 → #80
4. ~~Non-media lane~~ → #64 → #81
5. ~~Hardware/discovery splits~~ → #63, #67
6. **Non-core deferred follow-up** → **this section (#69)**

The sequencing is intentional: non-core services consume all of the
infrastructure that the earlier lanes prove. Activating #69 before the
earlier lanes are durable means testing against unvalidated substrate.

### How to activate this lane

When all entry criteria in the table above are met:

1. File a new implementation issue under #51 for the first Home
Assistant-class workload (e.g., "implement Home Assistant validation
lane in service-catalog pipeline").
2. The implementation issue should reference this section for scope and
explicitly inherit the shared workload contract from #66.
3. Move this section's status from "deferred" to "active" in the blockers
table below (§7).
4. Do not remove this section — it serves as the design record for why the
work was deferred and what the activation criteria were.

---

## 7. Known Blockers and Deferred Work

| Issue | Status | Dependency |
|---|---|---|
| #62 RWX / shared-storage | ❌ blocked | NFS CSI or Longhorn installation on ghost |
| #63 GPU transcoding lane | ❌ deferred | GPU passthrough KubeVirt feature gate |
| #61 auth-gated service UI | ❌ deferred | service-catalog baseline lane first |
| #69 Home Assistant-class workloads | ❌ deferred | All entry criteria in §6 (#66, #79, #80, #81, #58, #61, storage lane) |
| #60 first restore drill | ✅ implemented | `homelab-restore-drill` WorkflowTemplate + `tests/homelab_backup/` |
| #84 PVC restore drill with backup artifact | ✅ implemented | `homelab-restore-drill` WorkflowTemplate + `tests/homelab_backup/` |
| Media service lane | ❌ deferred | #62 (shared mount) + #63 (GPU) |