feat(service-catalog): split GPU transcoding lane from base media lane (closes #63)

[clubanderson]

Summary

Defines the GPU transcoding and hardware-passthrough validation lane as a standalone split from the base media-service lane (#59). Closes #63.

Substrate dependency chain (made explicit by this PR)

#54 substrate (GPU device plugin + driver stack on ghost)
    → #63 this lane (GPU transcoding contract proven)
    → #59 base media lane (unblocked from GPU scope)

Acceptance criteria check

• GPU transcoding / passthrough requirements are split clearly from the base media-service lane — dedicated tests/service_catalog/media_gpu/ module, separate WorkflowTemplate
• The issue states the substrate assumptions that must be proven before hardware-accelerated media validation can exist — module docstring + §7 docs table lists 5 specific epic: homelab cluster substrate and fleet-client model #54 prerequisites
• The dependency between service and substrate work is explicit — dependency chain in module docstring, WorkflowTemplate guard step, docs §7
• The issue is linked to epic: homelab service-catalog workload validation #51, epic: homelab cluster substrate and fleet-client model #54, and the media lane in feat: define representative media-service workload lane for homelab validation #59 — all referenced in commit, module docstring, and PR

What's in this PR

tests/service_catalog/media_gpu/test_gpu_transcoding.py

13 test methods in TestMediaGpuTranscodingLane:

Module-level skip gate: _gpu_allocatable_on_any_node() — if no nvidia.com/gpu in any node allocatable, the entire module is skipped. Non-GPU CI clusters are not broken.

Group	Tests
Substrate	node allocatable capacity, device plugin DaemonSet Running
Deployment	GPU deployment ready, pod Running, resource limit in pod spec
Device	/dev/nvidia* visible in container, nvidia-smi reports GPU
Transcoding	ffmpeg lists nvenc, ffmpeg 1-second hardware transcode completes
Lifecycle	GPU capacity recovers after pod deletion (within 60s)
Deferred	KubeVirt VM passthrough → pytest.skip → #54; Multi-GPU/MIG → pytest.skip; AMD/Intel → pytest.skip

argo/workflow-templates/homelab-media-gpu.yaml

WorkflowTemplate:

• check-gpu-prerequisites guard step (runs first): verifies node GPU allocatable capacity and device plugin pods; fails with clear epic: homelab cluster substrate and fleet-client model #54 step-by-step instructions if not ready
  deploy-fixture → run-tests DAG
• deploy-fixture: homelab-media-gpu-config 1Gi PVC, Deployment with nvidia.com/gpu: 1 limit, runtimeClassName: nvidia, NVIDIA_VISIBLE_DEVICES=all, linuxserver/ffmpeg image
• cleanup onExit handler

argo/homelab-media-gpu.yaml

Workflow submit trigger.

docs/homelab-contracts.md

• §6: feat: split GPU transcoding and passthrough from the base media lane #63 status updated from '❌ deferred' → '✅ defined'
• §7: New section — GPU Transcoding and Hardware-Passthrough Lane with substrate dependency chain, required-epic: homelab cluster substrate and fleet-client model #54-steps table, behavior table, skip-gate explanation, out-of-scope splits table

Dependencies

• epic: homelab cluster substrate and fleet-client model #54 homelab substrate (GPU device plugin + driver stack) — must be done before tests execute
• feat: define representative media-service workload lane for homelab validation #59 base media lane (this PR makes the split from that lane concrete)

[hanthor]

LGTM — well-structured test/infra addition, clean code.

[hanthor]

Well-designed GPU lane split. The module-level skip gate _gpu_allocatable_on_any_node() is the right approach — non-GPU CI clusters are cleanly unaffected. The dependency chain (#54 substrate → #63 this lane → #59 base media) is explicitly documented in the module docstring, WorkflowTemplate, and docs. Deferred tests (KubeVirt passthrough, multi-GPU, AMD/Intel) are properly marked with pytest.skip with issue references. The onExit cleanup handler is correctly wired. LGTM.

[hanthor]

Approved via org-wide review.

[hanthor]

Approved via org-wide review.

[hanthor]

Review: Approved ✅

Part of the structured service-catalog project build-up. Conventional Commits format, referenced issues, consistent with related PRs in the series.