Opt 12 v1beta1 CRDs into storage-version migration + CI guard

[ChrisJBurns]

Summary

Adds the opt-in label that the StorageVersionMigrator controller (shipped in #5362) requires to act on a CRD, and a CI guard that prevents future CRD additions from silently skipping migration.

This is PR-B of the three-PR sequence for #4969. PR-A (#5362) shipped the controller behind a default-off env-var flag. PR-B (this one) labels every storage-version root type and adds the marker-coverage CI guard. PR-C (next) flips the default to on and ships the helm chart surface + user docs.

Part of #4969. Depends on #5362 (merged).

Medium level

• Adds +kubebuilder:metadata:labels=toolhive.stacklok.dev/auto-migrate-storage-version=true to every storage-version root type under cmd/thv-operator/api/. That's the 12 root types under api/v1beta1/ plus MCPWebhookConfig under api/v1alpha1/types.go (the only CRD whose storage version is still v1alpha1). Regenerated CRD YAML so the label appears in metadata.labels on every CRD the chart ships.
• New CI test TestStorageVersionRootMarkerCoverage in cmd/thv-operator/controllers/marker_coverage_test.go. Walks every cmd/thv-operator/api/v*/ directory and scans types.go and *_types.go. For every root type carrying both +kubebuilder:object:root=true AND +kubebuilder:storageversion, the migrate marker is required. No escape hatch — if a CRD legitimately should not be auto-migrated, an entry is added to a hardcoded allowlist (excludedRootTypes in the same file, currently empty) via PR review, not via a self-serve marker.
• Marker match is whole-token strict, not substring. A typo such as =truee would pass a substring match but fail the controller's runtime check (labels[key] == "true"), silently excluding the CRD. The strict match catches it at PR time. TestContainsMarkerStrictBoundary defends the boundary contract against future regressions.
• No code logic changes, no chart-side changes, no default flip. The controller in main is still default-off; PR-B's only behavioural effect is that if an admin opts in via the env var, the migrator will now actually find labeled CRDs to act on.

Low level

File	Change
cmd/thv-operator/api/v1beta1/*_types.go (×12)	+kubebuilder:metadata:labels=...auto-migrate-storage-version=true marker on each root type
cmd/thv-operator/api/v1alpha1/types.go	Same marker added to MCPWebhookConfig (the only never-graduated storage-version root)
cmd/thv-operator/controllers/marker_coverage_test.go	New static-source CI test — scans all api/v*/ directories, requires migrate marker on every storage-version root, supports an excludedRootTypes allowlist for documented exclusions
deploy/charts/operator-crds/files/crds/*.yaml (×13)	Regenerated — label in metadata.labels
deploy/charts/operator-crds/templates/*.yaml (×13)	Regenerated — same

Type of change

• New feature (additive — extends an already-shipped feature flag)
• Bug fix
• Breaking change
• Refactoring
• Documentation
• Other

Test plan

• TestStorageVersionRootMarkerCoverage passes (scans every root type across all API version dirs, asserts marker presence)
• TestContainsMarkerStrictBoundary passes (7 subtests covering exact match, whitespace boundary, value-typo rejection — defends against future regression to permissive substring matching)
• task operator-manifests produces no diff after the markers — labels land in CRD YAML cleanly
• Full operator test suite green: go test -race ./cmd/thv-operator/...
• envtest suites green including the StorageVersionMigrator suite from PR-A
• task lint-fix — known to be blocked locally by a pre-existing toolchain mismatch (golangci-lint built against go1.25 vs repo's go1.26 target); not introduced by this PR

Why the CI guard matters

Without TestStorageVersionRootMarkerCoverage:

1. Someone adds a new CRD root type and forgets the marker.
2. task operator-manifests regenerates without the opt-in label.
3. The controller's isManagedCRD check returns false for that new CRD; CRs of that kind never get re-encoded.
4. The bug stays invisible until a future release tries to drop a deprecated version from spec.versions — at which point storedVersions still contains the deprecated version and the apiserver rejects the CRD update.
5. Diagnosis trail is long cold; the missed marker was on a PR that landed months earlier.

With the test, the PR adding the new CRD fails CI with a clear pointer to the missing marker.

The test is forward-compatible: when a future v1beta2 graduation moves +kubebuilder:storageversion from v1beta1 root types to v1beta2 root types, the scanner picks up the new directory automatically without code changes here. The previous version's root types lose the storage marker and are naturally filtered out.

Design choice: no escape hatch

An earlier iteration of this test accepted either the migrate marker or an explicit +thv:storage-version-migrator:exclude sibling. That permissive contract opens a graduation-time hole: a single-version CRD created with exclude passes CI, but at v1→v2 graduation time the developer has to remember to swap exclude→migrate. Forgetting the swap leaves the CRD silently un-migrated — exactly the failure mode the test is meant to prevent.

Replaced with: every storage-version root must have the migrate marker, full stop. If a CRD legitimately needs to be excluded, the path is to add its <version>/<file>.<TypeName> key to the excludedRootTypes map in the test file as a deliberate, reviewed decision. The allowlist is currently empty and has an example comment showing the format.

Why every storage-version root (not just multi-version CRDs)

Single-version CRDs today have nothing to migrate — storedVersions == [storageVersion], the controller's isMigrationNeeded check returns false, no-op forever. But when that CRD eventually graduates to a second version, storedVersions accumulates the old entry and the migrator suddenly needs to know whether to act. Requiring the label from day one means graduation PRs don't need to remember to add it later. The cost of the label on a single-version CRD is zero (a string in metadata.labels); the cost of forgetting at graduation is silent data orphaning.

Special notes for reviewers

• The label key toolhive.stacklok.dev/auto-migrate-storage-version is a stable API surface once shipped — users may write Kyverno rules or GitOps filters against it, so renaming becomes a breaking change.
• 13 type-file additions (one line each). The 26 generated CRD YAMLs each get the same 2 label lines. These are auto-generated; manually editing them would be wiped on the next task operator-manifests.
• Marker match is now whole-token-strict, not substring. A value typo like =truee was a real silent-failure class — controller runtime checks for exact string "true", but the CI's substring Contains would accept =truee as a match. The new containsMarker requires the marker to be followed by end-of-line or whitespace, catching the typo at PR time. TestContainsMarkerStrictBoundary is the regression guard if anyone "improves" it back to substring semantics.
• No behavioural change for any user until both (a) they opt in via TOOLHIVE_ENABLE_STORAGE_VERSION_MIGRATOR=true AND (b) they have CRs whose etcd-stored apiVersion differs from the current storage version. Today no toolhive cluster has the former and the latter is rare.

Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 68.81%. Comparing base (8932f93) to head (6d03996).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5391   +/-   ##
=======================================
  Coverage   68.81%   68.81%           
=======================================
  Files         628      628           
  Lines       63900    63900           
=======================================
+ Hits        43971    43974    +3     
+ Misses      16669    16667    -2     
+ Partials     3260     3259    -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.