AWS ElastiCache for Redis Cluster vs Replication group

I'm quite confused from the terminology of AWS ElastiCache with regards to clusters, replication groups, etc.

Let me start describing what I know and the confusion will emerge:
Let's begin with the components of ElastiCache described in ElastiCache components and features

So we have a node which is the smallest unit in the system. A node is a chunk of compute and memory capacity. Each node runs an instance of the engine and version chosen in the creation.

Then we have the shard, which is a grouping of one to six nodes. Redis (cluster mode disbaled) has always one shard, with one node being the primary node, and the rest are replicas.

Then we have the cluster, which is one or more shards.

Now a cluster may be cluster-mode disabled, in which the cluster has only one shard, and cluster-mode enabled, where we have more than one shard.

Up to here everything is great, until I've tried to create an ElastiCache for Redis cluster using Terraform.

So with terraform, we use the aws_elasticache_replication_group resource in order to create a cluster-mode disabled multi node cluster. So if I want to have a single shard with one read/write primary node and 2 replica nodes, I need to use this resource.

In contrast, in order to create a single-node cluster, I can use the aws_elasticache_cluster resource.

When trying to run the Terraform configuration, I've got the error:

 Error: creating ElastiCache Replication Group (my-redis-cluster): AccessDenied: User: arn:aws:iam::xxx:user/bob
 is not authorized to perform: elasticache:CreateReplicationGroup on resource: arn:aws:elasticache:us-east-1:xxx:replicationgroup:my-redis-cluster 
with an explicit deny in a service control policy

Since I could, using the AWS Console, create such cluster exactly, I didn't understand what the problem is.

During investigation, I found that there are two API actions in the API reference: CreateReplicatioGroup and CreateCacheCluster.

In the page of CreateReplicationGroup stated:
> A Redis (cluster mode disabled) replication group is a collection of clusters, where one of the clusters is a read/write primary and the others are read-only replicas. Writes to the primary are asynchronously propagated to the replicas.

Now the confusion: What does it mean that it's a collection of "clusters"? From what we said above, a cluster is the top-level entity, which contains one/more shards, which in turn contain one/more nodes.

Now the confusion increases when I did create this Terraform resource, and then in the AWS Console I saw that I do have only one cluster.

So, can someone clarify what exactly the term "cluster" mean? What is this replication group thing? And why these are 2 separate Actions in the API?

Thank you.

Before I jump into clarifying the terminology, let’s address the IAM error you mentioned. This error is likely related to an explicit Deny statement in user’s attached IAM policy. You can read more about how to troubleshoot these kind of errors in the IAM documentation.

>A Redis (cluster mode disabled) replication group is a collection of clusters, where one of the clusters is a read/write primary and the others are read-only replicas. Writes to the primary are asynchronously propagated to the replicas.

should probably be re-worded to:

>A Redis (cluster mode disabled) replication group is a collection of instances, where one of the instances is a read/write primary and the others are read-only replicas. Writes to the primary are asynchronously propagated to the replicas.

>A Redis (cluster mode enabled) replication group is a collection of shards where one of the shards has a primary...

To keep the rest of the definition the same, the easiest way would be to replace "clusters" -> "instances" in this CMD context.
In a CME context, replication group is essentially the same thing as a cluster.

ElastiCache is a managed service for both Memcached and Redis. The word “cluster” is used in the documentation circumstantially, I agree that describing replication group as a “collection of clusters” is indeed confusing.

For the API question, if we look carefully into the documentation of the APIs you mentioned; CreateCacheCluster and, CreateReplicationGroup - we can come up with some good practices on what to action to use and when and also clarify some of the terminology.

When creating a new Redis cluster, using the CreateCacheCluster will result in a cluster mode disabled deployment with a single primary instance and no replicas. The only way to attach replicas to this cluster would be to create a replication group. Therefore, it is not beneficial to use the CreateCacheCluster API to create a Redis cluster. This API is useful when we want to create a Memcached cluster where we can define 1-40 Memcached instances. Note that Memcached doesn’t support replication.

CreateReplicationGroup allows us to create a cluster mode disabled or a cluster mode enabled deployment. When creating a cluster mode disabled, we can define 1 primary and up to 5 replicas. When creating a cluster mode enabled (Which is preferred, unless you need features that exist only in cluster mode disabled), you can define up to 500 instances (primaries + replicas). The word clusters in that part of the documentation is synonymous to “shards” which should be reworded. Note that CreateReplicationGroup only supports “Redis” for its Engine param.

From CreateReplicationGroup docs:
>This operation is valid for Redis only.

To sum up. I advise to use the CreateReplicationGroup API when creating a Redis deployment and, use CreateCacheCluster when creating a Memcached deployment.