Creating a replication group in Valkey or Redis OSS (Cluster Mode Enabled) from scratch

You can create a Valkey or Redis OSS (cluster mode enabled) cluster (API/CLI: replication group) using the ElastiCache console, the AWS CLI, or the ElastiCache API. A Valkey or Redis OSS (cluster mode enabled) replication group has from 1 to 500 shards (API/CLI: node groups), a primary node in each shard, and up to 5 read replicas in each shard. You can create a cluster with higher number of shards and lower number of replicas totaling up to 90 nodes per cluster. This cluster configuration can range from 90 shards and 0 replicas to 15 shards and 5 replicas, which is the maximum number of replicas allowed.

The node or shard limit can be increased to a maximum of 500 per cluster if the Valkey or Redis OSS engine version is 5.0.6 or higher. For example, you can choose to configure a 500 node cluster that ranges between 83 shards (one primary and 5 replicas per shard) and 500 shards (single primary and no replicas). Make sure there are enough available IP addresses to accommodate the increase. Common pitfalls include the subnets in the subnet group have too small a CIDR range or the subnets are shared and heavily used by other clusters. For more information, see Creating a subnet group.

For versions below 5.0.6, the limit is 250 per cluster.

To request a limit increase, see AWS Service Limits and choose the limit type Nodes per cluster per instance type.

Creating a Valkey or Redis OSS (Cluster Mode Enabled) cluster (Console)

To create a Valkey or Redis OSS (cluster mode enabled) cluster, see Creating a Valkey or Redis OSS (cluster mode enabled) cluster (Console). Be sure to enable cluster mode, Cluster Mode enabled (Scale Out), and specify at least two shards and one replica node in each.

Creating a Valkey or Redis OSS (Cluster Mode Enabled) replication group from scratch (AWS CLI)

The following procedure creates a Valkey or Redis OSS (cluster mode enabled) replication group using the AWS CLI.

When you create a Valkey or Redis OSS (cluster mode enabled) replication group from scratch, you create the replication group and all its nodes with a single call to the AWS CLI create-replication-group command. Include the following parameters.

If you want to enable in-transit or at-rest encryption on this replication group, add either or both of the --transit-encryption-enabled or --at-rest-encryption-enabled parameters and meet the following conditions.

The following operation creates the Valkey or Redis OSS (cluster mode enabled) replication group sample-repl-group with three node groups/shards (--num-node-groups), each with three nodes, a primary and two read replicas (--replicas-per-node-group).

For Linux, macOS, or Unix:

aws elasticache create-replication-group \
   --replication-group-id sample-repl-group \
   --replication-group-description "Demo cluster with replicas" \
   --num-node-groups 3 \
   --replicas-per-node-group 2 \
   --cache-node-type cache.m4.large \ 
   --engine redis \   
   --security-group-ids SECURITY_GROUP_ID \    
   --cache-subnet-group-name SUBNET_GROUP_NAME>
 

For Windows:

aws elasticache create-replication-group ^
   --replication-group-id sample-repl-group ^
   --replication-group-description "Demo cluster with replicas" ^
   --num-node-groups 3 ^
   --replicas-per-node-group 2 ^
   --cache-node-type cache.m4.large ^ 
   --engine redis ^   
   --security-group-ids SECURITY_GROUP_ID ^      
   --cache-subnet-group-name SUBNET_GROUP_NAME>             
 

The preceding command generates the following output.

{
    "ReplicationGroup": {
        "Status": "creating", 
        "Description": "Demo cluster with replicas", 
        "ReplicationGroupId": "sample-repl-group", 
        "SnapshotRetentionLimit": 0, 
        "AutomaticFailover": "enabled", 
        "SnapshotWindow": "05:30-06:30", 
        "MemberClusters": [
            "sample-repl-group-0001-001", 
            "sample-repl-group-0001-002", 
            "sample-repl-group-0001-003", 
            "sample-repl-group-0002-001", 
            "sample-repl-group-0002-002", 
            "sample-repl-group-0002-003", 
            "sample-repl-group-0003-001", 
            "sample-repl-group-0003-002", 
            "sample-repl-group-0003-003"
        ], 
        "PendingModifiedValues": {}
    }
}

When you create a Valkey or Redis OSS (cluster mode enabled) replication group from scratch, you are able to configure each shard in the cluster using the --node-group-configuration parameter as shown in the following example which configures two node groups (Console: shards). The first shard has two nodes, a primary and one read replica. The second shard has three nodes, a primary and two read replicas.

The following operation creates the Valkey or Redis OSS (cluster mode enabled) replication group new-group with two node groups/shards (--num-node-groups). Unlike the preceding example, each node group is configured differently from the other node group (--node-group-configuration).

For Linux, macOS, or Unix:

aws elasticache create-replication-group \
  --replication-group-id new-group \
  --replication-group-description "Sharded replication group" \
  --engine redis \    
  --snapshot-retention-limit 8 \
  --cache-node-type cache.m4.medium \
  --num-node-groups 2 \
  --node-group-configuration \
      "ReplicaCount=1,Slots=0-8999,PrimaryAvailabilityZone='us-east-1c',ReplicaAvailabilityZones='us-east-1b'" \
      "ReplicaCount=2,Slots=9000-16383,PrimaryAvailabilityZone='us-east-1a',ReplicaAvailabilityZones='us-east-1a','us-east-1c'"

For Windows:

aws elasticache create-replication-group ^
  --replication-group-id new-group ^
  --replication-group-description "Sharded replication group" ^
  --engine redis ^    
  --snapshot-retention-limit 8 ^
  --cache-node-type cache.m4.medium ^
  --num-node-groups 2 ^
  --node-group-configuration \
      "ReplicaCount=1,Slots=0-8999,PrimaryAvailabilityZone='us-east-1c',ReplicaAvailabilityZones='us-east-1b'" \
      "ReplicaCount=2,Slots=9000-16383,PrimaryAvailabilityZone='us-east-1a',ReplicaAvailabilityZones='us-east-1a','us-east-1c'"

The preceding operation generates the following output.

{
    "ReplicationGroup": {
        "Status": "creating", 
        "Description": "Sharded replication group", 
        "ReplicationGroupId": "rc-rg", 
        "SnapshotRetentionLimit": 8, 
        "AutomaticFailover": "enabled", 
        "SnapshotWindow": "10:00-11:00", 
        "MemberClusters": [
            "rc-rg-0001-001", 
            "rc-rg-0001-002", 
            "rc-rg-0002-001", 
            "rc-rg-0002-002", 
            "rc-rg-0002-003"
        ], 
        "PendingModifiedValues": {}
    }
}

For additional information and parameters you might want to use, see the AWS CLI topic create-replication-group.

Creating a replication group in Valkey or Redis OSS (Cluster Mode Enabled) from scratch (ElastiCache API)

The following procedure creates a Valkey or Redis OSS (cluster mode enabled) replication group using the ElastiCache API.

When you create a Valkey or Redis OSS (cluster mode enabled) replication group from scratch, you create the replication group and all its nodes with a single call to the ElastiCache API CreateReplicationGroup operation. Include the following parameters.

If you want to enable in-transit or at-rest encryption on this replication group, add either or both of the TransitEncryptionEnabled=true or AtRestEncryptionEnabled=true parameters and meet the following conditions.

Line breaks are added for ease of reading.

https://elasticache.us-west-2.amazonaws.com/
   ?Action=CreateReplicationGroup 
   &CacheNodeType=cache.m4.large
   &CacheParemeterGroup=default.redis6.xcluster.on
   &Engine=redis
   &EngineVersion=6.0
   &NumNodeGroups=3
   &ReplicasPerNodeGroup=2
   &ReplicationGroupDescription=test%20group
   &ReplicationGroupId=myReplGroup
   &Version=2015-02-02
   &SignatureVersion=4
   &SignatureMethod=HmacSHA256
   &Timestamp=20150202T192317Z
   &X-Amz-Credential=<credential>

For additional information and parameters you might want to use, see the ElastiCache API topic CreateReplicationGroup.