Graduate CRDs from v1alpha1 to v1beta1 (#4849)

* Graduate CRDs from v1alpha1 to v1beta1

Signal API stability by promoting all ToolHive CRDs to v1beta1 while
preserving backwards compatibility — the CRDs serve both versions
simultaneously so existing v1alpha1 resources survive the upgrade
untouched and users migrate manifests at their own pace.

v1alpha1 and v1beta1 are schema-identical. The new
cmd/thv-operator/api/v1alpha1/ package defines only the root resource
types (MCPServer, MCPGroup, ...) as thin wrappers whose Spec and Status
fields reference the canonical types from v1beta1. controller-gen walks
field types when building the OpenAPI schema, so both versions resolve
to the same schema without any duplication of the actual model — I
verified empirically that all 12 CRDs produce structurally identical
schemas (modulo the legitimately-different root descriptions).

The upgrade is orchestrated through the `served` and `storage` flags
on each version entry: the new CRDs list both versions as served, mark
v1beta1 as storage, and mark v1alpha1 as deprecated with a warning.
No conversion webhook is configured, which defaults to strategy: None
— safe because the schemas are identical. Kubernetes swaps the
apiVersion string when serving an object at a different version than
it was stored at. Users can upgrade the CRD chart without deleting
anything, keep reading/writing at v1alpha1 indefinitely, and migrate
to v1beta1 by re-applying manifests. Once status.storedVersions no
longer contains v1alpha1, a future release can drop the v1alpha1
entry and remove the wrapper package.

What changed:

- Mechanical rename from v1alpha1 to v1beta1 across all Go imports,
  YAML apiVersion strings, Helm deploy manifests, chainsaw fixtures,
  examples, docs, and generated artifacts.
- New cmd/thv-operator/api/v1alpha1/ package: 12 root types + 12 list
  types as thin wrappers over v1beta1 Spec/Status, plus scheme
  registration. Each root type carries a +kubebuilder:deprecatedversion
  warning so kubectl prints a migration hint on every access.
- Register both schemes in cmd/thv-operator/main.go.
- Regenerated CRD manifests list both versions (v1alpha1 deprecated
  and non-storage, v1beta1 storage) with conversion.strategy: None.
- Removed the obsolete pre-upgrade Helm hook that blocked upgrades
  when v1alpha1 resources existed — no longer needed since those
  resources now survive the upgrade.
- Drive-by: regenerate pkg/audit/zz_generated.deepcopy.go which had
  drifted after DetectApplicationErrors was added to Config without
  re-running controller-gen.

Closes #2556

* Update test files to use v1beta1 after merge

Two test files that came in via the merge from main still reference
the v1alpha1 Go package, which no longer exists on this branch. The
operator binaries compile fine, but CI lint/test fail on the missing
mcpv1alpha1 symbol in the test package.

- cmd/thv-operator/controllers/mcpremoteproxy_deployment_test.go
- cmd/thv-operator/controllers/mcpserver_resource_overrides_test.go

Applied the same mcpv1alpha1 → mcpv1beta1 rename that the rest of
the branch uses. No behavioural change.

Author: ChrisJBurns

.claude/skills/implement-story/SKILL.md

@@ -170,7 +170,7 @@ After changes that affect generated artifacts, run the appropriate tasks:
 
 | Change Type | Regeneration Command |
 |-------------|---------------------|
-| CRD type definitions (`api/v1alpha1/*_types.go`) | `task operator-manifests operator-generate` |
+| CRD type definitions (`api/v1beta1/*_types.go`) | `task operator-manifests operator-generate` |
 | Mock interfaces | `task gen` |
 | CLI commands or API endpoints | `task docs` |
 | Helm chart values | `task helm-docs` |

PROJECT

@@ -11,6 +11,6 @@ resources:
   domain: toolhive.stacklok.dev
   group: toolhive
   kind: MCPServer
-  path: github.com/stacklok/toolhive/cmd/thv-operator/api/v1alpha1
-  version: v1alpha1
+  path: github.com/stacklok/toolhive/cmd/thv-operator/api/v1beta1
+  version: v1beta1
 version: "3"

cmd/thv-operator/README.md

@@ -136,7 +136,7 @@ helm upgrade -i <release_name> oci://ghcr.io/stacklok/toolhive/toolhive-operator
 To create an MCP server, define an `MCPServer` resource and apply it to your cluster:
 
 ```yaml
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: fetch
@@ -165,7 +165,7 @@ kubectl apply -f your-mcpserver.yaml
 For MCP servers that require authentication tokens or other secrets:
 
 ```yaml
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: github
@@ -272,7 +272,7 @@ kubectl create configmap my-registry-data --from-file registry.json=/path/to/you
 Then create the MCPRegistry resource with `configYAML` and mount the ConfigMap:
 
 ```yaml
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRegistry
 metadata:
   name: my-registry
@@ -350,7 +350,7 @@ This operator is scaffolded using Kubebuilder. If you want to make changes to th
 Generate CRD manifests:
 
 ```bash
-kubebuilder create api --group toolhive --version v1alpha1 --kind MCPServer
+kubebuilder create api --group toolhive --version v1beta1 --kind MCPServer
 ```
 
 Update CRD manifests after changing API types:
@@ -369,7 +369,7 @@ task operator-run
 
 The Kubebuilder project structure is as follows:
 
-- `api/v1alpha1/`: Contains the API definitions for the CRDs
+- `api/v1beta1/`: Contains the API definitions for the CRDs
 - `controllers/`: Contains the reconciliation logic for the controllers
 - `config/`: Contains the Kubernetes manifests for deploying the operator
 - `PROJECT`: Kubebuilder project configuration file

cmd/thv-operator/REGISTRY.md

@@ -33,7 +33,7 @@ data:
       }
     }
 ---
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRegistry
 metadata:
   name: my-registry
@@ -171,7 +171,7 @@ type: Opaque
 stringData:
   password: "ghp_your_github_token_here"  # GitHub PAT, GitLab token, etc.
 ---
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRegistry
 metadata:
   name: private-registry
@@ -501,7 +501,7 @@ kubectl logs -n toolhive-system deployment/toolhive-operator | grep "my-registry
 
 ### Production Registry
 ```yaml
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRegistry
 metadata:
   name: production-registry
@@ -523,7 +523,7 @@ spec:
 
 ### Development Registry
 ```yaml
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRegistry
 metadata:
   name: dev-registry
@@ -554,7 +554,7 @@ type: Opaque
 stringData:
   token: "<github token>"
 ---
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRegistry
 metadata:
   name: private-registry
@@ -586,7 +586,7 @@ spec:
 You can configure multiple data sources in a single MCPRegistry and aggregate them into registry views:
 
 ```yaml
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRegistry
 metadata:
   name: multi-source-registry

cmd/thv-operator/api/v1alpha1/doc.go

@@ -0,0 +1,19 @@
+// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+// Package v1alpha1 contains the deprecated v1alpha1 API types for the
+// toolhive.stacklok.dev group. These types exist solely to enable seamless
+// CRD graduation from v1alpha1 → v1beta1: the CRD serves both versions
+// (with conversion strategy "None"), so existing v1alpha1 resources continue
+// to work while users migrate their manifests to v1beta1.
+//
+// All Spec and Status types are imported from v1beta1 — the schemas are
+// identical. Only the root resource types and their List companions are
+// defined here so that controller-gen produces a multi-version CRD.
+//
+// This package will be removed in a future release once the v1alpha1
+// deprecation period ends.
+//
+// +kubebuilder:object:generate=true
+// +groupName=toolhive.stacklok.dev
+package v1alpha1

cmd/thv-operator/api/v1alpha1/groupversion_info.go

@@ -1,9 +1,6 @@
 // SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
-// Package v1alpha1 contains API Schema definitions for the toolhive v1alpha1 API group
-// +kubebuilder:object:generate=true
-// +groupName=toolhive.stacklok.dev
 package v1alpha1
 
 import (
@@ -12,10 +9,10 @@ import (
 )
 
 var (
-	// GroupVersion is group version used to register these objects
+	// GroupVersion is group version used to register these objects.
 	GroupVersion = schema.GroupVersion{Group: "toolhive.stacklok.dev", Version: "v1alpha1"}
 
-	// SchemeBuilder is used to add go types to the GroupVersionKind scheme
+	// SchemeBuilder is used to add go types to the GroupVersionKind scheme.
 	SchemeBuilder = &scheme.Builder{GroupVersion: GroupVersion}
 
 	// AddToScheme adds the types in this group-version to the given scheme.