Cache Modules 0.23.0Last updated in version 0.23.0

Valkey Module

This module creates an ElastiCache cluster that runs Valkey.

The valkey 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 valkey 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 Valkey deployment

Nodes: The smallest unit of an ElastiCache Valkey deployment is a node. It's basically the network-attached RAM on which the cache engine (Valkey 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.
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.

Concept of Sharding & Replication in ElasticCache Valkey

Valkey implements replication in two ways:

Cluster Mode Disabled: With a single shard that contains all of the cluster's data in each node
Cluster Mode Enabled: With data partitioned across up to 500 shards

Each shard in a replication group has a single read/write primary node and up to 5 read-only replica nodes. 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 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.

You can find more information here: https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/Replication.Valkey.Groups.html

Different Modes of ElasticCache Valkey deployment

There are different types of modes you can deploy ElasticCache Valkey:

Mode	Description	Configuration
Cluster Enabled	- supports sharding - supports replication	- `enable_single_instance_mode = false` - `cluster_mode:num_node_groups > 1`
Cluster Disabled	- no replication - supports sharding	- `enable_single_instance_mode = false` - `cluster_mode:num_node_groups = 1` Note: do not include `.cluster.on` suffix if you are setting `parameter_group_name`.
Single Instance	- no replication - no sharding	- `enable_single_instance_mode = true`

How to Enable Cluster Mode with Single Sharding

By default, if you set cluster_mode::num_node_groups = 1, you are deploying Valkey with the cluster mode disabled. If you want to enable cluster mode for valkey with single sharding, you need to explicitly set the parameter group with cluster-enabled=yes.

Choosing Cluster Mode vs. Single Instance

You can use var.enable_single_instance_mode=true to deploy a single node Valkey instance.

Here are some of the points you may consider while choosing which mode to run:

Scalability: Valkey single instance is limited to a single server node, which can be scaled vertically, while Valkey cluster mode supports horizontal scaling by distributing data across multiple nodes, up to 1000 nodes. This allows for increased capacity, availability, and fault tolerance.
High Availability: Valkey single instance has limited high availability options, as it can only be replicated to a slave node. In contrast, Valkey cluster mode provides more robust high availability features by automatically distributing data across multiple nodes and ensuring data replication, even in the case of node failures.
Performance: Valkey cluster mode provides improved performance, as it allows for distributing the data across multiple nodes, providing more CPU and memory resources. Additionally, Valkey cluster mode uses sharding to distribute keys across multiple nodes, allowing for parallel data processing and faster data access.
Complexity: Valkey cluster mode introduces more complexity than Valkey single instance. Configuring and managing a Valkey cluster requires more effort and expertise, as it involves setting up and managing multiple nodes, and configuring the sharding and replication.

How do you connect to the Valkey Cluster?

When connecting to Valkey (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 Valkey (cluster mode enabled) from your app, direct all reads/writes to the **Configuration Endpoint ** of the Cluster. Ensure you have a client that supports Valkey Cluster. 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.
(Optional) It is possible to link a user_group_id and provide a list of user_id's to add additional layers of security for your cluster or replication group. Refer to the ElasticCache RBAC Access documentation for further information.
(Optional) It is also possible to update the default user id used by AWS when creating a valkey cluster and replace it with your own default user. This is actually recommended by AWS as a first step to securing your Valkey cluster. Refer to the Role-Based Access Control (RBAC) documentation on how to do this. The new user_id can be passed into the Valkey clusters user group via the default_user_id variable.

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 Valkey 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 valkey 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 Valkey 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.

For more info on both methods, see Scaling Single-Node (cluster mode disabled) Clusters.

When Cluster Mode is Enabled

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 Valkey "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

cluster_mode = [
  {
    num_node_groups         = 2
    replicas_per_node_group = 1
  }
]

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.

For more info on scaling "cluster mode enabled" Valkey clusters, see Scaling Multishard (cluster mode disabled) Clusters

How do you use the auto-scaling feature?

Auto Scaling ElastiCache for Valkey clusters summarizes how auto-scaling works for Valkey clusters. You can enable auto-scaling via using the following variables:

enable_auto_scaling: true
auto_scale_dimension: choose one from the supported scalable dimension mentioned below
auto_scale_trigger_metric: choose one from the supported trigger metric mentioned below
auto_scale_min_capacity: choose the desired min capacity
auto_scale_max_capacity: choose the desired max capacity (Note: depends on the configuration of the Valkey cluster. (e.g., 5 would be the maximum for replica auto-scaling)

Prerequisites

ElastiCache for Valkey Auto Scaling is limited to the following:

Valkey (cluster mode enabled) clusters running Valkey engine version 7.2 onwards
Instance type families - R5, R6g, M5, M6g
Instance sizes - Large, XLarge, 2XLarge
Auto Scaling in ElastiCache for Valkey is not supported for clusters running in Global datastores, Outposts or Local Zones.
AWS Auto Scaling for ElastiCache for Valkey is not available in the following regions: China (Beijing), China ( Ningxia), AWS GovCloud (US-West) and AWS GovCloud (US-East).

Supported Predefined Metrics

Here are some predefined metrics available for Valkey: ElastiCachePrimaryEngineCPUUtilization (shards auto-scale), ElastiCacheReplicaEngineCPUUtilization (replica auto-scale). You can find more information here:

Both pages also explain how to use a custom metric and you can find the list of CloudWatch metrics from here: https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/CacheMetrics.Redis.html

Supported Scalable Dimensions

ElastiCache for Valkey supports the following types of automatic scaling dimensions:

elasticache:replication-group:NodeGroups - The number of node groups for an Amazon ElastiCache replication group.
elasticache:replication-group:Replicas - The number of replicas per node group for an Amazon ElastiCache replication group.

Sample Usage

Terraform
Terragrunt

main.tf

# ------------------------------------------------------------------------------------------------------
# DEPLOY GRUNTWORK'S VALKEY MODULE
# ------------------------------------------------------------------------------------------------------

module "valkey" {

  source = "git::git@github.com:gruntwork-io/terraform-aws-cache.git//modules/valkey?ref=v0.23.0"

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

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

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

  # A list of subnet ids where the ElastiCache instances should be deployed. For
  # the standard Gruntwork VPC setup, these should be the private peristence
  # subnet ids.
  subnet_ids = <list(string)>

  # The id of the VPC in which the ElastiCache cluster should be deployed.
  vpc_id = <string>

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

  # A list of additional security group ids to attach
  additional_security_group_ids = []

  # A list of CIDR-formatted IP address ranges that can connect to this
  # ElastiCache cluster. For the standard Gruntwork VPC setup, these should be
  # the CIDR blocks of the private app subnet in this VPC plus the private
  # subnet in the mgmt VPC.
  allow_connections_from_cidr_blocks = []

  # Specifies a list of Security Groups to allow connections from.
  allow_connections_from_security_groups = []

  # Specifies whether any database 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 'valkey' and if the
  # engine version is 6 or higher
  auto_minor_version_upgrade = true

  # Scalable dimension of the scalable target. Supported dimensions are:
  # [elasticache:replication-group:NodeGroups,elasticache:replication-group:Replicas].
  # Documentation can be found in the ScalableDimension parameter at:
  # https://docs.aws.amazon.com/autoscaling/application/APIReference/API_RegisterScalableTarget.html#API_RegisterScalableTarget_RequestParameters.
  auto_scale_dimension = null

  # Max capacity of the scalable target.
  auto_scale_max_capacity = null

  # Min capacity of the scalable target.
  auto_scale_min_capacity = null

  # Metric type to trigger auto-scaling. Supported metric type can be found
  # here:
  # https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/CacheMetrics.Valkey.html
  auto_scale_trigger_metric = null

  # Target value of the auto_scale trigger metric
  auto_scale_trigger_metric_target_value = null

  # The description of the aws_elasticache_security_group that is created.
  # Defaults to 'Security group for the var.name ElastiCache cluster' if not
  # specified.
  aws_elasticache_security_group_description = null

  # The name of the aws_elasticache_security_group that is created. Defaults to
  # var.name if not specified.
  aws_elasticache_security_group_name = null

  # Subnet group for the var.name ElastiCache cluster.
  aws_elasticache_subnet_group_description = null

  # The name of the aws_elasticache_subnet_group that is created. Defaults to
  # var.name-subnet-group if not specified.
  aws_elasticache_subnet_group_name = null

  # Whether to create the ElastiCache user group or not. If not then it will
  # asume the group pointed by `user_group_id` already exists
  create_user_group = true

  # The name of the new 'default' user_id, in the event is different from
  # 'default'.
  default_user_id = "default"

  # Whether to enable encryption at rest.
  enable_at_rest_encryption = true

  # Whether to enable auto-scaling or not. Please refer to the prerequisite
  # section to understand the supported Valkey configuration:
  # https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/AutoScaling.html
  enable_auto_scaling = false

  # Specifies whether a read-only replica is automatically promoted to
  # read/write primary if the existing primary fails. It must be enabled for
  # Valkey (cluster mode enabled) replication groups. This is required if
  # enable_single_instance_mode is set to false.
  enable_automatic_failover = null

  # 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. This is required if
  # enable_single_instance_mode is set to false
  enable_multi_az = null

  # Whether to enable single-node Valkey instance.
  enable_single_instance_mode = false

  # Whether to enable encryption in transit.
  enable_transit_encryption = true

  # Specifies the destination and format of Valkey 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

  # The KMS key ARN used to encrypt data at rest. Can be specified only if
  # at_rest_encryption_enabled = true.
  kms_key_id = null

  # Specifies the destination and format of Valkey SLOWLOG or Valkey 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.
  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 Valkey 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

  #  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

  # The total number of nodes in the Valkey Replication Group. E.g. 1 represents
  # just the primary node, 2 represents the primary plus a single Read Replica.
  # This is required if enable_single_instance_mode is set to false
  replication_group_size = null

  # A set of tags to set for the Security Group created as part of this module.
  security_group_tags = {}

  # Specifies the destination and format of Valkey 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 Valkey 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 Valkey 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 = 7

  # 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. This is required if
  # enable_single_instance_mode is set to false
  sns_topic_for_notifications = null

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

  # The group id of the AWS Elasticache group which can be used to provide
  # access to a Valkey replication group or cluster and allow for RBAC access
  user_group_id = null

  # This is a list of user IDs  that should be added to the group defined in the
  # 'user_group_id' variable. This list should always include the 'default' user
  # in addition to user Ids
  user_ids = []

  # Version number of valkey to use (e.g. 7.2).
  valkey_version = "7.2"

}

terragrunt.hcl

# ------------------------------------------------------------------------------------------------------
# DEPLOY GRUNTWORK'S VALKEY MODULE
# ------------------------------------------------------------------------------------------------------

terraform {
  source = "git::git@github.com:gruntwork-io/terraform-aws-cache.git//modules/valkey?ref=v0.23.0"
}

inputs = {

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

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

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

  # A list of subnet ids where the ElastiCache instances should be deployed. For
  # the standard Gruntwork VPC setup, these should be the private peristence
  # subnet ids.
  subnet_ids = <list(string)>

  # The id of the VPC in which the ElastiCache cluster should be deployed.
  vpc_id = <string>

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

  # A list of additional security group ids to attach
  additional_security_group_ids = []

  # A list of CIDR-formatted IP address ranges that can connect to this
  # ElastiCache cluster. For the standard Gruntwork VPC setup, these should be
  # the CIDR blocks of the private app subnet in this VPC plus the private
  # subnet in the mgmt VPC.
  allow_connections_from_cidr_blocks = []

  # Specifies a list of Security Groups to allow connections from.
  allow_connections_from_security_groups = []

  # Specifies whether any database 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 'valkey' and if the
  # engine version is 6 or higher
  auto_minor_version_upgrade = true

  # Scalable dimension of the scalable target. Supported dimensions are:
  # [elasticache:replication-group:NodeGroups,elasticache:replication-group:Replicas].
  # Documentation can be found in the ScalableDimension parameter at:
  # https://docs.aws.amazon.com/autoscaling/application/APIReference/API_RegisterScalableTarget.html#API_RegisterScalableTarget_RequestParameters.
  auto_scale_dimension = null

  # Max capacity of the scalable target.
  auto_scale_max_capacity = null

  # Min capacity of the scalable target.
  auto_scale_min_capacity = null

  # Metric type to trigger auto-scaling. Supported metric type can be found
  # here:
  # https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/CacheMetrics.Valkey.html
  auto_scale_trigger_metric = null

  # Target value of the auto_scale trigger metric
  auto_scale_trigger_metric_target_value = null

  # The description of the aws_elasticache_security_group that is created.
  # Defaults to 'Security group for the var.name ElastiCache cluster' if not
  # specified.
  aws_elasticache_security_group_description = null

  # The name of the aws_elasticache_security_group that is created. Defaults to
  # var.name if not specified.
  aws_elasticache_security_group_name = null

  # Subnet group for the var.name ElastiCache cluster.
  aws_elasticache_subnet_group_description = null

  # The name of the aws_elasticache_subnet_group that is created. Defaults to
  # var.name-subnet-group if not specified.
  aws_elasticache_subnet_group_name = null

  # Whether to create the ElastiCache user group or not. If not then it will
  # asume the group pointed by `user_group_id` already exists
  create_user_group = true

  # The name of the new 'default' user_id, in the event is different from
  # 'default'.
  default_user_id = "default"

  # Whether to enable encryption at rest.
  enable_at_rest_encryption = true

  # Whether to enable auto-scaling or not. Please refer to the prerequisite
  # section to understand the supported Valkey configuration:
  # https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/AutoScaling.html
  enable_auto_scaling = false

  # Specifies whether a read-only replica is automatically promoted to
  # read/write primary if the existing primary fails. It must be enabled for
  # Valkey (cluster mode enabled) replication groups. This is required if
  # enable_single_instance_mode is set to false.
  enable_automatic_failover = null

  # 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. This is required if
  # enable_single_instance_mode is set to false
  enable_multi_az = null

  # Whether to enable single-node Valkey instance.
  enable_single_instance_mode = false

  # Whether to enable encryption in transit.
  enable_transit_encryption = true

  # Specifies the destination and format of Valkey 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

  # The KMS key ARN used to encrypt data at rest. Can be specified only if
  # at_rest_encryption_enabled = true.
  kms_key_id = null

  # Specifies the destination and format of Valkey SLOWLOG or Valkey 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.
  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 Valkey 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

  #  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

  # The total number of nodes in the Valkey Replication Group. E.g. 1 represents
  # just the primary node, 2 represents the primary plus a single Read Replica.
  # This is required if enable_single_instance_mode is set to false
  replication_group_size = null

  # A set of tags to set for the Security Group created as part of this module.
  security_group_tags = {}

  # Specifies the destination and format of Valkey 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 Valkey 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 Valkey 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 = 7

  # 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. This is required if
  # enable_single_instance_mode is set to false
  sns_topic_for_notifications = null

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

  # The group id of the AWS Elasticache group which can be used to provide
  # access to a Valkey replication group or cluster and allow for RBAC access
  user_group_id = null

  # This is a list of user IDs  that should be added to the group defined in the
  # 'user_group_id' variable. This list should always include the 'default' user
  # in addition to user Ids
  user_ids = []

  # Version number of valkey to use (e.g. 7.2).
  valkey_version = "7.2"

}

Reference

Inputs
Outputs

Required

instance_typestringrequired

The compute and memory capacity of the nodes (e.g. cache.t3.medium).

namestringrequired

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

subnet_idslist(string)required

A list of subnet ids where the ElastiCache instances should be deployed. For the standard Gruntwork VPC setup, these should be the private peristence subnet ids.

vpc_idstringrequired

The id of the VPC in which the ElastiCache cluster should be deployed.

Optional

additional_security_group_idslist(string)optional

A list of additional security group ids to attach

Default:[]

allow_connections_from_cidr_blockslist(string)optional

A list of CIDR-formatted IP address ranges that can connect to this ElastiCache cluster. For the standard Gruntwork VPC setup, these should be the CIDR blocks of the private app subnet in this VPC plus the private subnet in the mgmt VPC.

Default:[]

allow_connections_from_security_groupslist(string)optional

Specifies a list of Security Groups to allow connections from.

Default:[]

apply_immediatelybooloptional

Specifies whether any database 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 'valkey' and if the engine version is 6 or higher

Default:true

auto_scale_dimensionstringoptional

Scalable dimension of the scalable target. Supported dimensions are: [elasticache:replication-group:NodeGroups,elasticache:replication-group:Replicas]. Documentation can be found in the ScalableDimension parameter at: https://docs.aws.amazon.com/autoscaling/application/APIReference/API_RegisterScalableTarget.html#API_RegisterScalableTarget_RequestParameters.

Default:null

auto_scale_max_capacitynumberoptional

Max capacity of the scalable target.

Default:null

auto_scale_min_capacitynumberoptional

Min capacity of the scalable target.

Default:null

auto_scale_trigger_metricstringoptional

Metric type to trigger auto-scaling. Supported metric type can be found here: https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/CacheMetrics.Valkey.html

Default:null

auto_scale_trigger_metric_target_valuenumberoptional

Target value of the auto_scale trigger metric

Default:null

aws_elasticache_security_group_descriptionstringoptional

The description of the aws_elasticache_security_group that is created. Defaults to 'Security group for the name ElastiCache cluster' if not specified.

Default:null

aws_elasticache_security_group_namestringoptional

The name of the aws_elasticache_security_group that is created. Defaults to name if not specified.

Default:null

aws_elasticache_subnet_group_descriptionstringoptional

Subnet group for the name ElastiCache cluster.

Default:null

aws_elasticache_subnet_group_namestringoptional

The name of the aws_elasticache_subnet_group that is created. Defaults to name-subnet-group if not specified.

Default:null

create_user_groupbooloptional

Whether to create the ElastiCache user group or not. If not then it will asume the group pointed by user_group_id already exists

Default:true

default_user_idstringoptional

The name of the new 'default' user_id, in the event is different from 'default'.

Default:"default"

enable_at_rest_encryptionbooloptional

Whether to enable encryption at rest.

Default:true

enable_auto_scalingbooloptional

Whether to enable auto-scaling or not. Please refer to the prerequisite section to understand the supported Valkey configuration: https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/AutoScaling.html

Default:false

enable_automatic_failoverbooloptional

Specifies whether a read-only replica is automatically promoted to read/write primary if the existing primary fails. It must be enabled for Valkey (cluster mode enabled) replication groups. This is required if enable_single_instance_mode is set to false.

Default:null

enable_multi_azbooloptional

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. This is required if enable_single_instance_mode is set to false

Default:null

enable_single_instance_modebooloptional

Whether to enable single-node Valkey instance.

Default:false

enable_transit_encryptionbooloptional

Whether to enable encryption in transit.

Default:true

engine_log_delivery_configurationobject(…)optional

Specifies the destination and format of Valkey 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

kms_key_idstringoptional

The KMS key ARN used to encrypt data at rest. Can be specified only if at_rest_encryption_enabled = true.

Default:null

log_delivery_configurationobject(…)optional

Specifies the destination and format of Valkey SLOWLOG or Valkey 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
    log_type         = 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 Valkey 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

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

replication_group_sizenumberoptional

The total number of nodes in the Valkey Replication Group. E.g. 1 represents just the primary node, 2 represents the primary plus a single Read Replica. This is required if enable_single_instance_mode is set to false

Default:null

security_group_tagsmap(string)optional

A set of tags to set for the Security Group created as part of this module.

Default:{}

slow_log_delivery_configurationobject(…)optional

Specifies the destination and format of Valkey 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 Valkey 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 Valkey 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:7

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. This is required if enable_single_instance_mode is set to false

Default:null

tagsmap(string)optional

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

Default:{}

user_group_idstringoptional

The group id of the AWS Elasticache group which can be used to provide access to a Valkey replication group or cluster and allow for RBAC access

Default:null

user_idslist(string)optional

This is a list of user IDs that should be added to the group defined in the 'user_group_id' variable. This list should always include the 'default' user in addition to user Ids

Default:[]

More Details

Details


   When a Valkey cluster is created, there is always a default user, and that
   user always must be added to the group.

valkey_versionstringoptional

Version number of valkey to use (e.g. 7.2).

Default:"7.2"

cache_addresses

cache_cluster_ids

cache_node_id

cache_node_ids

cache_port

configuration_endpoint

parameter_group

primary_endpoint

reader_endpoint

security_group_id

About Amazon ElastiCache​

What is Amazon ElastiCache?​

Structure of an ElastiCache Valkey deployment​

Concept of Sharding & Replication in ElasticCache Valkey​

Different Modes of ElasticCache Valkey deployment​

How to Enable Cluster Mode with Single Sharding​

Choosing Cluster Mode vs. Single Instance​

How do you connect to the Valkey Cluster?​

How do you scale the Valkey Cluster?​

When Cluster Mode is Disabled​

When Cluster Mode is Enabled​

How do you use the auto-scaling feature?​

Prerequisites​

Supported Predefined Metrics​

Supported Scalable Dimensions​

Sample Usage​

Reference​

Required​

Optional​

About Amazon ElastiCache

What is Amazon ElastiCache?

Structure of an ElastiCache Valkey deployment

Concept of Sharding & Replication in ElasticCache Valkey

Different Modes of ElasticCache Valkey deployment

How to Enable Cluster Mode with Single Sharding

Choosing Cluster Mode vs. Single Instance

How do you connect to the Valkey Cluster?

How do you scale the Valkey Cluster?

When Cluster Mode is Disabled

When Cluster Mode is Enabled

How do you use the auto-scaling feature?

Prerequisites

Supported Predefined Metrics

Supported Scalable Dimensions

Sample Usage

Reference

Required

Optional