This module creates an ElastiCache cluster that runs Redis.
The redis cluster is managed by AWS and automatically detects and replaces failed nodes, streamlines software upgrades
and patches, enables easy scaling of the cluster both horizontally (add more nodes) and vertically (increase the power
of existing nodes), and simplifies backup and restore functionality.
About Amazon ElastiCache
What is Amazon ElastiCache?
Before Amazon ElastiCache existed, teams would painstakingly configure the memcached or redis caching engines on their own. Setting up automatic failover, read replicas, backups, and handling upgrades are all non-trivial and AWS recognized they could implement these features according to best practices themselves, sparing customers the time and cost of doing it themselves.
Behind the scenes, ElastiCache runs on EC2 Instances located in subnets and protected by security groups you specify.
Structure of an ElastiCache Redis deployment
Nodes: The smallest unit of an ElastiCache Redis deployment is a node. It's basically the network-attached RAM on which the cache engine (Redis in this case) runs
Shards: Also sometimes called "Node Group". A Shard is a replication-enabled collection of multiple nodes. Within a Shard, one node is the primary read/write node while the rest are read-only replicas of the primary node. A Shard can have up to 5 read-only replicas.
Cluster: An ElastiCache cluster is a collection of one or more Shards. Somewhat confusingly, an ElastiCache Cluster has a "cluster mode" property that allows a Cluster to distribute its data over multiple Shards. When cluster mode is disabled, the Cluster can have at most one Shard. When cluster mode is enabled, the Cluster can have up to 15 Shards. A "cluster mode disabled" Cluster (i.e. Single Shard cluster) can be scaled horizontally by adding/removing replica nodes within its single Shard, vertical scaling is achieved by simply changing the node types. However, a "cluster mode enabled" Cluster (i.e. Multi Shard cluster) can be scaled horizontally by adding/removing Shards, the node types in the Shards can also be changed to achieve vertical scaling. Each cluster mode will be explained in detail below with additional info on when each one will be more appropriate depending on your scaling needs.
How do you connect to the Redis Cluster?
When connecting to Redis (cluster mode disabled) from your app, direct all operations to the Primary Endpoint of the Cluster. This way, in the event of a failover, your app will be resolving a DNS record that automatically gets updated to the latest primary node.
When connecting to Redis (cluster mode enabled) from your app, direct all reads/writes to the Configuration Endpoint of the Cluster. Ensure you have a client that supports Redis Cluster (redis 3.2). You can still read from individual node enpoints.
In both "cluster mode enabled" and "cluster mode disabled" deployment models you can still direct reads to any of the Read Endpoints of the nodes in the Cluster, however you now risk reading a slightly out-of-date copy of the data in the event that you read from a node before the primary's latest data has synced to it.
This module outputs Terraform output variables that contain the address of the primary endpoint and read endpoints. You can programmatically extract these variables in your Terraform templates and pass them to other resources (e.g. as environment variables in an EC2 Instance) You'll also see the variables at the end of each terraform apply call or if you run terraform output.
How do you scale the Redis Cluster?
You can scale your ElastiCache Cluster either horizontally (by adding more nodes) or vertically (by using more powerful nodes), but the method depends on whether Cluster Mode is enabled or disabled.
When Cluster Mode is Disabled
This mode is useful when you'd prefer to have only a single point for data to be written to the redis database. All data is written to the primary node of the single shard which is now replicated to the replica nodes. The advantage of this approach is that you're sure that all your data is present at a single point which could make migrations and backups a lot easier, if there's a problem with the primary write node however, all write attempts will fail.
Vertical: You can increase the type of the read replica nodes using the instance_type parameter (see here for valid values).
Horizontal: You can add up to 5 replica nodes to a Redis Cluster using the cluster_size parameter. There is always a primary node where all writes take place, but you can reduce load on this primary node by offloading reads to the non-primary nodes, which are known as Read Replicas.
When cluster mode is enabled, data you write is split among the primary nodes in multiple Shards, and each data stored in those Shards are replicated among the read replicas. If one Shard becomes unavailable for whatever reason, other shards are still available for writing.
To deploy a Redis "cluster mode enabled" cluster you must ensure that the enable_automatic_failover parameter is set to true and the cluster_mode variable has a single map with num_shards and replicas_per_shard parameters.
E.g. the following Terraform code specifies a "cluster mode enabled" Cluster with 2 Shards and 1 Read Replica per Shard
Horizontal: A "cluster mode enabled" cluster can be scaled horizontally by adding more Shards - also called Resharding, the amount of read replicas present in the extra Shards is the same as the number specified when the cluster was originally created. Resharding can take anywhere from a few minutes to several hours.
Vertical: A "cluster mode enabled" cluster can be scaled vertically by changing the node types within each Shard. This method is offline only and the cluster has to be backed up, a new cluster created with the required node types and the backup restored to that new cluster. During this process your entire cluster will experience a downtime which could last for any length of time depending on how much data the original cluster contained.
Prior to October 2016, ElastiCache for Redis did not support partitioning
(aka sharding) in Redis and as a result used a bunch of confusing terminologies to explain setting up a Redis cluster.
Cluster: In ElastiCache, each Redis node is labeled its own "cluster", despite that there is only a single node in the cluster. This is an artifact of how ElastiCache implements memcached clusters, which can support multiple nodes.
Replication Group: The Redis "read/write primary cluster" (the master node) will asynchronously copy its data to all other Redis clusters (individual nodes) in the same Replication Group. In a sense, the "real" redis cluster in ElastiCache is actually the Replication Group.
Primary Cluster: In a Replication Group, the primary cluster is where all write traffic is directed. Initially, you can direct all your reads here as well.
Read Replicas: In a Replication Group, data written to the primary cluster is asynchronously copied to each Read Replica. These are useful both to reduce the read load on the primary cluster and to faciliate fast failover.
Multi-AZ: Using the Multi-AZ option means that if the primary cluster fails, ElastiCache will auto failover to a Read Replica. Without this option, the primary cluster node will simply replace itself, which will take longer and may result in additional data loss.
Common Gotcha's
In the event of a Redis failover, you will experience a small period of time during which writes are not accepted, so make sure your app can handle this gracefully. In fact, consider simulating Redis failovers on a regular basis or with automated testing to validate that your app can handle it correctly.
Test that your app does not cache the DNS value of the Primary Endpoint! Java, in particular, has undesirable defaults around DNS caching in many cases. If your code does not honor the TTL property of the Primary Endpoint's DNS record, then your app may fail to reach the new primary node in the event of a failure.
The only way to add more storage space to nodes in a Redis Cluster (cluster mode disabled) is to scale up to a larger node type.
Questions? Ask away.
We're here to talk about our services, answer any questions, give advice, or just to chat.
{"treedata":{"name":"root","toggled":true,"children":[{"name":".circleci","children":[{"name":"config.yml","path":".circleci/config.yml","sha":"713034b3fea8d942623c62e27a27109b070099b7"}]},{"name":".gitignore","path":".gitignore","sha":"32845458602b36a63610885e236aecaf5d0cfb98"},{"name":"CODEOWNERS","path":"CODEOWNERS","sha":"f6e0666fa0dee5df6743291167734a2bcfbb359b"},{"name":"LICENSE.txt","path":"LICENSE.txt","sha":"f4e3d9bd4717a044ed31ad847a300eee74371a78"},{"name":"README.md","path":"README.md","sha":"2c356194fc0bbff15f5249a41508327e35859263"},{"name":"examples","children":[{"name":"memcached","children":[{"name":"README.md","path":"examples/memcached/README.md","sha":"98ac13c3915c0ec564a5f493a5df38deec5d4e00"},{"name":"main.tf","path":"examples/memcached/main.tf","sha":"40572ae87c9cd0ca4adbd19a9bb4426058f6b370"},{"name":"outputs.tf","path":"examples/memcached/outputs.tf","sha":"bc090567ef708bed42c4a64aaef937e8ae27b67a"},{"name":"vars.tf","path":"examples/memcached/vars.tf","sha":"2fd1a4649f52b1a66539b5f52d39107c87aabf14"}]},{"name":"redis","children":[{"name":"README.md","path":"examples/redis/README.md","sha":"cf0d093b9d434c17ff7817f5f7911c451175f135"},{"name":"main.tf","path":"examples/redis/main.tf","sha":"36f708f9d4cd62eea7b1ac21e55506b9b3daee68"},{"name":"outputs.tf","path":"examples/redis/outputs.tf","sha":"fa63a3dda4e16c49e15f8f6c1185ea8acda463d6"},{"name":"vars.tf","path":"examples/redis/vars.tf","sha":"decc10c01d6965cd6896dce1e5cd6bae4c1696eb"}]},{"name":"redis_with_auth_token","children":[{"name":"README.md","path":"examples/redis_with_auth_token/README.md","sha":"1eff206d550be3a4eb3a6ca12cc700ac918d3679"},{"name":"main.tf","path":"examples/redis_with_auth_token/main.tf","sha":"7890d2fe3ced51d33394b57714ba9c18b484b86c"},{"name":"outputs.tf","path":"examples/redis_with_auth_token/outputs.tf","sha":"fa63a3dda4e16c49e15f8f6c1185ea8acda463d6"},{"name":"vars.tf","path":"examples/redis_with_auth_token/vars.tf","sha":"4bb8102242a9324ef9251ea3bd9aa57223b77c70"}]},{"name":"redis_with_sharding","children":[{"name":"README.md","path":"examples/redis_with_sharding/README.md","sha":"b17e9da01d802f21d5587be60961ff448a35f769"},{"name":"main.tf","path":"examples/redis_with_sharding/main.tf","sha":"931e0cbe1270404caa403fcd0cef4fb4f6b32590"},{"name":"outputs.tf","path":"examples/redis_with_sharding/outputs.tf","sha":"b9da108a7b6c9d78ed439c31699fdd66abb83e0e"},{"name":"vars.tf","path":"examples/redis_with_sharding/vars.tf","sha":"266b3f3027fbc5ac570b481dca97a0885ec400db"}]}]},{"name":"modules","children":[{"name":"memcached","children":[{"name":"README.md","path":"modules/memcached/README.md","sha":"c5d3f4dc902f551347f460c0442ae8a0991ede04"},{"name":"main.tf","path":"modules/memcached/main.tf","sha":"ddc01e3a3001d8b1716f50e1244a19967b2b8dfc"},{"name":"outputs.tf","path":"modules/memcached/outputs.tf","sha":"937ab3e0a846931270544fcf9c6020a6da7ff47d"},{"name":"vars.tf","path":"modules/memcached/vars.tf","sha":"26715675dd0be9c11e8a583d0746e08f1a179d8a"}]},{"name":"redis","children":[{"name":"README.md","path":"modules/redis/README.md","sha":"7220f78fb0dc2a2baf72637a581909bfe48f0ab3","toggled":true},{"name":"main.tf","path":"modules/redis/main.tf","sha":"43ae59acbf258570ac1e4c685836afc84116da89"},{"name":"outputs.tf","path":"modules/redis/outputs.tf","sha":"f60f07c62fcb53e0c70d4f77f3162fc9596ca1c7"},{"name":"vars.tf","path":"modules/redis/vars.tf","sha":"aa38d63c286db322b29c67b2e01b4eb961d5e7c6"}],"toggled":true}],"toggled":true},{"name":"test","children":[{"name":"Gopkg.lock","path":"test/Gopkg.lock","sha":"e6fa805a9322132a9fc82f82dd37fbbd3e00744f"},{"name":"Gopkg.toml","path":"test/Gopkg.toml","sha":"21097b316459ac59bc80127556c0aba9f3acbf0c"},{"name":"README.md","path":"test/README.md","sha":"6b5235cc1168c5e09db7f1f1e22451d3d6d601db"},{"name":"example_memcached_test.go","path":"test/example_memcached_test.go","sha":"6be05472a7dd8bcc82f0766af74351d7fb95fcd5"},{"name":"example_redis_test.go","path":"test/example_redis_test.go","sha":"98cee9bd935a2d89ca86f92e95f429259e89f676"},{"name":"example_util_functions_test.go","path":"test/example_util_functions_test.go","sha":"ac6c2e63d5f870b3bf459d167061eb7cc7bfd751"}]}]},"detailsContent":"<h1 class=\"preview__body--title\" id=\"redis-module\">Redis Module</h1><div class=\"preview__body--border\"></div><p>This module creates an ElastiCache cluster that runs <a href=\"http://redis.io/\" class=\"preview__body--description--blue\" target=\"_blank\">Redis</a>.</p>\n<p>The redis cluster is managed by AWS and automatically detects and replaces failed nodes, streamlines software upgrades\nand patches, enables easy scaling of the cluster both horizontally (add more nodes) and vertically (increase the power\nof existing nodes), and simplifies backup and restore functionality.</p>\n<h2 class=\"preview__body--subtitle\" id=\"about-amazon-elasti-cache\">About Amazon ElastiCache</h2>\n<h3 class=\"preview__body--subtitle\" id=\"what-is-amazon-elasti-cache\">What is Amazon ElastiCache?</h3>\n<p>Before <a href=\"http://docs.aws.amazon.com/AmazonElastiCache/latest/UserGuide/WhatIs.html\" class=\"preview__body--description--blue\" target=\"_blank\">Amazon ElastiCache</a> existed, teams would painstakingly configure the memcached or redis caching engines on their own. Setting up automatic failover, read replicas, backups, and handling upgrades are all non-trivial and AWS recognized they could implement these features according to best practices themselves, sparing customers the time and cost of doing it themselves.</p>\n<p>Behind the scenes, ElastiCache runs on EC2 Instances located in subnets and protected by security groups you specify.</p>\n<h3 class=\"preview__body--subtitle\" id=\"structure-of-an-elasti-cache-redis-deployment\">Structure of an ElastiCache Redis deployment</h3>\n<ul>\n<li>\n<p><strong>Nodes:</strong> The smallest unit of an ElastiCache Redis deployment is a node. It's basically the network-attached RAM on which the cache engine (Redis in this case) runs</p>\n</li>\n<li>\n<p><strong>Shards:</strong> Also sometimes called "Node Group". A Shard is a replication-enabled collection of multiple nodes. Within a Shard, one node is the primary read/write node while the rest are read-only replicas of the primary node. A Shard can have up to 5 read-only replicas.</p>\n</li>\n<li>\n<p><strong>Cluster:</strong> An ElastiCache cluster is a collection of one or more Shards. Somewhat confusingly, an ElastiCache Cluster has a "cluster mode" property that allows a Cluster to distribute its data over multiple Shards. When cluster mode is disabled, the Cluster can have at most one Shard. When cluster mode is enabled, the Cluster can have up to 15 Shards. A "cluster mode disabled" Cluster (i.e. Single Shard cluster) can be scaled horizontally by adding/removing replica nodes within its single Shard, vertical scaling is achieved by simply changing the node types. However, a "cluster mode enabled" Cluster (i.e. Multi Shard cluster) can be scaled horizontally by adding/removing Shards, the node types in the Shards can also be changed to achieve vertical scaling. Each cluster mode will be explained in detail below with additional info on when each one will be more appropriate depending on your scaling needs.</p>\n</li>\n</ul>\n<h3 class=\"preview__body--subtitle\" id=\"how-do-you-connect-to-the-redis-cluster\">How do you connect to the Redis Cluster?</h3>\n<ul>\n<li>\n<p>When connecting to Redis (cluster mode disabled) from your app, direct all operations to the <strong>Primary Endpoint</strong> of the <strong>Cluster.</strong> This way, in the event of a failover, your app will be resolving a DNS record that automatically gets updated to the latest primary node.</p>\n</li>\n<li>\n<p>When connecting to Redis (cluster mode enabled) from your app, direct all reads/writes to the <strong>Configuration Endpoint</strong> of the <strong>Cluster.</strong> Ensure you have a client that supports Redis Cluster (redis 3.2). You can still read from individual node enpoints.</p>\n</li>\n<li>\n<p>In both "cluster mode enabled" and "cluster mode disabled" deployment models you can still direct reads to any of the <strong>Read Endpoints</strong> of the nodes in the Cluster, however you now risk reading a slightly out-of-date copy of the data in the event that you read from a node before the primary's latest data has synced to it.</p>\n</li>\n</ul>\n<p>This module outputs <a href=\"https://www.terraform.io/intro/getting-started/outputs.html\" class=\"preview__body--description--blue\" target=\"_blank\">Terraform output variables</a> that contain the address of the primary endpoint and read endpoints. You can programmatically extract these variables in your Terraform templates and pass them to other resources (e.g. as environment variables in an EC2 Instance) You'll also see the variables at the end of each <code>terraform apply</code> call or if you run <code>terraform output</code>.</p>\n<h3 class=\"preview__body--subtitle\" id=\"how-do-you-scale-the-redis-cluster\">How do you scale the Redis Cluster?</h3>\n<p>You can scale your ElastiCache Cluster either horizontally (by adding more nodes) or vertically (by using more powerful nodes), but the method depends on whether Cluster Mode is enabled or disabled.</p>\n<h4 id=\"when-cluster-mode-is-disabled\">When Cluster Mode is Disabled</h4>\n<p>This mode is useful when you'd prefer to have only a single point for data to be written to the redis database. All data is written to the primary node of the single shard which is now replicated to the replica nodes. The advantage of this approach is that you're sure that all your data is present at a single point which could make migrations and backups a lot easier, if there's a problem with the primary write node however, all write attempts will fail.</p>\n<ul>\n<li>\n<p><strong>Vertical:</strong> You can increase the type of the read replica nodes using the <code>instance_type</code> parameter (see <a href=\"https://aws.amazon.com/elasticache/details/#Available_Cache_Node_Types\" class=\"preview__body--description--blue\" target=\"_blank\">here</a> for valid values).</p>\n</li>\n<li>\n<p><strong>Horizontal:</strong> You can add up to 5 replica nodes to a Redis Cluster using the <code>cluster_size</code> parameter. There is always a primary node where all writes take place, but you can reduce load on this primary node by offloading reads to the non-primary nodes, which are known as Read Replicas.</p>\n</li>\n</ul>\n<p>For more info on both methods, see <a href=\"https://docs.aws.amazon.com/AmazonElastiCache/latest/UserGuide/Scaling.RedisStandalone.html\" class=\"preview__body--description--blue\" target=\"_blank\">Scaling Single-Node Redis (cluster mode disabled) Clusters</a>.</p>\n<h4 id=\"when-cluster-mode-is-enabled\">When Cluster Mode is Enabled</h4>\n<p>When cluster mode is enabled, data you write is split among the primary nodes in multiple Shards, and each data stored in those Shards are replicated among the read replicas. If one Shard becomes unavailable for whatever reason, other shards are still available for writing.</p>\n<p>To deploy a Redis "cluster mode enabled" cluster you must ensure that the <code>enable_automatic_failover</code> parameter is set to <code>true</code> and the <code>cluster_mode</code> variable has a single map with <code>num_shards</code> and <code>replicas_per_shard</code> parameters.</p>\n<p>E.g. the following Terraform code specifies a "cluster mode enabled" Cluster with 2 Shards and 1 Read Replica per Shard</p>\n<pre><span class=\"hljs-attr\">cluster_mode</span> = [{\n <span class=\"hljs-attr\">num_node_groups</span> = <span class=\"hljs-number\">2</span>\n <span class=\"hljs-attr\">replicas_per_node_group</span> = <span class=\"hljs-number\">1</span>\n}]\n</pre>\n<ul>\n<li>\n<p><strong>Horizontal:</strong> A "cluster mode enabled" cluster can be scaled horizontally by adding more Shards - also called Resharding, the amount of read replicas present in the extra Shards is the same as the number specified when the cluster was originally created. Resharding can take anywhere from a few minutes to several hours.</p>\n</li>\n<li>\n<p><strong>Vertical:</strong> A "cluster mode enabled" cluster can be scaled vertically by changing the node types within each Shard. This method is offline only and the cluster has to be backed up, a new cluster created with the required node types and the backup restored to that new cluster. During this process your entire cluster will experience a downtime which could last for any length of time depending on how much data the original cluster contained.</p>\n</li>\n</ul>\n<p>For more info on scaling "cluster mode enabled" Redis clusters, see <a href=\"https://docs.aws.amazon.com/AmazonElastiCache/latest/UserGuide/scaling-redis-cluster-mode-enabled.html\" class=\"preview__body--description--blue\" target=\"_blank\">Scaling Multishard Redis (cluster mode disabled) Clusters</a></p>\n<h2 class=\"preview__body--subtitle\" id=\"how-do-you-use-this-module\">How do you use this module?</h2>\n<p>See the <a href=\"/repos/v0.9.0/module-cache/examples/redis\" class=\"preview__body--description--blue\">redis example</a> for an example.</p>\n<h3 class=\"preview__body--subtitle\" id=\"elasti-cache-old-terminology\">ElastiCache Old Terminology</h3>\n<p>Prior to October 2016, ElastiCache for Redis did not support <a href=\"http://redis.io/topics/partitioning\" class=\"preview__body--description--blue\" target=\"_blank\">partitioning</a>\n(aka sharding) in Redis and as a result used a bunch of confusing terminologies to explain setting up a Redis cluster.</p>\n<ul>\n<li>\n<p><strong>Cluster:</strong> In ElastiCache, each Redis node is labeled its own "cluster", despite that there is only a single node in the cluster. This is an artifact of how ElastiCache implements memcached clusters, which can support multiple nodes.</p>\n</li>\n<li>\n<p><strong>Replication Group:</strong> The Redis "read/write primary cluster" (the master node) will asynchronously copy its data to all other Redis clusters (individual nodes) in the same Replication Group. In a sense, the "real" redis cluster in ElastiCache is actually the Replication Group.</p>\n</li>\n<li>\n<p><strong>Primary Cluster:</strong> In a Replication Group, the primary cluster is where all write traffic is directed. Initially, you can direct all your reads here as well.</p>\n</li>\n<li>\n<p><strong>Read Replicas:</strong> In a Replication Group, data written to the primary cluster is asynchronously copied to each Read Replica. These are useful both to reduce the read load on the primary cluster and to faciliate fast failover.</p>\n</li>\n<li>\n<p><strong>Multi-AZ:</strong> Using the Multi-AZ option means that if the primary cluster fails, ElastiCache will auto failover to a Read Replica. Without this option, the primary cluster node will simply replace itself, which will take longer and may result in additional data loss.</p>\n</li>\n</ul>\n<h3 class=\"preview__body--subtitle\" id=\"common-gotchas\">Common Gotcha's</h3>\n<ul>\n<li>\n<p>In the event of a Redis failover, <em>you will experience a small period of time during which writes are not accepted</em>, so make sure your app can handle this gracefully. In fact, consider simulating Redis failovers on a regular basis or with automated testing to validate that your app can handle it correctly.</p>\n</li>\n<li>\n<p>Test that your app does not cache the DNS value of the Primary Endpoint! Java, in particular, has undesirable defaults around DNS caching in many cases. If your code does not honor the TTL property of the Primary Endpoint's DNS record, then your app may fail to reach the new primary node in the event of a failure.</p>\n</li>\n<li>\n<p>The only way to add more storage space to nodes in a Redis Cluster (cluster mode disabled) is to scale up to a larger node type.</p>\n</li>\n</ul>\n","repoName":"module-cache","repoRef":"v0.9.4","serviceDescriptor":{"serviceName":"Redis","serviceRepoName":"module-cache","serviceRepoOrg":"gruntwork-io","serviceMainReadmePath":"/modules/redis","cloudProviders":["aws"],"description":"Run a Redis cluster using Amazon’s ElastiCache Service. Supports replication, multi-zone automatic failover, and automatic backup.","imageUrl":"redis.png","licenseType":"subscriber","technologies":["Terraform","Bash"],"compliance":[],"tags":[""]},"serviceCategoryName":"NoSQL","fileName":"README.md","filePath":"/modules/redis","title":"Repo Browser: Redis","description":"Browse the repos in the Gruntwork Infrastructure as Code Library."}
.circleci
main.tf
