Service Catalog Version 0.118.1Last updated in version 0.112.5

Amazon ElastiCache for Redis

Overview

This service contains code to deploy a Redis Cluster using Amazon ElastiCache. The cluster is managed by AWS and automatically handles standby failover, read replicas, backups, patching, and encryption.

ElastiCache for Redis architecture

Features

Deploy a fully-managed Redis cluster
Automatic failover to a standby in another availability zone
Read replicas
Automatic nightly snapshots
Automatic cross account snapshots
Automatic scaling of storage
CloudWatch Alarms for alerting when CPU, memory, and disk metrics exceed certain thresholds
Integrate with Kubernetes Service Discovery

Learn

note

This repo is a part of the Gruntwork Service Catalog, a collection of reusable, battle-tested, production ready infrastructure code. If you’ve never used the Service Catalog before, make sure to read How to use the Gruntwork Service Catalog!

What is Amazon ElastiCache?
Common gotchas with ElastiCache
Amazon ElastiCache for Redis documentation: Amazon’s ElastiCache for Redis docs that cover core concepts such as the options and versions supported, security, backup & restore, and monitoring.
Designing Data Intensive Applications: the best book we’ve found for understanding data systems, including relational databases, NoSQL, replication, sharding, consistency, and so on.

Deploy

Non-production deployment (quick start for learning)

If you just want to try this repo out for experimenting and learning, check out the following resources:

examples/for-learning-and-testing folder: The examples/for-learning-and-testing folder contains standalone sample code optimized for learning, experimenting, and testing (but not direct production usage).

Production deployment

If you want to deploy this repo in production, check out the following resources:

examples/for-production folder: The examples/for-production folder contains sample code optimized for direct usage in production. This is code from the Gruntwork Reference Architecture, and it shows you how we build an end-to-end, integrated tech stack on top of the Gruntwork Service Catalog.

Sample Usage

Terraform
Terragrunt

main.tf

# ------------------------------------------------------------------------------------------------------
# DEPLOY GRUNTWORK'S REDIS MODULE
# ------------------------------------------------------------------------------------------------------

module "redis" {

  source = "git::git@github.com:gruntwork-io/terraform-aws-service-catalog.git//modules/data-stores/redis?ref=v0.118.1"

  # ----------------------------------------------------------------------------------------------------
  # REQUIRED VARIABLES
  # ----------------------------------------------------------------------------------------------------

  # Indicates whether Multi-AZ is enabled. When Multi-AZ is enabled, a read-only
  # replica is automatically promoted to a read-write primary cluster if the
  # existing primary cluster fails. If you specify true, you must specify a
  # value greater than 1 for replication_group_size.
  enable_automatic_failover = <bool>

  # Indicates whether Multi-AZ is enabled. When Multi-AZ is enabled, a read-only
  # replica is automatically promoted to a read-write primary cluster if the
  # existing primary cluster fails. If you specify true, you must specify a
  # value greater than 1 for replication_group_size.
  enable_multi_az = <bool>

  # The compute and memory capacity of the nodes (e.g. cache.m4.large).
  instance_type = <string>

  # The name used to namespace all resources created by these templates,
  # including the ElastiCache cluster itself (e.g. rediscache). Must be unique
  # in this region. Must be a lowercase string.
  name = <string>

  # The total number of nodes in the Redis Replication Group. E.g. 1 represents
  # just the primary node, 2 represents the primary plus a single Read Replica.
  replication_group_size = <number>

  # The list of IDs of the subnets in which to deploy the ElasticCache
  # instances. The list must only contain subnets in var.vpc_id.
  subnet_ids = <list(string)>

  # The ID of the VPC in which to deploy RDS.
  vpc_id = <string>

  # ----------------------------------------------------------------------------------------------------
  # OPTIONAL VARIABLES
  # ----------------------------------------------------------------------------------------------------

  # Trigger an alarm if the amount of free memory, in Bytes, on the node drops
  # below this threshold
  alarm_low_memory_available_threshold = 100000000

  # Sets how this alarm should handle entering the INSUFFICIENT_DATA state.
  # Based on
  # https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html#alarms-and-missing-data.
  # Must be one of: 'missing', 'ignore', 'breaching' or 'notBreaching'.
  alarm_treat_missing_data = "missing"

  # The ARNs of SNS topics where CloudWatch alarms (e.g., for CPU, memory, and
  # disk space usage) should send notifications.
  alarms_sns_topic_arns = []

  # The list of network CIDR blocks to allow network access to ElastiCache from.
  # One of var.allow_connections_from_cidr_blocks or
  # var.allow_connections_from_security_groups must be specified for the
  # ElastiCache instances to be reachable.
  allow_connections_from_cidr_blocks = []

  # The list of IDs or Security Groups to allow network access to ElastiCache
  # from. All security groups must either be in the VPC specified by var.vpc_id,
  # or a peered VPC with the VPC specified by var.vpc_id. One of
  # var.allow_connections_from_cidr_blocks or
  # var.allow_connections_from_security_groups must be specified for the
  # ElastiCache instances to be reachable.
  allow_connections_from_security_groups = []

  # Specifies whether any modifications are applied immediately, or during the
  # next maintenance window.
  apply_immediately = false

  # The password used to access a password protected server. Can be specified
  # only if transit_encryption_enabled = true. Must contain from 16 to 128
  # alphanumeric characters or symbols (excluding @, <double-quotes>, and /)
  auth_token = null

  # Specifies whether minor version engine upgrades will be applied
  # automatically to the underlying Cache Cluster instances during the
  # maintenance window. Only supported for engine type 'redis' and if the engine
  # version is 6 or higher. Defaults to false (disabled).
  auto_minor_version_upgrade = false

  # Whether to enable encryption at rest.
  enable_at_rest_encryption = true

  # Set to true to enable several basic CloudWatch alarms around CPU usage,
  # memory usage, and disk space usage. If set to true, make sure to specify SNS
  # topics to send notifications to using var.alarms_sns_topic_arn.
  enable_cloudwatch_alarms = true

  # Whether to enable encryption in transit.
  enable_transit_encryption = true

  # Specifies the destination and format of Redis Engine Log. See the
  # documentation on Amazon ElastiCache. See Log Delivery Configuration below
  # for more details. You can find more information here
  # https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/elasticache_replication_group#log-delivery-configuration.
  engine_log_delivery_configuration = null

  # Specifies the weekly time range for when maintenance on the cache cluster is
  # performed (e.g. sun:05:00-sun:09:00). The format is ddd:hh24:mi-ddd:hh24:mi
  # (24H Clock UTC). The minimum maintenance window is a 60 minute period.
  maintenance_window = "sat:07:00-sat:08:00"

  # Number of node groups (shards) for this Redis replication group. Changing
  # this number will trigger a resizing operation before other settings
  # modifications.
  num_node_groups = null

  # Name of the parameter group to associate with this cache cluster. This can
  # be used to configure custom settings for the cluster.
  parameter_group_name = null

  # The port number on which each of the cache nodes will accept connections
  # (e.g. 6379).
  port = 6379

  # Version number of redis to use (e.g. 5.0.6).
  redis_version = "5.0.6"

  #  Number of replica nodes in each node group. Changing this number will
  # trigger a resizing operation before other settings modifications. Valid
  # values are 0 to 5.
  replicas_per_node_group = null

  # Specifies the destination and format of Redis SLOWLOG. See the documentation
  # on Amazon ElastiCache. See Log Delivery Configuration below for more
  # details. You can find more information here
  # https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/elasticache_replication_group#log-delivery-configuration.
  slow_log_delivery_configuration = null

  # The Amazon Resource Name (ARN) of a Redis RDB snapshot file stored in Amazon
  # S3. You can use this parameter to restore from an externally created
  # snapshot. If you have an ElastiCache snapshot, use snapshot_name.
  snapshot_arn = null

  # The name of a snapshot from which to restore the Redis cluster. You can use
  # this to restore from an ElastiCache snapshot. If you have an externally
  # created snapshot, use snapshot_arn.
  snapshot_name = null

  # The number of days for which ElastiCache will retain automatic cache cluster
  # snapshots before deleting them. Set to 0 to disable snapshots.
  snapshot_retention_limit = 15

  # The daily time range during which automated backups are created (e.g.
  # 04:00-09:00). Time zone is UTC. Performance may be degraded while a backup
  # runs. Set to empty string to disable snapshots.
  snapshot_window = "06:00-07:00"

  # The ARN of the SNS Topic to which notifications will be sent when a
  # Replication Group event happens, such as an automatic failover (e.g.
  # arn:aws:sns:*:123456789012:my_sns_topic). An empty string is a valid value
  # if you do not wish to receive notifications via SNS.
  sns_topic_for_notifications = ""

  # A set of tags to set for the ElastiCache Replication Group.
  tags = {}

}

terragrunt.hcl

# ------------------------------------------------------------------------------------------------------
# DEPLOY GRUNTWORK'S REDIS MODULE
# ------------------------------------------------------------------------------------------------------

terraform {
  source = "git::git@github.com:gruntwork-io/terraform-aws-service-catalog.git//modules/data-stores/redis?ref=v0.118.1"
}

inputs = {

  # ----------------------------------------------------------------------------------------------------
  # REQUIRED VARIABLES
  # ----------------------------------------------------------------------------------------------------

  # Indicates whether Multi-AZ is enabled. When Multi-AZ is enabled, a read-only
  # replica is automatically promoted to a read-write primary cluster if the
  # existing primary cluster fails. If you specify true, you must specify a
  # value greater than 1 for replication_group_size.
  enable_automatic_failover = <bool>

  # Indicates whether Multi-AZ is enabled. When Multi-AZ is enabled, a read-only
  # replica is automatically promoted to a read-write primary cluster if the
  # existing primary cluster fails. If you specify true, you must specify a
  # value greater than 1 for replication_group_size.
  enable_multi_az = <bool>

  # The compute and memory capacity of the nodes (e.g. cache.m4.large).
  instance_type = <string>

  # The name used to namespace all resources created by these templates,
  # including the ElastiCache cluster itself (e.g. rediscache). Must be unique
  # in this region. Must be a lowercase string.
  name = <string>

  # The total number of nodes in the Redis Replication Group. E.g. 1 represents
  # just the primary node, 2 represents the primary plus a single Read Replica.
  replication_group_size = <number>

  # The list of IDs of the subnets in which to deploy the ElasticCache
  # instances. The list must only contain subnets in var.vpc_id.
  subnet_ids = <list(string)>

  # The ID of the VPC in which to deploy RDS.
  vpc_id = <string>

  # ----------------------------------------------------------------------------------------------------
  # OPTIONAL VARIABLES
  # ----------------------------------------------------------------------------------------------------

  # Trigger an alarm if the amount of free memory, in Bytes, on the node drops
  # below this threshold
  alarm_low_memory_available_threshold = 100000000

  # Sets how this alarm should handle entering the INSUFFICIENT_DATA state.
  # Based on
  # https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html#alarms-and-missing-data.
  # Must be one of: 'missing', 'ignore', 'breaching' or 'notBreaching'.
  alarm_treat_missing_data = "missing"

  # The ARNs of SNS topics where CloudWatch alarms (e.g., for CPU, memory, and
  # disk space usage) should send notifications.
  alarms_sns_topic_arns = []

  # The list of network CIDR blocks to allow network access to ElastiCache from.
  # One of var.allow_connections_from_cidr_blocks or
  # var.allow_connections_from_security_groups must be specified for the
  # ElastiCache instances to be reachable.
  allow_connections_from_cidr_blocks = []

  # The list of IDs or Security Groups to allow network access to ElastiCache
  # from. All security groups must either be in the VPC specified by var.vpc_id,
  # or a peered VPC with the VPC specified by var.vpc_id. One of
  # var.allow_connections_from_cidr_blocks or
  # var.allow_connections_from_security_groups must be specified for the
  # ElastiCache instances to be reachable.
  allow_connections_from_security_groups = []

  # Specifies whether any modifications are applied immediately, or during the
  # next maintenance window.
  apply_immediately = false

  # The password used to access a password protected server. Can be specified
  # only if transit_encryption_enabled = true. Must contain from 16 to 128
  # alphanumeric characters or symbols (excluding @, <double-quotes>, and /)
  auth_token = null

  # Specifies whether minor version engine upgrades will be applied
  # automatically to the underlying Cache Cluster instances during the
  # maintenance window. Only supported for engine type 'redis' and if the engine
  # version is 6 or higher. Defaults to false (disabled).
  auto_minor_version_upgrade = false

  # Whether to enable encryption at rest.
  enable_at_rest_encryption = true

  # Set to true to enable several basic CloudWatch alarms around CPU usage,
  # memory usage, and disk space usage. If set to true, make sure to specify SNS
  # topics to send notifications to using var.alarms_sns_topic_arn.
  enable_cloudwatch_alarms = true

  # Whether to enable encryption in transit.
  enable_transit_encryption = true

  # Specifies the destination and format of Redis Engine Log. See the
  # documentation on Amazon ElastiCache. See Log Delivery Configuration below
  # for more details. You can find more information here
  # https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/elasticache_replication_group#log-delivery-configuration.
  engine_log_delivery_configuration = null

  # Specifies the weekly time range for when maintenance on the cache cluster is
  # performed (e.g. sun:05:00-sun:09:00). The format is ddd:hh24:mi-ddd:hh24:mi
  # (24H Clock UTC). The minimum maintenance window is a 60 minute period.
  maintenance_window = "sat:07:00-sat:08:00"

  # Number of node groups (shards) for this Redis replication group. Changing
  # this number will trigger a resizing operation before other settings
  # modifications.
  num_node_groups = null

  # Name of the parameter group to associate with this cache cluster. This can
  # be used to configure custom settings for the cluster.
  parameter_group_name = null

  # The port number on which each of the cache nodes will accept connections
  # (e.g. 6379).
  port = 6379

  # Version number of redis to use (e.g. 5.0.6).
  redis_version = "5.0.6"

  #  Number of replica nodes in each node group. Changing this number will
  # trigger a resizing operation before other settings modifications. Valid
  # values are 0 to 5.
  replicas_per_node_group = null

  # Specifies the destination and format of Redis SLOWLOG. See the documentation
  # on Amazon ElastiCache. See Log Delivery Configuration below for more
  # details. You can find more information here
  # https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/elasticache_replication_group#log-delivery-configuration.
  slow_log_delivery_configuration = null

  # The Amazon Resource Name (ARN) of a Redis RDB snapshot file stored in Amazon
  # S3. You can use this parameter to restore from an externally created
  # snapshot. If you have an ElastiCache snapshot, use snapshot_name.
  snapshot_arn = null

  # The name of a snapshot from which to restore the Redis cluster. You can use
  # this to restore from an ElastiCache snapshot. If you have an externally
  # created snapshot, use snapshot_arn.
  snapshot_name = null

  # The number of days for which ElastiCache will retain automatic cache cluster
  # snapshots before deleting them. Set to 0 to disable snapshots.
  snapshot_retention_limit = 15

  # The daily time range during which automated backups are created (e.g.
  # 04:00-09:00). Time zone is UTC. Performance may be degraded while a backup
  # runs. Set to empty string to disable snapshots.
  snapshot_window = "06:00-07:00"

  # The ARN of the SNS Topic to which notifications will be sent when a
  # Replication Group event happens, such as an automatic failover (e.g.
  # arn:aws:sns:*:123456789012:my_sns_topic). An empty string is a valid value
  # if you do not wish to receive notifications via SNS.
  sns_topic_for_notifications = ""

  # A set of tags to set for the ElastiCache Replication Group.
  tags = {}

}

Reference

Inputs
Outputs

Required

enable_automatic_failoverboolrequired

Indicates whether Multi-AZ is enabled. When Multi-AZ is enabled, a read-only replica is automatically promoted to a read-write primary cluster if the existing primary cluster fails. If you specify true, you must specify a value greater than 1 for replication_group_size.

enable_multi_azboolrequired

instance_typestringrequired

The compute and memory capacity of the nodes (e.g. cache.m4.large).

namestringrequired

The name used to namespace all resources created by these templates, including the ElastiCache cluster itself (e.g. rediscache). Must be unique in this region. Must be a lowercase string.

replication_group_sizenumberrequired

The total number of nodes in the Redis Replication Group. E.g. 1 represents just the primary node, 2 represents the primary plus a single Read Replica.

subnet_idslist(string)required

The list of IDs of the subnets in which to deploy the ElasticCache instances. The list must only contain subnets in vpc_id.

vpc_idstringrequired

The ID of the VPC in which to deploy RDS.

Optional

alarm_low_memory_available_thresholdnumberoptional

Trigger an alarm if the amount of free memory, in Bytes, on the node drops below this threshold

Default:100000000

More Details

Details

   Default is 100MB (100 million bytes)

alarm_treat_missing_datastringoptional

Sets how this alarm should handle entering the INSUFFICIENT_DATA state. Based on https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html#alarms-and-missing-data. Must be one of: 'missing', 'ignore', 'breaching' or 'notBreaching'.

Default:"missing"

alarms_sns_topic_arnslist(string)optional

The ARNs of SNS topics where CloudWatch alarms (e.g., for CPU, memory, and disk space usage) should send notifications.

Default:[]

allow_connections_from_cidr_blockslist(string)optional

The list of network CIDR blocks to allow network access to ElastiCache from. One of allow_connections_from_cidr_blocks or allow_connections_from_security_groups must be specified for the ElastiCache instances to be reachable.

Default:[]

allow_connections_from_security_groupslist(string)optional

The list of IDs or Security Groups to allow network access to ElastiCache from. All security groups must either be in the VPC specified by vpc_id, or a peered VPC with the VPC specified by vpc_id. One of allow_connections_from_cidr_blocks or allow_connections_from_security_groups must be specified for the ElastiCache instances to be reachable.

Default:[]

apply_immediatelybooloptional

Specifies whether any modifications are applied immediately, or during the next maintenance window.

Default:false

auth_tokenstringoptional

The password used to access a password protected server. Can be specified only if transit_encryption_enabled = true. Must contain from 16 to 128 alphanumeric characters or symbols (excluding @, <double-quotes>, and /)

Default:null

auto_minor_version_upgradebooloptional

Specifies whether minor version engine upgrades will be applied automatically to the underlying Cache Cluster instances during the maintenance window. Only supported for engine type 'redis' and if the engine version is 6 or higher. Defaults to false (disabled).

Default:false

enable_at_rest_encryptionbooloptional

Whether to enable encryption at rest.

Default:true

enable_cloudwatch_alarmsbooloptional

Set to true to enable several basic CloudWatch alarms around CPU usage, memory usage, and disk space usage. If set to true, make sure to specify SNS topics to send notifications to using alarms_sns_topic_arn.

Default:true

enable_transit_encryptionbooloptional

Whether to enable encryption in transit.

Default:true

engine_log_delivery_configurationobject(…)optional

Specifies the destination and format of Redis Engine Log. See the documentation on Amazon ElastiCache. See Log Delivery Configuration below for more details. You can find more information here https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/elasticache_replication_group#log-delivery-configuration.

Type Details

object({
    destination      = string
    destination_type = string
    log_format       = string
  })

Default:null

maintenance_windowstringoptional

Specifies the weekly time range for when maintenance on the cache cluster is performed (e.g. sun:05:00-sun:09:00). The format is ddd:hh24:mi-ddd:hh24:mi (24H Clock UTC). The minimum maintenance window is a 60 minute period.

Default:"sat:07:00-sat:08:00"

num_node_groupsnumberoptional

Number of node groups (shards) for this Redis replication group. Changing this number will trigger a resizing operation before other settings modifications.

Default:null

parameter_group_namestringoptional

Name of the parameter group to associate with this cache cluster. This can be used to configure custom settings for the cluster.

Default:null

portnumberoptional

The port number on which each of the cache nodes will accept connections (e.g. 6379).

Default:6379

redis_versionstringoptional

Version number of redis to use (e.g. 5.0.6).

Default:"5.0.6"

replicas_per_node_groupnumberoptional

Number of replica nodes in each node group. Changing this number will trigger a resizing operation before other settings modifications. Valid values are 0 to 5.

Default:null

slow_log_delivery_configurationobject(…)optional

Specifies the destination and format of Redis SLOWLOG. See the documentation on Amazon ElastiCache. See Log Delivery Configuration below for more details. You can find more information here https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/elasticache_replication_group#log-delivery-configuration.

Type Details

object({
    destination      = string
    destination_type = string
    log_format       = string
  })

Default:null

snapshot_arnstringoptional

The Amazon Resource Name (ARN) of a Redis RDB snapshot file stored in Amazon S3. You can use this parameter to restore from an externally created snapshot. If you have an ElastiCache snapshot, use snapshot_name.

Default:null

snapshot_namestringoptional

The name of a snapshot from which to restore the Redis cluster. You can use this to restore from an ElastiCache snapshot. If you have an externally created snapshot, use snapshot_arn.

Default:null

snapshot_retention_limitnumberoptional

The number of days for which ElastiCache will retain automatic cache cluster snapshots before deleting them. Set to 0 to disable snapshots.

Default:15

snapshot_windowstringoptional

The daily time range during which automated backups are created (e.g. 04:00-09:00). Time zone is UTC. Performance may be degraded while a backup runs. Set to empty string to disable snapshots.

Default:"06:00-07:00"

sns_topic_for_notificationsstringoptional

The ARN of the SNS Topic to which notifications will be sent when a Replication Group event happens, such as an automatic failover (e.g. arn:aws:sns:*:123456789012:my_sns_topic). An empty string is a valid value if you do not wish to receive notifications via SNS.

Default:""

tagsmap(string)optional

A set of tags to set for the ElastiCache Replication Group.

Default:{}

cache_cluster_ids

The list of AWS cache cluster ids where each one represents a Redis node.

cache_node_id

The id of the ElastiCache node. Note: Each Redis cache cluster has only one node and its id is always 0001.

cache_port

The port number on which each of the cache nodes will accept connections (e.g. 6379).

configuration_endpoint

When cluster mode is enabled, use this endpoint for all operations. Redis will automatically determine which of the cluster's node to access.

primary_endpoint

The primary endpoint is a DNS name that always resolves to the primary node in the Redis cluster.

reader_endpoint

When cluster mode is disabled, use this endpoint for all read operations.

security_group_id

Security Group ID used for redis cluster.

Overview​

Features​

Learn​

Deploy​

Non-production deployment (quick start for learning)​

Production deployment​

Sample Usage​

Reference​

Required​

Optional​

Overview

Features

Learn

Deploy

Non-production deployment (quick start for learning)

Production deployment

Sample Usage

Reference

Required

Optional