feat: new cluster topology and component version API (#6582)

PROJECT

@@ -200,7 +200,6 @@ resources:
   version: v1alpha1
 - api:
     crdVersion: v1
-    namespaced: true
   controller: true
   domain: kubeblocks.io
   group: apps
@@ -226,11 +225,22 @@ resources:
     webhookVersion: v1
 - api:
     crdVersion: v1
-    namespaced: true
   controller: true
   domain: kubeblocks.io
   group: apps
   kind: OpsDefinition
   path: github.com/apecloud/kubeblocks/apis/apps/v1alpha1
   version: v1alpha1
+- api:
+    crdVersion: v1
+  controller: true
+  domain: kubeblocks.io
+  group: apps
+  kind: ComponentVersion
+  path: github.com/apecloud/kubeblocks/apis/apps/v1alpha1
+  version: v1alpha1
+  webhooks:
+    defaulting: true
+    validation: true
+    webhookVersion: v1
 version: "3"

apis/apps/v1alpha1/cluster_types.go

@@ -48,9 +48,17 @@ type ClusterSpec struct {
 	//
 	// +kubebuilder:validation:MaxLength=63
 	// +kubebuilder:validation:Pattern:=`^[a-z0-9]([a-z0-9\.\-]*[a-z0-9])?$`
+	// +kubebuilder:deprecatedversion:warning="This field has been deprecated since 0.9.0"
 	// +optional
 	ClusterVersionRef string `json:"clusterVersionRef,omitempty"`
 
+	// Topology specifies the topology to use for the cluster. If not specified, the default topology will be used.
+	// Cannot be updated.
+	//
+	// +kubebuilder:validation:MaxLength=32
+	// +optional
+	Topology string `json:"topology,omitempty"`
+
 	// Specifies the cluster termination policy.
 	//
 	// - DoNotTerminate will block delete operation.
@@ -100,50 +108,57 @@ type ClusterSpec struct {
 	// +optional
 	Tolerations []corev1.Toleration `json:"tolerations,omitempty"`
 
+	// Cluster backup configuration.
+	//
+	// +optional
+	Backup *ClusterBackup `json:"backup,omitempty"`
+
 	// !!!!! The following fields may be deprecated in subsequent versions, please DO NOT rely on them for new requirements.
 
 	// Describes how pods are distributed across node.
 	//
+	// +kubebuilder:deprecatedversion:warning="This field has been deprecated since 0.9.0"
 	// +optional
 	Tenancy TenancyType `json:"tenancy,omitempty"`
 
 	// Describes the availability policy, including zone, node, and none.
 	//
+	// +kubebuilder:deprecatedversion:warning="This field has been deprecated since 0.9.0"
 	// +optional
 	AvailabilityPolicy AvailabilityPolicyType `json:"availabilityPolicy,omitempty"`
 
 	// Specifies the replicas of the first componentSpec, if the replicas of the first componentSpec is specified,
 	// this value will be ignored.
 	//
+	//+kubebuilder:deprecatedversion:warning="This field has been deprecated since 0.9.0"
 	// +optional
 	Replicas *int32 `json:"replicas,omitempty"`
 
 	// Specifies the resources of the first componentSpec, if the resources of the first componentSpec is specified,
 	// this value will be ignored.
 	//
+	// +kubebuilder:deprecatedversion:warning="This field has been deprecated since 0.9.0"
 	// +optional
 	Resources ClusterResources `json:"resources,omitempty"`
 
 	// Specifies the storage of the first componentSpec, if the storage of the first componentSpec is specified,
 	// this value will be ignored.
 	//
+	// +kubebuilder:deprecatedversion:warning="This field has been deprecated since 0.9.0"
 	// +optional
 	Storage ClusterStorage `json:"storage,omitempty"`
 
 	// The configuration of monitor.
 	//
+	// +kubebuilder:deprecatedversion:warning="This field has been deprecated since 0.9.0"
 	// +optional
 	Monitor ClusterMonitor `json:"monitor,omitempty"`
 
 	// The configuration of network.
 	//
+	// +kubebuilder:deprecatedversion:warning="This field has been deprecated since 0.9.0"
 	// +optional
 	Network *ClusterNetwork `json:"network,omitempty"`
-
-	// Cluster backup configuration.
-	//
-	// +optional
-	Backup *ClusterBackup `json:"backup,omitempty"`
 }
 
 type ClusterBackup struct {
@@ -363,7 +378,6 @@ type ShardingSpec struct {
 }
 
 // ClusterComponentSpec defines the specifications for a cluster component.
-// +kubebuilder:validation:XValidation:rule="has(self.componentDefRef) || has(self.componentDef)",message="either componentDefRef or componentDef should be provided"
 // TODO +kubebuilder:validation:XValidation:rule="!has(oldSelf.componentDefRef) || has(self.componentDefRef)", message="componentDefRef is required once set"
 // TODO +kubebuilder:validation:XValidation:rule="!has(oldSelf.componentDef) || has(self.componentDef)", message="componentDef is required once set"
 type ClusterComponentSpec struct {
@@ -382,18 +396,27 @@ type ClusterComponentSpec struct {
 	// +kubebuilder:validation:MaxLength=22
 	// +kubebuilder:validation:Pattern:=`^[a-z]([a-z0-9\-]*[a-z0-9])?$`
 	// TODO +kubebuilder:validation:XValidation:rule="self == oldSelf",message="componentDefRef is immutable"
+	// +kubebuilder:deprecatedversion:warning="This field has been deprecated since 0.9.0, consider using the ComponentDef instead"
 	// +optional
 	ComponentDefRef string `json:"componentDefRef,omitempty"`
 
 	// References the name of the ComponentDefinition.
 	// If both componentDefRef and componentDef are provided, the componentDef will take precedence over componentDefRef.
 	//
-	// +kubebuilder:validation:MaxLength=22
+	// +kubebuilder:validation:MaxLength=64
 	// +kubebuilder:validation:Pattern:=`^[a-z0-9]([a-z0-9\.\-]*[a-z0-9])?$`
-	// TODO +kubebuilder:validation:XValidation:rule="self == oldSelf",message="componentDef is immutable"
 	// +optional
 	ComponentDef string `json:"componentDef,omitempty"`
 
+	// ServiceVersion specifies the version of the service provisioned by the component.
+	// The version should follow the syntax and semantics of the "Semantic Versioning" specification (http://semver.org/).
+	// If not explicitly specified, the version defined in the referenced topology will be used.
+	// If no version is specified in the topology, the latest available version will be used.
+	//
+	// +kubebuilder:validation:MaxLength=32
+	// +optional
+	ServiceVersion string `json:"serviceVersion,omitempty"`
+
 	// References the class defined in ComponentClassDefinition.
 	//
 	// +kubebuilder:deprecatedversion:warning="Due to the lack of practical use cases, this field is deprecated from KB 0.9.0."
@@ -464,11 +487,13 @@ type ClusterComponentSpec struct {
 
 	// Services expose endpoints that can be accessed by clients.
 	//
+	// +kubebuilder:deprecatedversion:warning="This field has been deprecated since 0.9.0, consider using the $.Spec.ClusterService instead"
 	// +optional
 	Services []ClusterComponentService `json:"services,omitempty"`
 
 	// Defines the strategy for switchover and failover when workloadType is Replication.
 	//
+	// +kubebuilder:deprecatedversion:warning="This field has been deprecated since 0.9.0"
 	// +optional
 	SwitchPolicy *ClusterSwitchPolicy `json:"switchPolicy,omitempty"`
 
@@ -490,6 +515,7 @@ type ClusterComponentSpec struct {
 	// Defines the update strategy for the component.
 	// Not supported.
 	//
+	// +kubebuilder:deprecatedversion:warning="This field has been deprecated since 0.9.0"
 	// +optional
 	UpdateStrategy *UpdateStrategy `json:"updateStrategy,omitempty"`
 

apis/apps/v1alpha1/clusterdefinition_types.go

@@ -33,17 +33,18 @@ type ClusterDefinitionSpec struct {
 	//
 	// +kubebuilder:validation:MaxLength=24
 	// +kubebuilder:validation:Pattern:=`^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$`
+	// +kubebuilder:deprecatedversion:warning="This field has been deprecated since 0.9.0"
 	// +optional
 	Type string `json:"type,omitempty"`
 
 	// Provides the definitions for the cluster components.
 	//
-	// +kubebuilder:validation:Required
-	// +kubebuilder:validation:MinItems=1
+	// +kubebuilder:deprecatedversion:warning="This field has been deprecated since 0.9.0"
 	// +patchMergeKey=name
 	// +patchStrategy=merge,retainKeys
 	// +listType=map
 	// +listMapKey=name
+	// +optional
 	ComponentDefs []ClusterComponentDefinition `json:"componentDefs" patchStrategy:"merge,retainKeys" patchMergeKey:"name"`
 
 	// Connection credential template used for creating a connection credential secret for cluster objects.
@@ -64,8 +65,85 @@ type ClusterDefinitionSpec struct {
 	//    `{"name": "mysql", "targetPort": "mysqlContainerPort", "port": 3306}`, and `$(SVC_PORT_mysql)` in the
 	//    connection credential value is 3306.
 	//
+	// +kubebuilder:deprecatedversion:warning="This field has been deprecated since 0.9.0"
 	// +optional
 	ConnectionCredential map[string]string `json:"connectionCredential,omitempty"`
+
+	// Topologies represents the different topologies within the cluster.
+	//
+	// +kubebuilder:validation:MinItems=1
+	// +kubebuilder:validation:MaxItems=128
+	// +optional
+	Topologies []ClusterTopology `json:"topologies,omitempty"`
+}
+
+// ClusterTopology represents the definition for a specific cluster topology.
+type ClusterTopology struct {
+	// Name is the unique identifier for the cluster topology.
+	// Cannot be updated.
+	//
+	// +kubebuilder:validation:Required
+	// +kubebuilder:validation:MaxLength=32
+	Name string `json:"name"`
+
+	// Components specifies the components in the topology.
+	//
+	// +kubebuilder:validation:Required
+	// +kubebuilder:validation:MinItems=1
+	// +kubebuilder:validation:MaxItems=128
+	Components []ClusterTopologyComponent `json:"components"`
+
+	// Orders defines the orders of components within the topology.
+	//
+	// +optional
+	Orders *ClusterTopologyOrders `json:"orders,omitempty"`
+
+	// Default indicates whether this topology is the default configuration.
+	//
+	// +optional
+	Default bool `json:"default,omitempty"`
+}
+
+// ClusterTopologyComponent defines a component within a cluster topology.
+type ClusterTopologyComponent struct {
+	// Name defines the name of the component.
+	// This name is also part of Service DNS name, following IANA Service Naming rules.
+	// Cannot be updated.
+	//
+	// +kubebuilder:validation:Required
+	// +kubebuilder:validation:MaxLength=16
+	// +kubebuilder:validation:Pattern:=`^[a-z]([a-z0-9\-]*[a-z0-9])?$`
+	Name string `json:"name"`
+
+	// CompDef specifies the component definition to use, either as a specific name or a name prefix.
+	// Cannot be updated.
+	//
+	// +kubebuilder:validation:Required
+	// +kubebuilder:validation:MaxLength=64
+	CompDef string `json:"compDef"`
+}
+
+// ClusterTopologyOrders defines the orders for components within a topology.
+type ClusterTopologyOrders struct {
+	// StartupOrder defines the order in which components should be started in the cluster.
+	// Components with the same order can be listed together, separated by commas.
+	//
+	// +optional
+	StartupOrder []string `json:"startupOrder,omitempty"`
+
+	// ShutdownOrder defines the order in which components should be shut down in the cluster.
+	// Components with the same order can be listed together, separated by commas.
+	//
+	// +optional
+	ShutdownOrder []string `json:"shutdownOrder,omitempty"`
+
+	// UpdateOrder defines the order in which components should be updated in the cluster.
+	// Components with the same order can be listed together, separated by commas.
+	//
+	// +optional
+	UpdateOrder []string `json:"updateOrder,omitempty"`
+
+	// TODO: upgrade order?
 }
 
 // SystemAccountSpec specifies information to create system accounts.
@@ -208,6 +286,11 @@ type ProvisionStatements struct {
 
 // ClusterDefinitionStatus defines the observed state of ClusterDefinition
 type ClusterDefinitionStatus struct {
+	// Represents the most recent generation observed for this ClusterDefinition.
+	//
+	// +optional
+	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
+
 	// Specifies the current phase of the ClusterDefinition. Valid values are `empty`, `Available`, `Unavailable`.
 	// When `Available`, the ClusterDefinition is ready and can be referenced by related objects.
 	Phase Phase `json:"phase,omitempty"`
@@ -217,10 +300,15 @@ type ClusterDefinitionStatus struct {
 	// +optional
 	Message string `json:"message,omitempty"`
 
-	// Represents the most recent generation observed for this ClusterDefinition.
+	// Topologies this ClusterDefinition supported.
 	//
 	// +optional
-	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
+	Topologies string `json:"topologies,omitempty"`
+
+	// The service references declared by this ClusterDefinition.
+	//
+	// +optional
+	ServiceRefs string `json:"serviceRefs,omitempty"`
 }
 
 func (r ClusterDefinitionStatus) GetTerminalPhases() []Phase {
@@ -1085,13 +1173,18 @@ type GVKResource struct {
 	Selector map[string]string `json:"selector,omitempty"`
 }
 
+// TODO(API):
+//  1. how to display the aggregated topologies and its service references line by line?
+//  2. the services and versions supported
+
 // +genclient
 // +genclient:nonNamespaced
 // +k8s:openapi-gen=true
 // +kubebuilder:object:root=true
 // +kubebuilder:subresource:status
 // +kubebuilder:resource:categories={kubeblocks},scope=Cluster,shortName=cd
-// +kubebuilder:printcolumn:name="MAIN-COMPONENT-NAME",type="string",JSONPath=".spec.componentDefs[0].name",description="main component names"
+// +kubebuilder:printcolumn:name="Topologies",type="string",JSONPath=".status.topologies",description="topologies"
+// +kubebuilder:printcolumn:name="ServiceRefs",type="string",JSONPath=".status.serviceRefs",description="service references"
 // +kubebuilder:printcolumn:name="STATUS",type="string",JSONPath=".status.phase",description="status phase"
 // +kubebuilder:printcolumn:name="AGE",type="date",JSONPath=".metadata.creationTimestamp"
 

apis/apps/v1alpha1/clusterversion_types.go

@@ -154,6 +154,7 @@ type VersionsContext struct {
 // +kubebuilder:printcolumn:name="CLUSTER-DEFINITION",type="string",JSONPath=".spec.clusterDefinitionRef",description="ClusterDefinition referenced by cluster."
 // +kubebuilder:printcolumn:name="STATUS",type="string",JSONPath=".status.phase",description="status phase"
 // +kubebuilder:printcolumn:name="AGE",type="date",JSONPath=".metadata.creationTimestamp"
+// +kubebuilder:deprecatedversion:warning="The ClusterVersion CRD has been deprecated since 0.9.0"
 
 // ClusterVersion is the Schema for the ClusterVersions API
 type ClusterVersion struct {

apis/apps/v1alpha1/component_types.go

@@ -32,8 +32,16 @@ type ComponentSpec struct {
 	// Specifies the name of the referenced ComponentDefinition.
 	//
 	// +kubebuilder:validation:Required
+	// +kubebuilder:validation:MaxLength=64
 	CompDef string `json:"compDef"`
 
+	// ServiceVersion specifies the version of the service provisioned by the component.
+	// The version should follow the syntax and semantics of the "Semantic Versioning" specification (http://semver.org/).
+	//
+	// +kubebuilder:validation:MaxLength=32
+	// +optional
+	ServiceVersion string `json:"serviceVersion,omitempty"`
+
 	// References the class defined in ComponentClassDefinition.
 	//
 	// +kubebuilder:deprecatedversion:warning="Due to the lack of practical use cases, this field is deprecated from KB 0.9.0."

apis/apps/v1alpha1/componentdefinition_types.go

@@ -80,7 +80,8 @@ type ComponentDefinitionSpec struct {
 	ServiceKind string `json:"serviceKind,omitempty"`
 
 	// Specifies the version of the well-known service that the component provides.
-	// This field is immutable.
+	// The version should follow the syntax and semantics of the "Semantic Versioning" specification (http://semver.org/).
+	// Cannot be updated.
 	//
 	// +kubebuilder:validation:MaxLength=32
 	// +optional