[infra] infra-request dispatch handler + contabo-k3s-node module + consumer test-harness

[izzywdev]

@claude

Context: FuzeFront (and future consumer repos) now declare infra needs in git and dispatch to FuzeInfra to reconcile — FuzeFront PR #76 adds deploy/terraform/node-request.tf (referencing a FuzeInfra-owned module) + .github/workflows/infra-dispatch.yml that fires repository_dispatch (event_type: infra-request) at this repo. FuzeInfra is the sole credential holder. Build the handler side.

Please add to FuzeInfra:

1. modules/contabo-k3s-node — a Terraform module using the official contabo/contabo provider's contabo_instance (+ contabo_private_network attach): creates the VPS, injects an SSH key, and via user_data cloud-init runs k3s agent join to the existing cluster (server URL + node-token from variables) and labels the node (node-role=<role>). Inputs: requests[] ({name, product_id, region, role, labels}); creds + k3s_server_url + k3s_node_token as variables (from secrets, never hardcoded).
2. .github/workflows/infra-request-handler.yml — on: repository_dispatch: types: [infra-request]: check out the requesting repo's deploy/terraform/ + deploy/argocd/; validate each request against a whitelist (allowed product_id tier(s), region == EU, role ∈ {workload}, bounded node-count) → auto-apply (terraform apply with FuzeInfra's Contabo creds + k3s join token + a FuzeInfra-owned remote TF state backend), then k3s-join+label the node and kubectl apply/argocd-sync the changed Argo Applications. Non-whitelisted → open a gated PR with terraform plan (manual approval), do not auto-apply.
3. Document the scoped token the consumer needs: a fine-grained PAT or GitHub App with permission ONLY to trigger repository_dispatch on FuzeInfra — the consumer stores it as FUZEINFRA_DISPATCH_TOKEN. (Izzy: create it + add to FuzeFront repo secrets.)

Also (separate, for CI parity): publish a consumer test-harness compose (docker-compose.consumer-test.yml or similar) — a trimmed set of the shared base services (Postgres/Redis/Kafka/ChromaDB/MailHog) pinned to the SAME image versions prod runs — so consumer repos' CI can stand up version-accurate ephemeral infra (via the FuzeInfra submodule) instead of hand-rolling and drifting. Expose the canonical image versions in one place.

Constraints: generic (works for any consumer repo, not FuzeFront-specific); secrets via FuzeInfra's CI secrets only; PR against main; whitelist auto-apply per above. On completion, open the PR(s) and post links.

[claude]

Claude finished @izzywdev's task in 7m 12s —— View job • claude/issue-33-20260622-0542 • Create PR ➔

---

Done ✅

Built the FuzeInfra handler side of the infra-request dispatch model, plus the consumer test-harness.

Tasks

• Explore repo conventions (terraform/contabo, k3s runbook, compose image pins, CONTRACT.md)
• modules/contabo-k3s-node — Terraform module
• infra-request-handler workflow (⚠️ shipped under docs/workflows/ — see note)
• Auto-apply whitelist + validator (with unit tests)
• Document scoped FUZEINFRA_DISPATCH_TOKEN
• Consumer test-harness compose + single-source-of-truth image versions

What was added

1. modules/contabo-k3s-node/ — provisions Contabo VPS(es) and joins each to the existing k3s cluster as an agent via cloud-init, labeling node-role=<role> (+ fuzeinfra.io/role, plus any request labels). Optional contabo_private_network attach. Inputs are requests[] ({name, product_id, region, role, labels}); Contabo creds + k3s_server_url + k3s_node_token are variables, never hardcoded. Uses for_each keyed by name and ignore_changes = [user_data] so re-renders don't recreate live nodes.

2. docs/workflows/infra-request-handler.yml — on: repository_dispatch: types: [infra-request]. Checks out the requesting repo's deploy/terraform/ + deploy/argocd/, validates against the whitelist, then:

• Whitelisted → terraform apply (FuzeInfra Contabo creds + k3s token + a FuzeInfra-owned remote TF state backend) → label node → kubectl apply / argocd-sync changed Apps.
• Not whitelisted → opens a gated PR carrying terraform plan (manual approval); never auto-applies.

3. Whitelist — config/infra-request-whitelist.json (product_id tier, region==EU, role==workload, bounded node count, allowed repos) + scripts-tools/validate_infra_request.py with unit tests. Editable JSON — no workflow change needed to widen/narrow.

4. docs/INFRA_REQUEST_DISPATCH.md — architecture diagram + scoped FUZEINFRA_DISPATCH_TOKEN setup (fine-grained PAT or GitHub App, Contents:RW only, FuzeInfra-only) + the consumer-side infra-dispatch.yml example + required FuzeInfra CI secrets.

5. Consumer test-harness — docker-compose.consumer-test.yml (Postgres/Redis/Kafka/ChromaDB/MailHog) pinned from versions.env — the single source of truth mirroring docker-compose.FuzeInfra.yml. Ephemeral (own network, no volumes). Documented in docs/CONSUMER_TEST_HARNESS.md.

⚠️ Action needed (workflow activation)

GitHub App permissions block me from writing under .github/workflows/, so the handler ships at docs/workflows/infra-request-handler.yml. A maintainer must move it into place:

git mv docs/workflows/infra-request-handler.yml .github/workflows/
git commit -m "ci: activate infra-request-handler" && git push

Then add the FuzeInfra CI secrets listed in docs/INFRA_REQUEST_DISPATCH.md, and (Izzy) create FUZEINFRA_DISPATCH_TOKEN in FuzeFront's secrets.

Note: I couldn't run terraform fmt/pytest/yaml-lint — the sandbox denied Python/terraform execution (only git was permitted). Logic and syntax were written carefully and reviewed; if you want me to run validation, re-trigger with those tools allowed.

• Branch: claude/issue-33-20260622-0542