Add Cluster Mode support to ReplicationGroup

apis/v1alpha1/ack-generate-metadata.yaml

@@ -1,13 +1,13 @@
 ack_generate_info:
-  build_date: "2026-03-12T18:06:31Z"
+  build_date: "2026-03-17T18:45:48Z"
   build_hash: 5ac6c79fbc941c426d8b70cba768820fc9296542
-  go_version: go1.25.7
+  go_version: go1.26.1
   version: v0.58.0
-api_directory_checksum: 614ace2137dab4d515a00eaa896fe9a710e49449
+api_directory_checksum: a56f62ae21c741a76aa16e65cc5cf097210f3cef
 api_version: v1alpha1
 aws_sdk_go_version: v1.41.0
 generator_config_info:
-  file_checksum: 8b64d30e8ebf1c16f3b1445206074eb6451279b5
+  file_checksum: b2600b920ae26c695349e4c8fc04e7d6a27d287f
   original_file_name: generator.yaml
 last_modification:
   reason: API generation

apis/v1alpha1/generator.yaml

@@ -155,6 +155,9 @@ resources:
         references:
           resource: CacheSubnetGroup
           path: Spec.CacheSubnetGroupName
+      ClusterMode:
+        late_initialize:
+          skip_incomplete_check: {}
       SecurityGroupIDs:
         references:
           resource: SecurityGroup
@@ -472,10 +475,10 @@ ignore:
     - CreateReplicationGroupOutput.ReplicationGroup.TransitEncryptionMode
     - CreateReplicationGroupInput.TransitEncryptionMode
     - ModifyReplicationGroupOutput.ReplicationGroup.PendingModifiedValues.TransitEncryptionMode
-    - CreateReplicationGroupOutput.ReplicationGroup.ClusterMode
-    - CreateReplicationGroupOutput.ReplicationGroup.PendingModifiedValues.ClusterMode
-    - CreateReplicationGroupInput.ClusterMode
-    - ModifyReplicationGroupOutput.ReplicationGroup.ClusterMode
-    - ModifyReplicationGroupOutput.ReplicationGroup.PendingModifiedValues.ClusterMode
+    #- CreateReplicationGroupOutput.ReplicationGroup.ClusterMode
+    #- CreateReplicationGroupOutput.ReplicationGroup.PendingModifiedValues.ClusterMode
+    #- CreateReplicationGroupInput.ClusterMode
+    #- ModifyReplicationGroupOutput.ReplicationGroup.ClusterMode
+    #- ModifyReplicationGroupOutput.ReplicationGroup.PendingModifiedValues.ClusterMode
     - Subnet.SupportedNetworkTypes
     - CreateReplicationGroupInput.ServerlessCacheSnapshotName

config/crd/bases/elasticache.services.k8s.aws_replicationgroups.yaml

@@ -224,6 +224,17 @@ spec:
                         type: string
                     type: object
                 type: object
+              clusterMode:
+                description: |-
+                  Enabled or Disabled. To modify cluster mode from Disabled to Enabled, you
+                  must first set the cluster mode to Compatible. Compatible mode allows your
+                  Valkey or Redis OSS clients to connect using both cluster mode enabled and
+                  cluster mode disabled. After you migrate all Valkey or Redis OSS clients
+                  to use cluster mode enabled, you can then complete cluster mode configuration
+                  and set the cluster mode to Enabled.
+
+                  Cluster mode configuration can only be changed from cluster mode disabled to cluster mode enabled. Reverting this configuration is not possible.
+                type: string
               dataTieringEnabled:
                 description: |-
                   Enables data tiering. Data tiering is only supported for replication groups
@@ -856,6 +867,8 @@ spec:
                     type: string
                   automaticFailoverStatus:
                     type: string
+                  clusterMode:
+                    type: string
                   logDeliveryConfigurations:
                     items:
                       description: The log delivery configurations being modified

documentation.yaml

@@ -0,0 +1,6 @@
+resources:
+  ReplicationGroup:
+    fields:
+      ClusterMode:
+        append: |
+          Cluster mode configuration can only be changed from cluster mode disabled to cluster mode enabled. Reverting this configuration is not possible.

generator.yaml

@@ -155,6 +155,9 @@ resources:
         references:
           resource: CacheSubnetGroup
           path: Spec.CacheSubnetGroupName
+      ClusterMode:
+        late_initialize:
+          skip_incomplete_check: {}
       SecurityGroupIDs:
         references:
           resource: SecurityGroup
@@ -472,10 +475,10 @@ ignore:
     - CreateReplicationGroupOutput.ReplicationGroup.TransitEncryptionMode
     - CreateReplicationGroupInput.TransitEncryptionMode
     - ModifyReplicationGroupOutput.ReplicationGroup.PendingModifiedValues.TransitEncryptionMode
-    - CreateReplicationGroupOutput.ReplicationGroup.ClusterMode
-    - CreateReplicationGroupOutput.ReplicationGroup.PendingModifiedValues.ClusterMode
-    - CreateReplicationGroupInput.ClusterMode
-    - ModifyReplicationGroupOutput.ReplicationGroup.ClusterMode
-    - ModifyReplicationGroupOutput.ReplicationGroup.PendingModifiedValues.ClusterMode
+    #- CreateReplicationGroupOutput.ReplicationGroup.ClusterMode
+    #- CreateReplicationGroupOutput.ReplicationGroup.PendingModifiedValues.ClusterMode
+    #- CreateReplicationGroupInput.ClusterMode
+    #- ModifyReplicationGroupOutput.ReplicationGroup.ClusterMode
+    #- ModifyReplicationGroupOutput.ReplicationGroup.PendingModifiedValues.ClusterMode
     - Subnet.SupportedNetworkTypes
     - CreateReplicationGroupInput.ServerlessCacheSnapshotName

helm/crds/elasticache.services.k8s.aws_replicationgroups.yaml

@@ -224,6 +224,17 @@ spec:
                         type: string
                     type: object
                 type: object
+              clusterMode:
+                description: |-
+                  Enabled or Disabled. To modify cluster mode from Disabled to Enabled, you
+                  must first set the cluster mode to Compatible. Compatible mode allows your
+                  Valkey or Redis OSS clients to connect using both cluster mode enabled and
+                  cluster mode disabled. After you migrate all Valkey or Redis OSS clients
+                  to use cluster mode enabled, you can then complete cluster mode configuration
+                  and set the cluster mode to Enabled.
+
+                  Cluster mode configuration can only be changed from cluster mode disabled to cluster mode enabled. Reverting this configuration is not possible.
+                type: string
               dataTieringEnabled:
                 description: |-
                   Enables data tiering. Data tiering is only supported for replication groups
@@ -856,6 +867,8 @@ spec:
                     type: string
                   automaticFailoverStatus:
                     type: string
+                  clusterMode:
+                    type: string
                   logDeliveryConfigurations:
                     items:
                       description: The log delivery configurations being modified

pkg/resource/replication_group/hooks.go

@@ -537,15 +537,26 @@ func (rm *resourceManager) CustomModifyReplicationGroup(
 	}
 
 	// Order of operations when diffs map to multiple updates APIs:
-	// 1. When automaticFailoverEnabled differs:
+	// 1. ClusterMode must be transitioned before shard/replica scaling,
+	//    because a CMD cluster cannot have multiple shards. The cluster
+	//    must reach CME before scaling operations are valid.
+	// 2. When automaticFailoverEnabled differs:
 	//		if automaticFailoverEnabled == false; do nothing in this custom logic, let the modify execute first.
 	// 		else if automaticFailoverEnabled == true then following logic should execute first.
-	// 2. When multiAZ differs
+	// 3. When multiAZ differs
 	// 		if multiAZ = true  then below is fine.
 	// 		else if multiAZ = false ; do nothing in custom logic, let the modify execute.
-	// 3. updateReplicaCount() is invoked Before updateShardConfiguration()
+	// 4. updateReplicaCount() is invoked Before updateShardConfiguration()
 	//		because both accept availability zones, however the number of
 	//		values depend on replica count.
+
+	// ClusterMode changes are prioritized above scaling operations because
+	// shard scaling requires cluster mode enabled. We also isolate ClusterMode
+	// into its own API call since it cannot be combined with most other parameters.
+	if delta.DifferentAt("Spec.ClusterMode") && desired.ko.Spec.ClusterMode != nil {
+		return rm.modifyClusterMode(ctx, desired, delta)
+	}
+
 	if desired.ko.Spec.AutomaticFailoverEnabled != nil && *desired.ko.Spec.AutomaticFailoverEnabled == false {
 		latestAutomaticFailoverEnabled := latest.ko.Status.AutomaticFailover != nil && *latest.ko.Status.AutomaticFailover == "enabled"
 		if latestAutomaticFailoverEnabled != *desired.ko.Spec.AutomaticFailoverEnabled {
@@ -638,6 +649,36 @@ func (rm *resourceManager) modifyReplicationGroup(
 	return nil, nil
 }
 
+// modifyClusterMode sends an isolated ModifyReplicationGroup API call
+// containing only ClusterMode (and optionally CacheParameterGroupName).
+// ClusterMode changes cannot be combined with most other parameters.
+func (rm *resourceManager) modifyClusterMode(
+	ctx context.Context,
+	desired *resource,
+	delta *ackcompare.Delta,
+) (*resource, error) {
+	input := &svcsdk.ModifyReplicationGroupInput{}
+	input.ApplyImmediately = aws.Bool(true)
+	if desired.ko.Spec.ReplicationGroupID != nil {
+		input.ReplicationGroupId = desired.ko.Spec.ReplicationGroupID
+	}
+	input.ClusterMode = svcsdktypes.ClusterMode(*desired.ko.Spec.ClusterMode)
+
+	// CacheParameterGroupName is allowed alongside ClusterMode
+	if delta.DifferentAt("Spec.CacheParameterGroupName") && desired.ko.Spec.CacheParameterGroupName != nil {
+		input.CacheParameterGroupName = desired.ko.Spec.CacheParameterGroupName
+	}
+
+	resp, respErr := rm.sdkapi.ModifyReplicationGroup(ctx, input)
+	rm.metrics.RecordAPICall("UPDATE", "ModifyReplicationGroup", respErr)
+	if respErr != nil {
+		rm.log.V(1).Info("Error during ModifyReplicationGroup (ClusterMode)", "error", respErr)
+		return nil, respErr
+	}
+
+	return rm.setReplicationGroupOutput(ctx, desired, resp.ReplicationGroup)
+}
+
 // replicaConfigurationsDifference returns
 // positive number if desired replica count is greater than latest replica count
 // negative number if desired replica count is less than latest replica count
@@ -1388,6 +1429,13 @@ func modifyDelta(
 		}
 	}
 
+	// if the user did not specify a CacheParameterGroupName, let AWS manage it
+	if delta.DifferentAt("Spec.CacheParameterGroupName") {
+		if desired.ko.Spec.CacheParameterGroupName == nil && latest.ko.Spec.CacheParameterGroupName != nil {
+			common.RemoveFromDelta(delta, "Spec.CacheParameterGroupName")
+		}
+	}
+
 	// note that the comparison is actually done between desired.Spec.LogDeliveryConfigurations and
 	// the last requested configurations saved in annotations (as opposed to latest.Spec.LogDeliveryConfigurations)
 	if logDeliveryRequiresUpdate(desired) {