Add read-only reader sites

.github/kind/e2e-calico.yaml

@@ -15,6 +15,7 @@ nodes:
   - role: control-plane
   - role: worker
   - role: worker
+  - role: worker
 networking:
   # Disable kindnet so Calico can manage CNI instead.
   disableDefaultCNI: true

api/v1alpha1/site_helpers.go

@@ -68,3 +68,26 @@ func (s *MysqlFailoverGroupSpec) PeerSiteNames(name string) []string {
 	}
 	return out
 }
+
+// IsReadOnlyReader reports whether the site is a non-promotable serving reader.
+func (s SiteSpec) IsReadOnlyReader() bool {
+	return s.EffectiveRole() == SiteRoleReadOnly
+}
+
+// EffectiveMaxLagSeconds returns the group replication threshold, including
+// the API default for objects constructed outside admission.
+func (s *MysqlFailoverGroupSpec) EffectiveMaxLagSeconds() int64 {
+	if s.Replication == nil || s.Replication.MaxLagSeconds == 0 {
+		return 300
+	}
+	return s.Replication.MaxLagSeconds
+}
+
+// EffectiveReadOnlyMaxLagSeconds returns the reader endpoint threshold. An
+// explicit zero is meaningful; nil inherits the group threshold.
+func (s *MysqlFailoverGroupSpec) EffectiveReadOnlyMaxLagSeconds() int64 {
+	if s.Replication != nil && s.Replication.ReadOnlyMaxLagSeconds != nil {
+		return *s.Replication.ReadOnlyMaxLagSeconds
+	}
+	return s.EffectiveMaxLagSeconds()
+}

api/v1alpha1/site_helpers_test.go

@@ -0,0 +1,62 @@
+package v1alpha1
+
+import "testing"
+
+func TestSiteRoleHelpers(t *testing.T) {
+	tests := []struct {
+		name       string
+		role       SiteRole
+		promotable bool
+		reader     bool
+	}{
+		{name: "default", promotable: true},
+		{name: "candidate", role: SiteRolePrimaryCandidate, promotable: true},
+		{name: "dr only", role: SiteRoleDROnly},
+		{name: "reader", role: SiteRoleReadOnly, reader: true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			s := SiteSpec{Role: tt.role}
+			if got := s.IsPromotable(); got != tt.promotable {
+				t.Fatalf("IsPromotable() = %v, want %v", got, tt.promotable)
+			}
+			if got := s.IsReadOnlyReader(); got != tt.reader {
+				t.Fatalf("IsReadOnlyReader() = %v, want %v", got, tt.reader)
+			}
+		})
+	}
+}
+
+func TestPeerSiteNamesIncludesReaders(t *testing.T) {
+	s := MysqlFailoverGroupSpec{Sites: []SiteSpec{
+		{Name: "iad"}, {Name: "pdx"}, {Name: "reader", Role: SiteRoleReadOnly},
+	}}
+	got := s.PeerSiteNames("iad")
+	if len(got) != 2 || got[0] != "pdx" || got[1] != "reader" {
+		t.Fatalf("PeerSiteNames() = %v", got)
+	}
+}
+
+func TestEffectiveReplicationLag(t *testing.T) {
+	zero := int64(0)
+	tests := []struct {
+		name string
+		spec MysqlFailoverGroupSpec
+		max  int64
+		read int64
+	}{
+		{name: "defaults", max: 300, read: 300},
+		{name: "inherits", spec: MysqlFailoverGroupSpec{Replication: &ReplicationSpec{MaxLagSeconds: 42}}, max: 42, read: 42},
+		{name: "explicit zero", spec: MysqlFailoverGroupSpec{Replication: &ReplicationSpec{MaxLagSeconds: 42, ReadOnlyMaxLagSeconds: &zero}}, max: 42, read: 0},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := tt.spec.EffectiveMaxLagSeconds(); got != tt.max {
+				t.Fatalf("EffectiveMaxLagSeconds() = %d, want %d", got, tt.max)
+			}
+			if got := tt.spec.EffectiveReadOnlyMaxLagSeconds(); got != tt.read {
+				t.Fatalf("EffectiveReadOnlyMaxLagSeconds() = %d, want %d", got, tt.read)
+			}
+		})
+	}
+}

api/v1alpha1/types.go

@@ -35,6 +35,10 @@ type MysqlFailoverGroupList struct {
 // +kubebuilder:validation:XValidation:rule="self.sites.all(x, self.sites.filter(y, y.name == x.name).size() == 1)",message="spec.sites[].name must be unique"
 // +kubebuilder:validation:XValidation:rule="self.sites.filter(s, s.role == 'primary-candidate').size() >= 2",message="spec.sites must contain at least two sites with role 'primary-candidate'"
 // +kubebuilder:validation:XValidation:rule="!has(self.splitBrainPolicy) || !has(self.splitBrainPolicy.sitePriorities) || self.splitBrainPolicy.sitePriorities.all(p, self.sites.exists(s, s.name == p && s.role == 'primary-candidate'))",message="splitBrainPolicy.sitePriorities entries must match the names of sites with role 'primary-candidate'"
+// +kubebuilder:validation:XValidation:rule="!has(self.serviceTemplate) || !has(self.serviceTemplate.externalTrafficPolicy) || (has(self.serviceTemplate.type) && self.serviceTemplate.type in ['NodePort', 'LoadBalancer'])",message="serviceTemplate.externalTrafficPolicy requires serviceTemplate.type NodePort or LoadBalancer"
+// +kubebuilder:validation:XValidation:rule="self.sites.all(s, !has(s.serviceTemplate) || !has(s.serviceTemplate.externalTrafficPolicy) || ((has(s.serviceTemplate.type) ? s.serviceTemplate.type : (has(self.serviceTemplate) && has(self.serviceTemplate.type) ? self.serviceTemplate.type : 'ClusterIP')) in ['NodePort', 'LoadBalancer']))",message="site serviceTemplate.externalTrafficPolicy requires an effective type of NodePort or LoadBalancer"
+// +kubebuilder:validation:XValidation:rule="self.sites.all(s, !has(s.serviceTemplate) || !has(s.serviceTemplate.nodePort) || ((has(s.serviceTemplate.type) ? s.serviceTemplate.type : (has(self.serviceTemplate) && has(self.serviceTemplate.type) ? self.serviceTemplate.type : 'ClusterIP')) in ['NodePort', 'LoadBalancer']))",message="site serviceTemplate.nodePort requires an effective type of NodePort or LoadBalancer"
+// +kubebuilder:validation:XValidation:rule="self.sites.all(s, !has(self.serviceTemplate) || !has(self.serviceTemplate.externalTrafficPolicy) || ((has(s.serviceTemplate) && has(s.serviceTemplate.type) ? s.serviceTemplate.type : (has(self.serviceTemplate.type) ? self.serviceTemplate.type : 'ClusterIP')) in ['NodePort', 'LoadBalancer']))",message="inherited externalTrafficPolicy requires each effective site service type to be NodePort or LoadBalancer"
 type MysqlFailoverGroupSpec struct {
 	// Image is the MySQL container image. Default: mysql:9.7
 	// +kubebuilder:default="mysql:9.7"
@@ -249,6 +253,13 @@ type ReplicationSpec struct {
 	// +kubebuilder:default=300
 	// +kubebuilder:validation:Minimum=0
 	MaxLagSeconds int64 `json:"maxLagSeconds,omitempty"`
+
+	// ReadOnlyMaxLagSeconds is the maximum lag for a read-only site's
+	// client-facing endpoint. Nil inherits MaxLagSeconds; explicit zero
+	// requires the reader to be fully caught up.
+	// +optional
+	// +kubebuilder:validation:Minimum=0
+	ReadOnlyMaxLagSeconds *int64 `json:"readOnlyMaxLagSeconds,omitempty"`
 }
 
 // SiteRole describes the promotion eligibility of a site.
@@ -269,7 +280,7 @@ type ReplicationSpec struct {
 // *promotion* and *policy eligibility*; it does not exempt the site
 // from the same safety fencing that protects primary-candidate
 // losers.
-// +kubebuilder:validation:Enum=primary-candidate;dr-only
+// +kubebuilder:validation:Enum=primary-candidate;dr-only;read-only
 type SiteRole string
 
 const (
@@ -280,9 +291,14 @@ const (
 	// SiteRoleDROnly is a passive replica role: a site that follows
 	// the active primary but is never promoted automatically.
 	SiteRoleDROnly SiteRole = "dr-only"
+
+	// SiteRoleReadOnly is a serving replica that is never promoted and
+	// does not participate in core failover-group readiness.
+	SiteRoleReadOnly SiteRole = "read-only"
 )
 
 // SiteSpec defines the configuration for a single site in the failover group.
+// +kubebuilder:validation:XValidation:rule="self.role == 'read-only' || (has(self.taintNodeSelector) && has(self.lbIP))",message="taintNodeSelector and lbIP are required unless role is read-only"
 type SiteSpec struct {
 	// Name is the site identifier (e.g. "iad", "pdx", "lhr").
 	// Must be unique within spec.sites. MaxLength caps the CEL cost
@@ -306,17 +322,27 @@ type SiteSpec struct {
 	// group-scoped labels so one physical node can participate in multiple
 	// failover groups at the same site.
 	// +kubebuilder:validation:MinProperties=1
-	TaintNodeSelector map[string]string `json:"taintNodeSelector"`
+	// +optional
+	TaintNodeSelector map[string]string `json:"taintNodeSelector,omitempty"`
 
 	// LBIP is the load balancer IP for DNS failover.
 	// +kubebuilder:validation:MinLength=1
-	LBIP string `json:"lbIP"`
+	// +optional
+	LBIP string `json:"lbIP,omitempty"`
 
 	// Storage configures the persistent volume for this site.
 	Storage StorageSpec `json:"storage"`
 
 	// Resources defines the compute resources for the MySQL container.
 	Resources corev1.ResourceRequirements `json:"resources,omitempty"`
+
+	// MysqlConf overrides group-level MySQL settings for this site.
+	MysqlConf map[string]string `json:"mysqlConf,omitempty"`
+
+	// ServiceTemplate overrides the group Service template for this site's
+	// client-facing MySQL Service.
+	// +optional
+	ServiceTemplate *SiteServiceTemplate `json:"serviceTemplate,omitempty"`
 }
 
 // EffectiveRole returns the site's role, defaulting to
@@ -415,10 +441,38 @@ type ServiceTemplate struct {
 	// +kubebuilder:validation:Enum=ClusterIP;LoadBalancer;NodePort
 	Type corev1.ServiceType `json:"type,omitempty"`
 
+	// ExternalTrafficPolicy controls external traffic routing for Services
+	// whose effective type is NodePort or LoadBalancer.
+	// +optional
+	// +kubebuilder:validation:Enum=Cluster;Local
+	ExternalTrafficPolicy corev1.ServiceExternalTrafficPolicyType `json:"externalTrafficPolicy,omitempty"`
+
 	// Annotations are additional annotations applied to every Service managed by this failover group.
 	Annotations map[string]string `json:"annotations,omitempty"`
 }
 
+// SiteServiceTemplate customizes one client-facing site Service.
+type SiteServiceTemplate struct {
+	// Type overrides the group Service type.
+	// +optional
+	// +kubebuilder:validation:Enum=ClusterIP;LoadBalancer;NodePort
+	Type corev1.ServiceType `json:"type,omitempty"`
+
+	// ExternalTrafficPolicy overrides the group policy.
+	// +optional
+	// +kubebuilder:validation:Enum=Cluster;Local
+	ExternalTrafficPolicy corev1.ServiceExternalTrafficPolicyType `json:"externalTrafficPolicy,omitempty"`
+
+	// NodePort requests a specific port for this site's MySQL endpoint.
+	// +optional
+	// +kubebuilder:validation:Minimum=1
+	// +kubebuilder:validation:Maximum=65535
+	NodePort int32 `json:"nodePort,omitempty"`
+
+	// Annotations are merged over group Service annotations for this site.
+	Annotations map[string]string `json:"annotations,omitempty"`
+}
+
 // CredentialsSpec configures per-role MySQL credential management.
 // Each field references a Secret with 'username' and 'password' keys.
 // The operator creates MySQL users with role-appropriate privileges
@@ -566,8 +620,31 @@ type SiteStatus struct {
 	// DivergentTransactionCount is the number of divergent transactions.
 	// +optional
 	DivergentTransactionCount *int64 `json:"divergentTransactionCount,omitempty"`
+
+	// SourceHost is the replication source reported by MySQL.
+	// +optional
+	SourceHost string `json:"sourceHost,omitempty"`
+
+	// SourceConvergenceState reports whether this follower directly follows
+	// the confirmed active primary.
+	// +optional
+	SourceConvergenceState SourceConvergenceState `json:"sourceConvergenceState,omitempty"`
+
+	// SourceConvergenceReason is a stable machine-readable explanation.
+	// +optional
+	SourceConvergenceReason string `json:"sourceConvergenceReason,omitempty"`
 }
 
+// SourceConvergenceState describes direct-primary source convergence.
+// +kubebuilder:validation:Enum="";Converged;Pending;Blocked
+type SourceConvergenceState string
+
+const (
+	SourceConvergenceConverged SourceConvergenceState = "Converged"
+	SourceConvergencePending   SourceConvergenceState = "Pending"
+	SourceConvergenceBlocked   SourceConvergenceState = "Blocked"
+)
+
 func init() {
 	SchemeBuilder.Register(&MysqlFailoverGroup{}, &MysqlFailoverGroupList{})
 }