feat(api): refactor v1alpha1 to parent/child model with scoped templates

api/v1alpha1/cell_types.go

@@ -17,148 +17,78 @@ limitations under the License.
 package v1alpha1
 
 import (
-	corev1 "k8s.io/api/core/v1"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
 
 // ============================================================================
 // Cell Spec (Read-only API)
 // ============================================================================
+//
+// Cell is a child CR managed by MultigresCluster.
 
-// CellSpec defines the desired state of Cell
-// This spec is populated by the MultigresCluster controller.
+// CellName is a string restricted to 63 characters for strict validation budgeting.
+// +kubebuilder:validation:MinLength=1
+// +kubebuilder:validation:MaxLength=63
+type CellName string
+
+// CellSpec defines the desired state of Cell.
+// +kubebuilder:validation:XValidation:rule="has(self.zone) != has(self.region)",message="must specify either 'zone' or 'region', but not both"
 type CellSpec struct {
 	// Name is the logical name of the cell.
-	// +kubebuilder:validation:MinLength:=1
-	// +kubebuilder:validation:MaxLength:=63
-	// +kubebuilder:validation:Pattern:="^[a-z0-9]([-a-z0-9]*[a-z0-9])?$"
+	// +kubebuilder:validation:MaxLength=63
 	Name string `json:"name"`
-
-	// Images required for this cell's components.
-	// +optional
-	Images CellImagesSpec `json:"images,omitempty"`
-
-	// MultiGateway defines the desired state of the MultiGateway deployment.
-	MultiGateway StatelessSpec `json:"multigateway"`
-
-	// MultiOrch defines the desired state of the MultiOrch deployment.
-	MultiOrch StatelessSpec `json:"multiorch"`
-
-	// GlobalTopoServer is a reference to the cluster-wide global topo server.
-	// This is always populated by the parent controller.
-	GlobalTopoServer GlobalTopoServerRefSpec `json:"globalTopoServer"`
-
-	// TopoServer defines the topology server configuration for this cell.
-	// If this is empty, the cell defaults to using the GlobalTopoServer.
-	TopoServer CellTopoServerSpec `json:"topoServer"`
-
-	// AllCells is a list of all cell names in the cluster for discovery.
-	// +optional
-	AllCells []string `json:"allCells,omitempty"`
-
-	// TopologyReconciliation defines flags for the cell controller's reconciliation logic.
-	// +optional
-	TopologyReconciliation TopologyReconciliationSpec `json:"topologyReconciliation,omitempty"`
-}
-
-// CellImagesSpec defines the images required for a Cell.
-type CellImagesSpec struct {
-	// +optional
-	// +kubebuilder:validation:MinLength=1
-	MultiGateway string `json:"multigateway,omitempty"`
+	// Zone indicates the physical availability zone.
+	// +kubebuilder:validation:MaxLength=63
+	Zone string `json:"zone,omitempty"`
+	// Region indicates the physical region.
 	// +optional
-	// +kubebuilder:validation:MinLength=1
-	MultiOrch string `json:"multiorch,omitempty"`
-}
+	// +kubebuilder:validation:MaxLength=63
+	Region string `json:"region,omitempty"`
 
-// StatelessSpec defines the desired state for a scalable, stateless component
-// like MultiAdmin, MultiOrch, or MultiGateway.
-type StatelessSpec struct {
-	// Replicas is the desired number of pods.
-	// +kubebuilder:validation:Minimum=0
-	// +optional
-	Replicas *int32 `json:"replicas,omitempty"`
+	// MultiGatewayImage is the image used for the gateway in this cell.
+	// +kubebuilder:validation:MaxLength=512
+	MultiGatewayImage string `json:"multigatewayImage"`
 
-	// Affinity defines the pod's scheduling constraints.
-	// +optional
-	Affinity *corev1.Affinity `json:"affinity,omitempty"`
-
-	// Resources defines the compute resource requirements.
-	// +optional
-	corev1.ResourceRequirements `json:"resources,omitempty"`
-}
+	// MultiGateway fully resolved config.
+	MultiGateway StatelessSpec `json:"multigateway"`
 
-// GlobalTopoServerRefSpec defines a reference to the global topo server.
-type GlobalTopoServerRefSpec struct {
-	// RootPath is the root path being used in the global topo server.
-	// +optional
-	RootPath string `json:"rootPath,omitempty"`
+	// GlobalTopoServer reference (always populated).
+	GlobalTopoServer GlobalTopoServerRef `json:"globalTopoServer"`
 
-	// ClientServiceName is the name of the etcd client service.
-	// +kubebuilder:validation:MinLength=1
+	// TopoServer defines the local topology config.
 	// +optional
-	ClientServiceName string `json:"clientServiceName,omitempty"`
-}
+	TopoServer LocalTopoServerSpec `json:"topoServer,omitempty"`
 
-// CellTopoServerSpec defines the topology server configuration for this cell.
-// Only one of External or ManagedSpec should be set.
-// If neither is set, the cell uses the top-level GlobalTopoServer.
-// TODO: Add validation when External field is uncommented
-type CellTopoServerSpec struct {
-	// External defines connection details for an unmanaged, external topo server.
+	// AllCells list for discovery.
 	// +optional
-	// External *ExternalTopoServerSpec `json:"external,omitempty"`
+	// +kubebuilder:validation:MaxItems=100
+	AllCells []CellName `json:"allCells,omitempty"`
 
-	// ManagedSpec defines the spec for a managed, cell-local topo server.
-	// If set, the Cell controller will create a child TopoServer CR.
+	// TopologyReconciliation flags.
 	// +optional
-	ManagedSpec *TopoServerSpec `json:"managedSpec,omitempty"`
+	TopologyReconciliation TopologyReconciliation `json:"topologyReconciliation,omitempty"`
 }
 
-// TopologyReconciliationSpec defines flags for the cell controller.
-type TopologyReconciliationSpec struct {
-	// RegisterCell instructs the controller to register this cell in the topology.
-	// +optional
-	RegisterCell bool `json:"registerCell,omitempty"`
-
-	// PruneTablets instructs the controller to prune old tablets from the topology.
-	// +optional
-	PruneTablets bool `json:"pruneTablets,omitempty"`
+// TopologyReconciliation defines flags for the cell controller.
+type TopologyReconciliation struct {
+	RegisterCell bool `json:"registerCell"`
+	PrunePoolers bool `json:"prunePoolers"`
 }
 
 // ============================================================================
 // CR Controller Status Specs
 // ============================================================================
 
-// CellStatus defines the observed state of Cell
+// CellStatus defines the observed state of Cell.
 type CellStatus struct {
-	// ObservedGeneration is the most recent generation observed by the controller.
-	// +optional
-	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
-
-	// Conditions represent the latest available observations of the Cell's state.
+	// Conditions represent the latest available observations.
 	// +optional
 	Conditions []metav1.Condition `json:"conditions,omitempty"`
 
-	// GatewayReplicas is the current number of MultiGateway pods.
-	// +optional
-	GatewayReplicas int32 `json:"gatewayReplicas,omitempty"`
-
-	// GatewayReadyReplicas is the number of MultiGateway pods ready to serve requests.
-	// +optional
-	GatewayReadyReplicas int32 `json:"gatewayReadyReplicas,omitempty"`
-
-	// GatewayServiceName is the name of the MultiGateway service.
-	// +optional
+	GatewayReplicas      int32 `json:"gatewayReplicas"`
+	GatewayReadyReplicas int32 `json:"gatewayReadyReplicas"`
+	// +kubebuilder:validation:MaxLength=253
 	GatewayServiceName string `json:"gatewayServiceName,omitempty"`
-
-	// MultiOrchAvailable indicates whether the MultiOrch deployment is available.
-	// +optional
-	MultiOrchAvailable metav1.ConditionStatus `json:"multiorchAvailable,omitempty"`
-
-	// TopoServerAvailable indicates whether the cell's topo server (local or global) is available.
-	// +optional
-	TopoServerAvailable metav1.ConditionStatus `json:"topoServerAvailable,omitempty"`
 }
 
 // ============================================================================
@@ -167,19 +97,10 @@ type CellStatus struct {
 
 // +kubebuilder:object:root=true
 // +kubebuilder:subresource:status
-// +kubebuilder:printcolumn:name="Status",type="string",JSONPath=".status.conditions[?(@.type=='Available')].status",description="Current availability status"
-// +kubebuilder:printcolumn:name="Gateway Ready",type="string",JSONPath=".status.gatewayReadyReplicas",description="Gateway ready replicas"
-// +kubebuilder:printcolumn:name="Gateway Total",type="string",JSONPath=".status.gatewayReplicas",description="Gateway total replicas"
-// +kubebuilder:printcolumn:name="Orch Ready",type="string",JSONPath=".status.multiorchAvailable",description="Orchestrator status"
-// +kubebuilder:printcolumn:name="Topo Ready",type="string",JSONPath=".status.topoServerAvailable",description="Topo server status"
-// +kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp"
-// +kubebuilder:rbac:groups=multigres.com,resources=cells,verbs=get;list;watch;create;update;patch;delete
-// +kubebuilder:rbac:groups=multigres.com,resources=cells/status,verbs=get;update;patch
-// +kubebuilder:rbac:groups=multigres.com,resources=cells/finalizers,verbs=update
-// +kubebuilder:rbac:groups=apps,resources=deployments,verbs=get;list;watch;create;update;patch;delete
-// +kubebuilder:rbac:groups="",resources=services,verbs=get;list;watch;create;update;patch;delete
-
-// Cell is the Schema for the Cells API
+// +kubebuilder:printcolumn:name="Gateway",type="integer",JSONPath=".status.gatewayReadyReplicas"
+// +kubebuilder:printcolumn:name="Ready",type="string",JSONPath=".status.conditions[?(@.type=='Available')].status"
+
+// Cell is the Schema for the cells API
 type Cell struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`

api/v1alpha1/celltemplate_types.go

@@ -0,0 +1,64 @@
+/*
+Copyright 2025.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package v1alpha1
+
+import (
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
+
+// ============================================================================
+// CellTemplateSpec Spec
+// ============================================================================
+
+// CellTemplateSpec defines reusable config for Cell components (Gateway, LocalTopo).
+type CellTemplateSpec struct {
+	// MultiGateway configuration.
+	// +optional
+	MultiGateway *StatelessSpec `json:"multigateway,omitempty"`
+
+	// LocalTopoServer configuration (optional).
+	// +optional
+	LocalTopoServer *LocalTopoServerSpec `json:"localTopoServer,omitempty"`
+}
+
+// ============================================================================
+// Kind Definition and registration
+// ============================================================================
+
+// +kubebuilder:object:root=true
+// +kubebuilder:resource:scope=Namespaced
+
+// CellTemplate is the Schema for the celltemplates API
+type CellTemplate struct {
+	metav1.TypeMeta   `json:",inline"`
+	metav1.ObjectMeta `json:"metadata,omitempty"`
+
+	Spec CellTemplateSpec `json:"spec,omitempty"`
+}
+
+// +kubebuilder:object:root=true
+
+// CellTemplateList contains a list of CellTemplate
+type CellTemplateList struct {
+	metav1.TypeMeta `json:",inline"`
+	metav1.ListMeta `json:"metadata,omitempty"`
+	Items           []CellTemplate `json:"items"`
+}
+
+func init() {
+	SchemeBuilder.Register(&CellTemplate{}, &CellTemplateList{})
+}

api/v1alpha1/common_types.go

@@ -0,0 +1,79 @@
+/*
+Copyright 2025.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package v1alpha1
+
+import (
+	corev1 "k8s.io/api/core/v1"
+)
+
+// ============================================================================
+// Shared Configuration Structs
+// ============================================================================
+//
+// These structs are used across multiple resources (Cluster, Templates, Children)
+// to ensure consistency in configuration shapes.
+
+// StatelessSpec defines the desired state for a scalable, stateless component
+// like MultiAdmin, MultiOrch, or MultiGateway.
+type StatelessSpec struct {
+	// Replicas is the desired number of pods.
+	// +kubebuilder:validation:Minimum=0
+	// +optional
+	Replicas *int32 `json:"replicas,omitempty"`
+
+	// Resources defines the compute resource requirements.
+	// +optional
+	Resources corev1.ResourceRequirements `json:"resources,omitempty"`
+
+	// Affinity defines the pod's scheduling constraints.
+	// +optional
+	Affinity *corev1.Affinity `json:"affinity,omitempty"`
+
+	// PodAnnotations are annotations to add to the pods.
+	// +optional
+	// +kubebuilder:validation:MaxProperties=64
+	// +kubebuilder:validation:XValidation:rule="self.all(k, size(k) < 64 && size(self[k]) < 256)",message="annotation keys must be <64 chars and values <256 chars"
+	PodAnnotations map[string]string `json:"podAnnotations,omitempty"`
+
+	// PodLabels are additional labels to add to the pods.
+	// +optional
+	// +kubebuilder:validation:MaxProperties=64
+	// +kubebuilder:validation:XValidation:rule="self.all(k, size(k) < 64 && size(self[k]) < 64)",message="label keys and values must be <64 chars"
+	PodLabels map[string]string `json:"podLabels,omitempty"`
+}
+
+// StorageSpec defines the storage configuration.
+type StorageSpec struct {
+	// Size of the persistent volume.
+	// +kubebuilder:validation:Pattern="^([0-9]+)(.+)$"
+	// +kubebuilder:validation:MaxLength=63
+	// +optional
+	Size string `json:"size,omitempty"`
+
+	// Class is the StorageClass name.
+	// +optional
+	// +kubebuilder:validation:MinLength=1
+	// +kubebuilder:validation:MaxLength=63
+	Class string `json:"class,omitempty"`
+}
+
+// ContainerConfig defines generic container configuration.
+type ContainerConfig struct {
+	// Resources defines the compute resource requirements.
+	// +optional
+	Resources corev1.ResourceRequirements `json:"resources,omitempty"`
+}