emqx · keynslug · Apr 8, 2026 · Mar 10, 2026 · Mar 11, 2026 · Mar 11, 2026
diff --git a/PROJECT b/PROJECT
@@ -15,15 +15,6 @@ resources:
   domain: emqx.io
   group: apps
   kind: EMQX
-  path: github.com/emqx/emqx-operator/api/v2
-  version: v2
-- api:
-    crdVersion: v1
-    namespaced: true
-  controller: true
-  domain: emqx.io
-  group: apps
-  kind: Rebalance
-  path: github.com/emqx/emqx-operator/api/v2beta1
-  version: v2beta1
+  path: github.com/emqx/emqx-operator/api/v3alpha1
+  version: v3alpha1
 version: "3"
diff --git a/README.md b/README.md
@@ -21,6 +21,8 @@ This operator is compatible with the following EMQX releases:
 - EMQX 5.10
 - EMQX 6.x
 
+Requires Kubernetes >= 1.27. PVC auto-cleanup for core nodes (on scale-down and CR deletion) relies on the `StatefulSetAutoDeletePVC` feature gate, which is stable and enabled by default since Kubernetes 1.32.
+
 ## Installation
 
 Here's the simplest way to install the operator.
@@ -74,8 +76,8 @@ kubectl logs -l "control-plane=controller-manager" --tail=-1 --namespace emqx-op
 ### Prerequisites
 - go version v1.22.0+
 - docker version 17.03+.
-- kubectl version v1.24+.
-- Access to a Kubernetes v1.24+ cluster.
+- kubectl version v1.27+.
+- Access to a Kubernetes v1.27+ cluster.
 
 ### To Deploy on the cluster
 **Build and push your image to the location specified by `OPERATOR_IMAGE`:**

diff --git a/api/v2beta1/groupversion_info.go b/api/v2beta1/groupversion_info.go
@@ -14,7 +14,12 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-// package v2beta1 contains API Schema definitions for the apps v2beta1 API group.
+// Package v2beta1 contains Rebalance API Schema definitions for the apps.emqx.io v2beta1 API group.
+//
+// NOTE: The Rebalance CRD is currently NOT FUNCTIONAL.
+// Type definitions are retained for future use but the CRD is not registered
+// with the scheme, not installed in the cluster, and no controller reconciles it.
+//
 // +kubebuilder:object:generate=true
 // +groupName=apps.emqx.io
 package v2beta1

diff --git a/api/v2beta1/rebalance_types.go b/api/v2beta1/rebalance_types.go
@@ -16,6 +16,14 @@ limitations under the License.
 
 package v2beta1
 
+// NOTE: The Rebalance CRD is currently NOT FUNCTIONAL.
+// The type definitions are retained for future use but the CRD is not registered
+// with the scheme and no controller reconciles it. Do not create Rebalance custom
+// resources — they will be ignored by the operator.
+//
+// To re-enable, uncomment the init() function at the bottom of this file and
+// wire up a corresponding controller in cmd/main.go.
+
 import (
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
@@ -44,6 +52,7 @@ type RebalanceList struct {
 	Items           []Rebalance `json:"items"`
 }
 
-func init() {
-	SchemeBuilder.Register(&Rebalance{}, &RebalanceList{})
-}
+// NOT FUNCTIONAL — Rebalance CRD is disabled. Uncomment to re-enable.
+// func init() {
+// 	SchemeBuilder.Register(&Rebalance{}, &RebalanceList{})
+// }
diff --git a/api/v2/const.go → api/v3alpha1/const.go b/api/v2/const.go → api/v3alpha1/const.go
@@ -14,7 +14,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-package v2
+package v3alpha1
 
 import corev1 "k8s.io/api/core/v1"
 
@@ -36,6 +36,4 @@ const (
 const (
 	// Whether the pod is responsible for DS replication
 	DSReplicationSite corev1.PodConditionType = "apps.emqx.io/ds-replication-site"
-	// https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#pod-readiness-gate
-	PodOnServing corev1.PodConditionType = "apps.emqx.io/on-serving"
 )
diff --git a/api/v2/emqx_types.go → api/v3alpha1/emqx_types.go b/api/v2/emqx_types.go → api/v3alpha1/emqx_types.go
@@ -14,7 +14,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-package v2
+package v3alpha1
 
 import (
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"

diff --git a/api/v2/emqx_types_spec.go → api/v3alpha1/emqx_types_spec.go b/api/v2/emqx_types_spec.go → api/v3alpha1/emqx_types_spec.go
@@ -14,7 +14,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-package v2
+package v3alpha1
 
 import (
 	corev1 "k8s.io/api/core/v1"
@@ -23,6 +23,7 @@ import (
 )
 
 // EMQXSpec defines the desired state of EMQX.
+// +kubebuilder:validation:XValidation:rule="!has(self.replicantTemplate) || !has(self.replicantTemplate.spec.replicas) || self.replicantTemplate.spec.replicas == 0 || self.coreTemplate.spec.replicas >= 2",message="Core-replicant clusters require at least 2 core replicas for rolling updates."
 type EMQXSpec struct {
 	// EMQX container image.
 	// More info: https://kubernetes.io/docs/concepts/containers/images
@@ -58,11 +59,11 @@ type EMQXSpec struct {
 	RevisionHistoryLimit int32 `json:"revisionHistoryLimit,omitempty"`
 
 	// Cluster upgrade strategy settings.
-	// +kubebuilder:default={type:Recreate}
+	// +kubebuilder:default={type:RollingUpdate}
 	UpdateStrategy UpdateStrategy `json:"updateStrategy,omitempty"`
 
 	// Template for Pods running EMQX core nodes.
-	// +kubebuilder:default={spec:{replicas:2}}
+	// +kubebuilder:default={spec:{replicas:2,persistentVolumeClaimSpec:{accessModes:{"ReadWriteOnce"},resources:{requests:{storage:"500Mi"}}}}}
 	CoreTemplate EMQXCoreTemplate `json:"coreTemplate,omitempty"`
 
 	// Template for Pods running EMQX replicant nodes.
@@ -118,14 +119,10 @@ type Config struct {
 
 type UpdateStrategy struct {
 	// Determines how cluster upgrade is performed.
-	// * `Recreate`: Perform blue-green upgrade.
-	// +kubebuilder:validation:Enum=Recreate
-	// +kubebuilder:default=Recreate
+	// * `RollingUpdate`: Perform a rolling upgrade, updating pods one at a time.
+	// +kubebuilder:validation:Enum=RollingUpdate
+	// +kubebuilder:default=RollingUpdate
 	Type string `json:"type,omitempty"`
-	// Number of seconds before connection evacuation starts.
-	// +kubebuilder:validation:Minimum=0
-	// +kubebuilder:default=10
-	InitialDelaySeconds int32 `json:"initialDelaySeconds,omitempty"`
 	// Evacuation strategy settings.
 	EvacuationStrategy EvacuationStrategy `json:"evacuationStrategy,omitempty"`
 }
@@ -177,8 +174,7 @@ type EMQXCoreTemplateSpec struct {
 	EMQXReplicantTemplateSpec `json:",inline"`
 
 	// PVC specification for a core node data storage.
-	// Note: this field named inconsistently, it is actually just a `PersistentVolumeClaimSpec`.
-	VolumeClaimTemplates corev1.PersistentVolumeClaimSpec `json:"volumeClaimTemplates,omitempty"`
+	PersistentVolumeClaimSpec corev1.PersistentVolumeClaimSpec `json:"persistentVolumeClaimSpec,omitempty"`
 }
 
 type EMQXReplicantTemplateSpec struct {
@@ -215,6 +211,12 @@ type EMQXReplicantTemplateSpec struct {
 	// by specifying 0. This is a mutually exclusive setting with "minAvailable".
 	// +kubebuilder:validation:XIntOrString
 	MaxUnavailable *intstr.IntOrString `json:"maxUnavailable,omitempty"`
+	// MinReadySeconds is the minimum time (seconds) a pod must be Ready before it counts as available.
+	// For core nodes this is applied to the StatefulSet (mirrors apps/v1 StatefulSetSpec.minReadySeconds);
+	// for replicants, to the ReplicaSet (mirrors apps/v1 ReplicaSetSpec.minReadySeconds).
+	// Omitted or zero matches the apps/v1 default (0).
+	// +kubebuilder:validation:Minimum=0
+	MinReadySeconds int32 `json:"minReadySeconds,omitempty"`
 
 	// Entrypoint array. Not executed within a shell.
 	// The container image's ENTRYPOINT is used if this is not provided.
@@ -285,8 +287,10 @@ type EMQXReplicantTemplateSpec struct {
 	LivenessProbe *corev1.Probe `json:"livenessProbe,omitempty"`
 	// Periodic probe of container service readiness.
 	// Container will be removed from service endpoints if the probe fails.
+	// Strongly advised to keep the current default: it takes into account ongoing node evacuations managed
+	// by the Operator as part of scaling operations and rolling updates.
 	// More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes
-	// +kubebuilder:default={initialDelaySeconds:10,periodSeconds:5,failureThreshold:12,httpGet: {path:/status, port:"dashboard"}}
+	// +kubebuilder:default={initialDelaySeconds:10,periodSeconds:5,timeoutSeconds:3,failureThreshold:1,httpGet:{path:"/api/v5/load_rebalance/availability_check", port:"dashboard"}}
 	ReadinessProbe *corev1.Probe `json:"readinessProbe,omitempty"`
 	// StartupProbe indicates that the Pod has successfully initialized.
 	// If specified, no other probes are executed until this completes successfully.
@@ -318,3 +322,17 @@ func (spec *EMQXSpec) HasReplicants() bool {
 func (s *ServiceTemplate) IsEnabled() bool {
 	return s.Enabled != nil && *s.Enabled
 }
+
+func (spec *EMQXSpec) NumCoreReplicas() int32 {
+	if spec.CoreTemplate.Spec.Replicas != nil {
+		return *spec.CoreTemplate.Spec.Replicas
+	}
+	return 1
+}
+
+func (spec *EMQXSpec) NumReplicantReplicas() int32 {
+	if spec.ReplicantTemplate != nil && spec.ReplicantTemplate.Spec.Replicas != nil {
+		return *spec.ReplicantTemplate.Spec.Replicas
+	}
+	return 0
+}
diff --git a/api/v2/emqx_types_status.go → api/v3alpha1/emqx_types_status.go b/api/v2/emqx_types_status.go → api/v3alpha1/emqx_types_status.go
@@ -14,7 +14,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-package v2
+package v3alpha1
 
 import (
 	"slices"
@@ -32,15 +32,15 @@ type EMQXStatus struct {
 	// Status of each core node in the cluster.
 	CoreNodes []EMQXNode `json:"coreNodes,omitempty"`
 	// Summary status of the set of core nodes.
-	CoreNodesStatus EMQXNodesStatus `json:"coreNodesStatus,omitempty"`
+	CoreNodesStatus CoreNodesStatus `json:"coreNodesStatus,omitempty"`
 
 	// Status of each replicant node in the cluster.
 	ReplicantNodes []EMQXNode `json:"replicantNodes,omitempty"`
 	// Summary status of the set of replicant nodes.
-	ReplicantNodesStatus EMQXNodesStatus `json:"replicantNodesStatus,omitempty"`
+	ReplicantNodesStatus ReplicantNodesStatus `json:"replicantNodesStatus,omitempty"`
 
 	// Status of active node evacuations in the cluster.
-	NodeEvacuationsStatus []NodeEvacuationStatus `json:"nodeEvacuationsStatus,omitempty"`
+	NodeEvacuations []NodeEvacuationStatus `json:"nodeEvacuations,omitempty"`
 	// Status of EMQX Durable Storage replication.
 	DSReplication DSReplicationStatus `json:"dsReplication,omitempty"`
 }
@@ -65,30 +65,40 @@ type NodeEvacuationStatus struct {
 	InitialConnections int32 `json:"initialConnections,omitempty"`
 }
 
-type EMQXNodesStatus struct {
-	// Total number of replicas.
-	Replicas int32 `json:"replicas,omitempty"`
+// CoreNodesStatus is the summary status of core nodes managed by a single StatefulSet.
+type CoreNodesStatus struct {
 	// Number of ready replicas.
-	ReadyReplicas int32 `json:"readyReplicas,omitempty"`
-	// Current revision of the respective core or replicant set.
+	ReadyReplicas int32 `json:"readyReplicas"`
+	// Number of replicas already updated to the desired pod template.
+	UpdatedReplicas int32 `json:"updatedReplicas"`
+	// Number of replicas still running the previous pod template.
+	CurrentReplicas int32 `json:"currentReplicas"`
+}
+
+// ReplicantNodesStatus is the summary status of the set of replicant nodes.
+// The multi-ReplicaSet pattern requires revision tracking at the CR level.
+type ReplicantNodesStatus struct {
+	// Number of ready replicas.
+	ReadyReplicas int32 `json:"readyReplicas"`
+	// Current revision of the replicant set.
 	CurrentRevision string `json:"currentRevision,omitempty"`
 	// Number of replicas running current revision.
-	CurrentReplicas int32 `json:"currentReplicas,omitempty"`
-	// Update revision of the respective core or replicant set.
+	CurrentReplicas int32 `json:"currentReplicas"`
+	// Update revision of the replicant set.
 	// When different from the current revision, the set is being updated.
 	UpdateRevision string `json:"updateRevision,omitempty"`
 	// Number of replicas running update revision.
-	UpdateReplicas int32 `json:"updateReplicas,omitempty"`
+	UpdateReplicas int32 `json:"updateReplicas"`
 
 	CollisionCount *int32 `json:"collisionCount,omitempty"`
 }
 
 type EMQXNode struct {
 	// Node name
-	// +kubebuilder:example="emqx@emqx-core-557c8b7684-0.emqx-headless.default.svc.cluster.local"
+	// +kubebuilder:example="emqx@emqx-core-0.emqx-headless.default.svc.cluster.local"
 	Name string `json:"name,omitempty"`
 	// Corresponding pod name
-	// +kubebuilder:example="emqx-core-557c8b7684-0"
+	// +kubebuilder:example="emqx-core-0"
 	PodName string `json:"podName,omitempty"`
 	// Node status
 	// +kubebuilder:example=running
@@ -103,9 +113,9 @@ type EMQXNode struct {
 	// +kubebuilder:example=core
 	Role string `json:"role,omitempty"`
 	// Number of MQTT sessions
-	Sessions int64 `json:"sessions,omitempty"`
+	Sessions int64 `json:"sessions"`
 	// Number of connected MQTT clients
-	Connections int64 `json:"connections,omitempty"`
+	Connections int64 `json:"connections"`
 }
 
 func (s EMQXStatus) FindNode(node string) *EMQXNode {
@@ -162,57 +172,29 @@ type DSDBReplicationStatus struct {
 }
 
 const (
-	Initialized               string = "Initialized"
 	CoreNodesProgressing      string = "CoreNodesProgressing"
-	CoreNodesReady            string = "CoreNodesReady"
 	ReplicantNodesProgressing string = "ReplicantNodesProgressing"
-	ReplicantNodesReady       string = "ReplicantNodesReady"
 	Available                 string = "Available"
 	Ready                     string = "Ready"
 )
 
-func (s *EMQXStatus) ResetConditions(reason string) {
-	conditionTypes := []string{}
-	for _, c := range s.Conditions {
-		if c.Type != Initialized && c.Status == metav1.ConditionTrue {
-			conditionTypes = append(conditionTypes, c.Type)
-		}
+func (s *EMQXStatus) SetCondition(ty string, status metav1.ConditionStatus, reason, message string) {
+	_, existing := s.GetCondition(ty)
+	if existing != nil &&
+		existing.Status == status &&
+		existing.Reason == reason &&
+		existing.Message == message {
+		return
 	}
-	for _, conditionType := range conditionTypes {
-		s.SetFalseCondition(conditionType, reason)
+	s.RemoveCondition(ty)
+	c := metav1.Condition{
+		Type:               ty,
+		Status:             status,
+		Reason:             reason,
+		Message:            message,
+		LastTransitionTime: metav1.Now(),
 	}
-}
-
-func (s *EMQXStatus) SetCondition(c metav1.Condition) {
-	s.RemoveCondition(c.Type)
-	c.LastTransitionTime = metav1.Now()
-	s.Conditions = slices.Insert(s.Conditions, 0, c)
-}
-
-func (s *EMQXStatus) SetTrueCondition(conditionType string) {
-	s.SetCondition(metav1.Condition{
-		Type:   conditionType,
-		Status: metav1.ConditionTrue,
-		Reason: conditionType,
-	})
-}
-
-func (s *EMQXStatus) SetFalseCondition(conditionType string, reason string) {
-	s.SetCondition(metav1.Condition{
-		Type:   conditionType,
-		Status: metav1.ConditionFalse,
-		Reason: reason,
-	})
-}
-
-func (s *EMQXStatus) GetLastTrueCondition() *metav1.Condition {
-	for i := range s.Conditions {
-		c := s.Conditions[i]
-		if c.Status == metav1.ConditionTrue {
-			return &c
-		}
-	}
-	return nil
+	s.Conditions = append(s.Conditions, c)
 }
 
 func (s *EMQXStatus) GetCondition(conditionType string) (int, *metav1.Condition) {

diff --git a/api/v2/groupversion_info.go → api/v3alpha1/groupversion_info.go b/api/v2/groupversion_info.go → api/v3alpha1/groupversion_info.go
@@ -14,10 +14,10 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-// package v2 contains API Schema definitions for the apps v2 API group.
+// Package v3alpha1 contains API Schema definitions for the apps.emqx.io v3alpha1 API group.
 // +kubebuilder:object:generate=true
 // +groupName=apps.emqx.io
-package v2
+package v3alpha1
 
 import (
 	"k8s.io/apimachinery/pkg/runtime/schema"
@@ -26,7 +26,7 @@ import (
 
 var (
 	// GroupVersion is group version used to register these objects.
-	GroupVersion = schema.GroupVersion{Group: "apps.emqx.io", Version: "v2"}
+	GroupVersion = schema.GroupVersion{Group: "apps.emqx.io", Version: "v3alpha1"}
 
 	// SchemeBuilder is used to add go types to the GroupVersionKind scheme.
 	SchemeBuilder = &scheme.Builder{GroupVersion: GroupVersion}

diff --git a/api/v2/labels.go → api/v3alpha1/labels.go b/api/v2/labels.go → api/v3alpha1/labels.go
@@ -14,7 +14,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-package v2
+package v3alpha1
 
 import (
 	"maps"