Skip to content

Resource: awsElasticacheCluster

Provides an ElastiCache Cluster resource, which manages either a Memcached cluster, a single-node Redis instance, or a [read replica in a Redis (Cluster Mode Enabled) replication group].

For working with Redis (Cluster Mode Enabled) replication groups, see the awsElasticacheReplicationGroup resource.

\~> Note: When you change an attribute, such as numCacheNodes, by default it is applied in the next maintenance window. Because of this, Terraform may report a difference in its planning phase because the actual modification has not yet taken place. You can use the applyImmediately flag to instruct the service to apply the change immediately. Using applyImmediately can result in a brief downtime as the server reboots. See the AWS Documentation on Modifying an ElastiCache Cache Cluster for ElastiCache for Memcached or ElastiCache for Redis for more information.

\~> Note: Any attribute changes that re-create the resource will be applied immediately, regardless of the value of applyImmediately.

Example Usage

Memcached Cluster

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
new aws.elasticacheCluster.ElasticacheCluster(this, "example", {
  clusterId: "cluster-example",
  engine: "memcached",
  nodeType: "cache.m4.large",
  numCacheNodes: 2,
  parameterGroupName: "default.memcached1.4",
  port: 11211,
});

Redis Instance

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
new aws.elasticacheCluster.ElasticacheCluster(this, "example", {
  clusterId: "cluster-example",
  engine: "redis",
  engineVersion: "3.2.10",
  nodeType: "cache.m4.large",
  numCacheNodes: 1,
  parameterGroupName: "default.redis3.2",
  port: 6379,
});

Redis Cluster Mode Disabled Read Replica Instance

These inherit their settings from the replication group.

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
new aws.elasticacheCluster.ElasticacheCluster(this, "replica", {
  clusterId: "cluster-example",
  replicationGroupId: "${aws_elasticache_replication_group.example.id}",
});

Redis Log Delivery configuration

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
new aws.elasticacheCluster.ElasticacheCluster(this, "test", {
  applyImmediately: true,
  clusterId: "mycluster",
  engine: "redis",
  logDeliveryConfiguration: [
    {
      destination: "${aws_cloudwatch_log_group.example.name}",
      destinationType: "cloudwatch-logs",
      logFormat: "text",
      logType: "slow-log",
    },
    {
      destination: "${aws_kinesis_firehose_delivery_stream.example.name}",
      destinationType: "kinesis-firehose",
      logFormat: "json",
      logType: "engine-log",
    },
  ],
  nodeType: "cache.t3.micro",
  numCacheNodes: 1,
  port: 6379,
});

Elasticache Cluster in Outpost

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
const awsVpcExample = new aws.vpc.Vpc(this, "example", {
  cidrBlock: "10.0.0.0/16",
});
const dataAwsOutpostsOutpostsExample =
  new aws.dataAwsOutpostsOutposts.DataAwsOutpostsOutposts(
    this,
    "example_1",
    {}
  );
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
dataAwsOutpostsOutpostsExample.overrideLogicalId("example");
const awsSubnetExample = new aws.subnet.Subnet(this, "example_2", {
  cidrBlock: "10.0.1.0/24",
  tags: {
    Name: "my-subnet",
  },
  vpcId: awsVpcExample.id,
});
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
awsSubnetExample.overrideLogicalId("example");
const dataAwsOutpostsOutpostExample =
  new aws.dataAwsOutpostsOutpost.DataAwsOutpostsOutpost(this, "example_3", {
    id: `\${tolist(${dataAwsOutpostsOutpostsExample.ids})[0]}`,
  });
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
dataAwsOutpostsOutpostExample.overrideLogicalId("example");
const awsElasticacheSubnetGroupExample =
  new aws.elasticacheSubnetGroup.ElasticacheSubnetGroup(this, "example_4", {
    name: "my-cache-subnet",
    subnetIds: [awsSubnetExample.id],
  });
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
awsElasticacheSubnetGroupExample.overrideLogicalId("example");
const awsElasticacheClusterExample =
  new aws.elasticacheCluster.ElasticacheCluster(this, "example_5", {
    clusterId: "cluster-example",
    engine: "memcached",
    nodeType: "cache.r5.large",
    numCacheNodes: 2,
    outpostMode: "single-outpost",
    parameterGroupName: "default.memcached1.4",
    port: 11211,
    preferredOutpostArn: dataAwsOutpostsOutpostExample.arn,
    subnetGroupName: awsElasticacheSubnetGroupExample.name,
  });
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
awsElasticacheClusterExample.overrideLogicalId("example");

Argument Reference

The following arguments are required:

  • clusterId – (Required) Group identifier. ElastiCache converts this name to lowercase. Changing this value will re-create the resource.
  • engine – (Optional, Required if replicationGroupId is not specified) Name of the cache engine to be used for this cache cluster. Valid values are memcached or redis.
  • nodeType – (Required unless replicationGroupId is provided) The instance class used. See AWS documentation for information on supported node types for Redis and guidance on selecting node types for Redis. See AWS documentation for information on supported node types for Memcached and guidance on selecting node types for Memcached. For Memcached, changing this value will re-create the resource.
  • numCacheNodes – (Required unless replicationGroupId is provided) The initial number of cache nodes that the cache cluster will have. For Redis, this value must be 1. For Memcached, this value must be between 1 and 40. If this number is reduced on subsequent runs, the highest numbered nodes will be removed.
  • parameterGroupName – (Required unless replicationGroupId is provided) The name of the parameter group to associate with this cache cluster.

The following arguments are optional:

  • applyImmediately - (Optional) Whether any database modifications are applied immediately, or during the next maintenance window. Default is false. See Amazon ElastiCache Documentation for more information..
  • autoMinorVersionUpgrade - (Optional) 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 true.
  • availabilityZone - (Optional) Availability Zone for the cache cluster. If you want to create cache nodes in multi-az, use preferredAvailabilityZones instead. Default: System chosen Availability Zone. Changing this value will re-create the resource.
  • azMode - (Optional, Memcached only) Whether the nodes in this Memcached node group are created in a single Availability Zone or created across multiple Availability Zones in the cluster's region. Valid values for this parameter are singleAz or crossAz, default is singleAz. If you want to choose crossAz, numCacheNodes must be greater than 1.
  • engineVersion – (Optional) Version number of the cache engine to be used. If not set, defaults to the latest version. See Describe Cache Engine Versions in the AWS Documentation for supported versions. When engine is redis and the version is 6 or higher, the major and minor version can be set, e.g., 62, or the minor version can be unspecified which will use the latest version at creation time, e.g., 6X. Otherwise, specify the full version desired, e.g., 506. The actual engine version used is returned in the attribute engineVersionActual, see Attributes Reference below.
  • finalSnapshotIdentifier - (Optional, Redis only) Name of your final cluster snapshot. If omitted, no final snapshot will be made.
  • ipDiscovery - (Optional) The IP version to advertise in the discovery protocol. Valid values are ipv4 or ipv6.
  • logDeliveryConfiguration - (Optional, Redis only) Specifies the destination and format of Redis SLOWLOG or Redis Engine Log. See the documentation on Amazon ElastiCache. See Log Delivery Configuration below for more details.
  • maintenanceWindow – (Optional) Specifies the weekly time range for when maintenance on the cache cluster is performed. The format is ddd:hh24:miDdd:hh24:mi (24H Clock UTC). The minimum maintenance window is a 60 minute period. Example: sun:05:00Sun:09:00.
  • networkType - (Optional) The IP versions for cache cluster connections. IPv6 is supported with Redis engine 62 onword or Memcached version 166 for all Nitro system instances. Valid values are ipv4, ipv6 or dualStack.
  • notificationTopicArn – (Optional) ARN of an SNS topic to send ElastiCache notifications to. Example: arn:aws:sns:usEast1:012345678999:mySnsTopic.
  • outpostMode - (Optional) Specify the outpost mode that will apply to the cache cluster creation. Valid values are "singleOutpost" and "crossOutpost", however AWS currently only supports "singleOutpost" mode.
  • port – (Optional) The port number on which each of the cache nodes will accept connections. For Memcached the default is 11211, and for Redis the default port is 6379. Cannot be provided with replicationGroupId. Changing this value will re-create the resource.
  • preferredAvailabilityZones - (Optional, Memcached only) List of the Availability Zones in which cache nodes are created. If you are creating your cluster in an Amazon VPC you can only locate nodes in Availability Zones that are associated with the subnets in the selected subnet group. The number of Availability Zones listed must equal the value of numCacheNodes. If you want all the nodes in the same Availability Zone, use availabilityZone instead, or repeat the Availability Zone multiple times in the list. Default: System chosen Availability Zones. Detecting drift of existing node availability zone is not currently supported. Updating this argument by itself to migrate existing node availability zones is not currently supported and will show a perpetual difference.
  • preferredOutpostArn - (Optional, Required if outpostMode is specified) The outpost ARN in which the cache cluster will be created.
  • replicationGroupId - (Optional, Required if engine is not specified) ID of the replication group to which this cluster should belong. If this parameter is specified, the cluster is added to the specified replication group as a read replica; otherwise, the cluster is a standalone primary that is not part of any replication group.
  • securityGroupIds – (Optional, VPC only) One or more VPC security groups associated with the cache cluster
  • securityGroupNames – (Optional, EC2 Classic only) List of security group names to associate with this cache cluster. Changing this value will re-create the resource.
  • snapshotArns – (Optional, Redis only) Single-element string list containing an Amazon Resource Name (ARN) of a Redis RDB snapshot file stored in Amazon S3. The object name cannot contain any commas. Changing snapshotArns forces a new resource.
  • snapshotName - (Optional, Redis only) Name of a snapshot from which to restore data into the new node group. Changing snapshotName forces a new resource.
  • snapshotRetentionLimit - (Optional, Redis only) Number of days for which ElastiCache will retain automatic cache cluster snapshots before deleting them. For example, if you set SnapshotRetentionLimit to 5, then a snapshot that was taken today will be retained for 5 days before being deleted. If the value of SnapshotRetentionLimit is set to zero (0), backups are turned off. Please note that setting a snapshotRetentionLimit is not supported on cache.t1.micro cache nodes
  • snapshotWindow - (Optional, Redis only) Daily time range (in UTC) during which ElastiCache will begin taking a daily snapshot of your cache cluster. Example: 05:00-09:00
  • subnetGroupName – (Optional, VPC only) Name of the subnet group to be used for the cache cluster. Changing this value will re-create the resource.
  • tags - (Optional) Map of tags to assign to the resource. If configured with a provider defaultTags configuration block present, tags with matching keys will overwrite those defined at the provider-level.

Attributes Reference

In addition to all arguments above, the following attributes are exported:

  • arn - The ARN of the created ElastiCache Cluster.
  • engineVersionActual - Because ElastiCache pulls the latest minor or patch for a version, this attribute returns the running version of the cache engine.
  • cacheNodes - List of node objects including id, address, port and availabilityZone.
  • clusterAddress - (Memcached only) DNS name of the cache cluster without the port appended.
  • configurationEndpoint - (Memcached only) Configuration endpoint to allow host discovery.
  • tagsAll - Map of tags assigned to the resource, including those inherited from the provider defaultTags configuration block.

Log Delivery Configuration

The logDeliveryConfiguration block allows the streaming of Redis SLOWLOG or Redis Engine Log to CloudWatch Logs or Kinesis Data Firehose. Max of 2 blocks.

  • destination - Name of either the CloudWatch Logs LogGroup or Kinesis Data Firehose resource.
  • destinationType - For CloudWatch Logs use cloudwatchLogs or for Kinesis Data Firehose use kinesisFirehose.
  • logFormat - Valid values are json or text
  • logType - Valid values are slowLog or engineLog. Max 1 of each.

Timeouts

Configuration options:

  • create - (Default 40M)
  • update - (Default 80M)
  • delete - (Default 40M)

Import

ElastiCache Clusters can be imported using the clusterId, e.g.,

$ terraform import aws_elasticache_cluster.my_cluster my_cluster