# Managing clusters in ElastiCache
A *cluster* is a collection of one or more cache nodes, all of which run an instance of the Valkey, Memcached, and Redis OSS engine software. When you create a cluster, you specify the engine and version for all of the nodes to use.
**Valkey and Redis OSS clusters**
The following diagram illustrates a typical Valkey or Redis OSS cluster. These clusters can contain a single node or up to six nodes inside a shard (API/CLI: node group), A single-node Valkey or Redis OSS (cluster mode disabled) cluster has no shard, and a multi-node Valkey or Redis OSS (cluster mode disabled) cluster has a single shard. Valkey or Redis OSS (cluster mode enabled) clusters can have up to 500 shards, with your data partitioned across the shards. The node or shard limit can be increased to a maximum of 500 per cluster if the engine version is Valkey 7.2 and higher or Redis OSS 5.0.6 and 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. For more information, see [Creating a subnet group](SubnetGroups.Creating.md). For versions below 5.0.6, the limit is 250 per cluster.
To request a limit increase, see [AWS Service Limits](https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html) and choose the limit type **Nodes per cluster per instance type**.
When you have multiple nodes in a Valkey or Redis OSS shard, one of the nodes is a read/write primary node. All other nodes in the shard are read-only replicas.
Typical Valkey or Redis OSS clusters look as follows.
![\[Image: Typical Valkey and Redis OSS Clusters\]](http://docs.aws.amazon.com/AmazonElastiCache/latest/dg/images/ElastiCache-Cluster-Redis.png)
**Memcached clusters**
Typical Memcached clusters look as follows. Memcached clusters contain from 1 to 60 nodes, across which you horizontally partition your data.
![\[Image: Typical Memcached Cluster\]](http://docs.aws.amazon.com/AmazonElastiCache/latest/dg/images/ElastiCache-Cluster-Memcached.png)
**Elasticache operations for Valkey, Memcached, and Redis OSS**
Most ElastiCache operations are performed at the cluster level. You can set up a cluster with a specific number of nodes and a parameter group that controls the properties for each node. All nodes within a cluster are designed to be of the same node type and have the same parameter and security group settings.
Every cluster must have a cluster identifier. The cluster identifier is a customer-supplied name for the cluster. This identifier specifies a particular cluster when interacting with the ElastiCache API and AWS CLI commands. The cluster identifier must be unique for that customer in an AWS Region.
ElastiCache supports multiple engine versions. Unless you have specific reasons, we recommend using the latest version.
ElastiCache clusters are designed to be accessed using an Amazon EC2 instance. If you launch your cluster in a virtual private cloud (VPC) based on the Amazon VPC service, you can access it from outside AWS. For more information, see [Accessing ElastiCache resources from outside AWS](accessing-elasticache.md#access-from-outside-aws).
For a list of supported versions, see [Supported engines and versions](VersionManagement.md#supported-engine-versions), [Supported Redis OSS engine versions](engine-versions.md#supported-engine-versions.redis), and [Supported ElastiCache for Memcached versions](engine-versions.md#supported-engine-versions-mc).
# Choosing a network type in ElastiCache
ElastiCache supports the Internet Protocol versions 4 and 6 (IPv4 and IPv6), allowing you to configure your cluster to accept:
+ only IPv4 connections,
+ only IPv6 connections,
+ both IPv4 and IPv6 connections (dual-stack)
IPv6 is supported for workloads using Valkey 7.2 and onward, or Redis OSS 6.2 and onward, on all instances built on the [Nitro system](https://aws.amazon.com/ec2/nitro/). There are no additional charges for accessing ElastiCache over IPv6.
**Note**
Migration of clusters created prior to the availability of IPV6 / dual-stack is not supported. Switching between network types on newly created clusters is also not supported.
IPv6 is supported for workloads using Memcached 1.6.6 onward on all instances built on the [Nitro system](https://aws.amazon.com/ec2/nitro/). There are no additional charges for accessing ElastiCache over IPv6.
## Configuring subnets for network type
If you create a cluster in an Amazon VPC, you must specify a subnet group. ElastiCache uses that subnet group to choose a subnet and IP addresses within that subnet to associate with your nodes. ElastiCache clusters require a dual-stack subnet with both IPv4 and IPv6 addresses assigned to them to operate in dual-stack mode and an IPv6-only subnet to operate as IPv6-only.
## Using dual-stack
When using ElastiCache for Redis OSS in cluster mode enabled, from an application's perspective, connecting to all the cluster nodes through the configuration endpoint is no different than connecting directly to an individual cache node. To achieve this, a cluster-aware client must engage in a cluster discovery process and request the configuration information for all nodes. Redis' discovery protocol supports only one IP per node.
When you create a cluster with ElastiCache for Memcachedand choose dual-stack as the network type, you then need to designate an IP discovery type – either IPv4 or IPv6. ElastiCache will default the network type and IP discovery to IPv6, but that can be changed. If you use Auto Discovery, only the IP addresses of your chosen IP type are returned returned to the Memcached client. For more information, see [Automatically identify nodes in your cluster (Memcached)](AutoDiscovery.md).
To maintain backwards compatibility with all existing clients, IP discovery is introduced, which allows you to select the IP type (i.e., IPv4 or IPv6) to advertise in the discovery protocol. While this limits auto discovery to only one IP type, dual-stack is still beneficial for cluster mode enabled workloads, as it enables migrations (or rollbacks) from an IPv4 to an IPv6 Discovery IP type with no downtime.
## TLS enabled dual stack ElastiCache clusters
When TLS is enabled for ElastiCache clusters the cluster discovery functions such as `cluster slots`, `cluster shards`, and `cluster nodes` with Valkey or Redis OSS and `config get cluster` with Memcached return hostnames instead of IPs. The hostnames are then used instead of IPs to connect to the ElastiCache cluster and perform a TLS handshake. This means that clients won’t be affected by the IP Discovery parameter. *For TLS enabled clusters the IP Discovery parameter has no effect on the preferred IP protocol.* Instead, the IP protocol used will be determined by which IP protocol the client prefers when resolving DNS hostnames.
For examples on how to configure an IP protocol preference when resolving DNS hostnames, see [TLS enabled dual stack ElastiCache clusters](BestPractices.md#network-type-configuring-tls-enabled-dual-stack).
## Using the AWS Management Console (Valkey and Redis OSS)
When creating a cluster using the AWS Management Console, under **Connectivity**, choose a network type, either **IPv4**, **IPv6** or **Dual stack**. If you are creating a Valkey or Redis OSS (cluster mode enabled) cluster and choose dual stack, you then must select a **Discovery IP type**, either IPv6 or IPv4.
For more information, see [Creating a Valkey or Redis OSS (cluster mode enabled) cluster (Console)](Clusters.Create.md#Clusters.Create.CON.RedisCluster) or [Creating a Valkey or Redis OSS (cluster mode disabled) (Console)](Clusters.Create.md#Clusters.Create.CON.Redis).
When creating a replication group using the AWS Management Console, choose a network type, either **IPv4**, **IPv6** or **Dual stack**. If you choose dual stack, you then must select a **Discovery IP type**, either IPv6 or IPv4.
For more information, see [Creating a Valkey or Redis OSS (Cluster Mode Disabled) replication group from scratch](Replication.CreatingReplGroup.NoExistingCluster.Classic.md) or [Creating a replication group in Valkey or Redis OSS (Cluster Mode Enabled) from scratch](Replication.CreatingReplGroup.NoExistingCluster.Cluster.md).
## Using the AWS Management Console (Memcached)
When creating a cluster using the AWS Management Console, under **Connectivity**, choose a network type, either **IPv4**, **IPv6** or **Dual stack**. If you choose dual stack, you then must select a **Discovery IP type**, either IPv6 or IPv4.
For more information, see [Creating a Memcached cluster (console)](Clusters.Create-mc.md#Clusters.Create.CON.Memcached).
## Using the CLI with Valkey, Memcached, or Redis OSS.
**Redis OSS**
When creating a cluster with Valkey or Redis OSS using the CLI, you use the [create-cache-cluster](https://docs.aws.amazon.com/cli/latest/reference/elasticache/create-cache-cluster.html) command and specify the `NetworkType` and `IPDiscovery` parameters:
For Linux, macOS, or Unix:
```
aws elasticache create-cache-cluster \
--cache-cluster-id "cluster-test" \
--engine redis \
--cache-node-type cache.m5.large \
--num-cache-nodes 1 \
--network-type dual_stack \
--ip-discovery ipv4
```
For Windows:
```
aws elasticache create-cache-cluster ^
--cache-cluster-id "cluster-test" ^
--engine redis ^
--cache-node-type cache.m5.large ^
--num-cache-nodes 1 ^
--network-type dual_stack ^
--ip-discovery ipv4
```
When creating a replication group with cluster mode disabled using the CLI, you use the [create-replication-group](https://docs.aws.amazon.com/cli/latest/reference/elasticache/create-replication-group.html) command and specify the `NetworkType` and `IPDiscovery` parameters:
For Linux, macOS, or Unix:
```
aws elasticache create-replication-group \
--replication-group-id sample-repl-group \
--replication-group-description "demo cluster with replicas" \
--num-cache-clusters 3 \
--primary-cluster-id redis01 \
--network-type dual_stack \
--ip-discovery ipv4
```
For Windows:
```
aws elasticache create-replication-group ^
--replication-group-id sample-repl-group ^
--replication-group-description "demo cluster with replicas" ^
--num-cache-clusters 3 ^
--primary-cluster-id redis01 ^
--network-type dual_stack ^
--ip-discovery ipv4
```
When creating a replication group with cluster mode enabled and use IPv4 for IP discovery using the CLI, you use the [create-replication-group](https://docs.aws.amazon.com/cli/latest/reference/elasticache/create-replication-group.html) command and specify the `NetworkType` and `IPDiscovery` parameters:
For Linux, macOS, or Unix:
```
aws elasticache create-replication-group \
--replication-group-id demo-cluster \
--replication-group-description "demo cluster" \
--cache-node-type cache.m5.large \
--num-node-groups 2 \
--engine redis \
--cache-subnet-group-name xyz \
--network-type dual_stack \
--ip-discovery ipv4 \
--region us-east-1
```
For Windows:
```
aws elasticache create-replication-group ^
--replication-group-id demo-cluster ^
--replication-group-description "demo cluster" ^
--cache-node-type cache.m5.large ^
--num-node-groups 2 ^
--engine redis ^
--cache-subnet-group-name xyz ^
--network-type dual_stack ^
--ip-discovery ipv4 ^
--region us-east-1
```
When creating a replication group with cluster mode enabled and use IPv6 for IP discovery using the CLI, you use the [create-replication-group](https://docs.aws.amazon.com/cli/latest/reference/elasticache/create-replication-group.html) command and specify the `NetworkType` and `IPDiscovery` parameters:
For Linux, macOS, or Unix:
```
aws elasticache create-replication-group \
--replication-group-id demo-cluster \
--replication-group-description "demo cluster" \
--cache-node-type cache.m5.large \
--num-node-groups 2 \
--engine redis \
--cache-subnet-group-name xyz \
--network-type dual_stack \
--ip-discovery ipv6 \
--region us-east-1
```
For Windows:
```
aws elasticache create-replication-group ^
--replication-group-id demo-cluster ^
--replication-group-description "demo cluster" ^
--cache-node-type cache.m5.large ^
--num-node-groups 2 ^
--engine redis ^
--cache-subnet-group-name xyz ^
--network-type dual_stack ^
--ip-discovery ipv6 ^
--region us-east-1
```
**Memcached**
When creating a cluster with Memcached using the CLI, you use the [create-cache-cluster](https://docs.aws.amazon.com/cli/latest/reference/elasticache/create-cache-cluster.html) command and specify the `NetworkType` and `IPDiscovery` parameters:
For Linux, macOS, or Unix:
```
aws elasticache create-cache-cluster \
--cache-cluster-id "cluster-test" \
--engine memcached \
--cache-node-type cache.m5.large \
--num-cache-nodes 1 \
--network-type dual_stack \
--ip-discovery ipv4
```
For Windows:
```
aws elasticache create-cache-cluster ^
--cache-cluster-id "cluster-test" ^
--engine memcached ^
--cache-node-type cache.m5.large ^
--num-cache-nodes 1 ^
--network-type dual_stack ^
--ip-discovery ipv4
```
# Automatically identify nodes in your cluster (Memcached)
For clusters running the Memcached engine, ElastiCache supports *Auto Discovery*—the ability for client programs to automatically identify all of the nodes in a cluster, and to initiate and maintain connections to all of these nodes.
**Note**
Auto Discovery is added for clusters running on Amazon ElastiCache Memcached. Auto Discovery is not available for Valkey or Redis OSS engines.
With Auto Discovery, your application does not need to manually connect to individual cache nodes; instead, your application connects to one Memcached node and retrieves the list of nodes. From that list your application is aware of the rest of the nodes in the cluster and can connect to any of them. You do not need to hard code the individual cache node endpoints in your application.
If you are using dual stack network type on your cluster, Auto Discovery will return only IPv4 or IPv6 addresses, depending on which one you select. For more information, see [Choosing a network type in ElastiCache](network-type.md) .
All of the cache nodes in the cluster maintain a list of metadata about all of the other nodes. This metadata is updated whenever nodes are added or removed from the cluster.
**Topics**
+ [
# Benefits of Auto Discovery with Memcached
](AutoDiscovery.Benefits.md)
+ [
# How Auto Discovery Works
](AutoDiscovery.HowAutoDiscoveryWorks.md)
+ [
# Using Auto Discovery
](AutoDiscovery.Using.md)
+ [
# Connecting to Memcached Cache Nodes Manually
](AutoDiscovery.Manual.md)
+ [
# Adding Auto Discovery to your Memcached client library
](AutoDiscovery.AddingToYourClientLibrary.md)
+ [
# ElastiCache clients with auto discovery
](Clients.md)
# Benefits of Auto Discovery with Memcached
When using Memcached, Auto Discovery offers the following benefits:
+ When you increase the number of nodes in a cluster, the new nodes register themselves with the configuration endpoint and with all of the other nodes. When you remove nodes from the cache cluster, the departing nodes deregister themselves. In both cases, all of the other nodes in the cluster are updated with the latest cache node metadata.
+ Cache node failures are automatically detected; failed nodes are automatically replaced.
**Note**
Until node replacement completes, the node will continue to fail.
+ A client program only needs to connect to the configuration endpoint. After that, the Auto Discovery library connects to all of the other nodes in the cluster.
+ Client programs poll the cluster once per minute (this interval can be adjusted if necessary). If there are any changes to the cluster configuration, such as new or deleted nodes, the client receives an updated list of metadata. Then the client connects to, or disconnects from, these nodes as needed.
Auto Discovery is enabled on all ElastiCache Memcached clusters. You do not need to reboot any of your cache nodes to use this feature.
# How Auto Discovery Works
**Topics**
+ [
## Connecting to Cache Nodes
](#AutoDiscovery.HowAutoDiscoveryWorks.Connecting)
+ [
## Normal Cluster Operations
](#AutoDiscovery.HowAutoDiscoveryWorks.NormalOps)
+ [
## Other Operations
](#AutoDiscovery.HowAutoDiscoveryWorks.OtherOps)
This section describes how client applications use the ElastiCache Cluster Client to manage cache node connections, and interact with data items in the cache.
## Connecting to Cache Nodes
From the application's point of view, connecting to the cluster configuration endpoint is no different from connecting directly to an individual cache node. The following sequence diagram shows the process of connecting to cache nodes.
![\[Connecting to Cache Nodes\]](http://docs.aws.amazon.com/AmazonElastiCache/latest/dg/images/autodiscovery_cluster_membership_refresh-diagram.png)
**Process of Connecting to Cache Nodes**
| | |
| --- |--- |
| ![\[1\]](http://docs.aws.amazon.com/AmazonElastiCache/latest/dg/images/callouts/1.png) | The application resolves the configuration endpoint's DNS name. Because the configuration endpoint maintains CNAME entries for all of the cache nodes, the DNS name resolves to one of the nodes; the client can then connect to that node. |
| ![\[2\]](http://docs.aws.amazon.com/AmazonElastiCache/latest/dg/images/callouts/2.png) | The client requests the configuration information for all of the other nodes. Since each node maintains configuration information for all of the nodes in the cluster, any node can pass configuration information to the client upon request. |
| ![\[3\]](http://docs.aws.amazon.com/AmazonElastiCache/latest/dg/images/callouts/3.png) | The client receives the current list of cache node hostnames and IP addresses. It can then connect to all of the other nodes in the cluster. |
**Note**
The client program refreshes its list of cache node hostnames and IP addresses once per minute. This polling interval can be adjusted if necessary.
## Normal Cluster Operations
When the application has connected to all of the cache nodes, ElastiCache Cluster Client determines which nodes should store individual data items, and which nodes should be queried for those data items later. The following sequence diagram shows the process of normal cluster operations.
![\[Normal Cluster Operations\]](http://docs.aws.amazon.com/AmazonElastiCache/latest/dg/images/autodiscovery_normal_cache_usage-diagram.png)
**Process of Normal Cluster Operations**
| | |
| --- |--- |
| ![\[1\]](http://docs.aws.amazon.com/AmazonElastiCache/latest/dg/images/callouts/1.png) | The application issues a get request for a particular data item, identified by its key. |
| ![\[2\]](http://docs.aws.amazon.com/AmazonElastiCache/latest/dg/images/callouts/2.png) | The client uses a hashing algorithm against the key to determine which cache node contains the data item. |
| ![\[3\]](http://docs.aws.amazon.com/AmazonElastiCache/latest/dg/images/callouts/3.png) | The data item is requested from the appropriate node. |
| ![\[4\]](http://docs.aws.amazon.com/AmazonElastiCache/latest/dg/images/callouts/4.png) | The data item is returned to the application. |
## Other Operations
In some situations, you might make a change to a cluster's nodes. For example, you might add an additional node to accommodate additional demand, or delete a node to save money during periods of reduced demand. Or you might replace a node due to a node failure of one sort or another.
When there is a change in the cluster that requires a metadata update to the cluster's endpoints, that change is made to all nodes at the same time. Thus the metadata in any given node is consistent with the metadata in all of the other nodes in the cluster.
In each of these cases, the metadata is consistent among all the nodes at all times since the metadata is updated at the same time for all nodes in the cluster. You should always use the configuration endpoint to obtain the endpoints of the various nodes in the cluster. By using the configuration endpoint, you ensure that you will not be obtaining endpoint data from a node that “disappears” on you.
### Adding a Node
During the time that the node is being spun up, its endpoint is not included in the metadata. As soon as the node is available, it is added to the metadata of each of the cluster’s nodes. In this scenario, the metadata is consistent among all the nodes and you will be able to interact with the new node only after it is available. Before the node being available, you will not know about it and will interact with the nodes in your cluster the same as though the new node does not exist.
### Deleting a Node
When a node is removed, its endpoint is first removed from the metadata and then the node is removed from the cluster. In this scenario the metadata in all the nodes is consistent and there is no time in which it will contain the endpoint for the node to be removed while the node is not available. During the node removal time it is not reported in the metadata and so your application will only be interacting with the n-1 remaining nodes, as though the node does not exist.
### Replacing a Node
If a node fails, ElastiCache takes down that node and spins up a replacement. The replacement process takes a few minutes. During this time the metadata in all the nodes still shows the endpoint for the failed node, but any attempt to interact with the node will fail. Therefore, your logic should always include retry logic.
# Using Auto Discovery
To begin using Auto Discovery with ElastiCache for Memcached, follow these steps:
+ [Obtain the Configuration Endpoint](#AutoDiscovery.Using.ConfigEndpoint)
+ [Download the ElastiCache Cluster Client](#AutoDiscovery.Using.ClusterClient)
+ [Modify Your Application Program](#AutoDiscovery.Using.ModifyApp)
## Obtain the Configuration Endpoint
To connect to a cluster, client programs must know the cluster configuration endpoint. See the topic [Finding a Cluster's Endpoints (Console) (Memcached)](Endpoints.md#Endpoints.Find.Memcached)
You can also use the `aws elasticache describe-cache-clusters` command with the `--show-cache-node-info` parameter:
Whatever method you use to find the cluster's endpoints, the configuration endpoint will always have **.cfg** in its address.
**Example Finding endpoints using the AWS CLI for ElastiCache**
For Linux, macOS, or Unix:
```
aws elasticache describe-cache-clusters \
--cache-cluster-id mycluster \
--show-cache-node-info
```
For Windows:
```
aws elasticache describe-cache-clusters ^
--cache-cluster-id mycluster ^
--show-cache-node-info
```
This operation produces output similar to the following (JSON format):
```
{
"CacheClusters": [
{
"Engine": "memcached",
"CacheNodes": [
{
"CacheNodeId": "0001",
"Endpoint": {
"Port": 11211,
"Address": "mycluster.fnjyzo.cfg.0001.use1.cache.amazonaws.com"
},
"CacheNodeStatus": "available",
"ParameterGroupStatus": "in-sync",
"CacheNodeCreateTime": "2016-10-12T21:39:28.001Z",
"CustomerAvailabilityZone": "us-east-1e"
},
{
"CacheNodeId": "0002",
"Endpoint": {
"Port": 11211,
"Address": "mycluster.fnjyzo.cfg.0002.use1.cache.amazonaws.com"
},
"CacheNodeStatus": "available",
"ParameterGroupStatus": "in-sync",
"CacheNodeCreateTime": "2016-10-12T21:39:28.001Z",
"CustomerAvailabilityZone": "us-east-1a"
}
],
"CacheParameterGroup": {
"CacheNodeIdsToReboot": [],
"CacheParameterGroupName": "default.memcached1.4",
"ParameterApplyStatus": "in-sync"
},
"CacheClusterId": "mycluster",
"PreferredAvailabilityZone": "Multiple",
"ConfigurationEndpoint": {
"Port": 11211,
"Address": "mycluster.fnjyzo.cfg.use1.cache.amazonaws.com"
},
"CacheSecurityGroups": [],
"CacheClusterCreateTime": "2016-10-12T21:39:28.001Z",
"AutoMinorVersionUpgrade": true,
"CacheClusterStatus": "available",
"NumCacheNodes": 2,
"ClientDownloadLandingPage": "https://console.aws.amazon.com/elasticache/home#client-download:",
"CacheSubnetGroupName": "default",
"EngineVersion": "1.4.24",
"PendingModifiedValues": {},
"PreferredMaintenanceWindow": "sat:06:00-sat:07:00",
"CacheNodeType": "cache.r3.large"
}
]
}
```
## Download the ElastiCache Cluster Client
To take advantage of Auto Discovery, client programs must use the *ElastiCache Cluster Client*. The ElastiCache Cluster Client is available for Java, PHP, and .NET and contains all of the necessary logic for discovering and connecting to all of your cache nodes.
**To download the ElastiCache Cluster Client**
1. Sign in to the AWS Management Console and open the ElastiCache console at [https://console.aws.amazon.com/elasticache/](https://console.aws.amazon.com/elasticache/).
1. From the ElastiCache console, choose **ElastiCache Cluster Client** then choose **Download**.
The source code for the ElastiCache Cluster Client for Java is available at [https://github.com/amazonwebservices/aws-elasticache-cluster-client-memcached-for-java](https://github.com/amazonwebservices/aws-elasticache-cluster-client-memcached-for-java). This library is based on the popular Spymemcached client. The ElastiCache Cluster Client is released under the Amazon Software License [https://aws.amazon.com/asl](https://aws.amazon.com/asl). You are free to modify the source code as you see fit. You can even incorporate the code into other open source Memcached libraries, or into your own client code.
**Note**
To use the ElastiCache Cluster Client for PHP, you will first need to install it on your Amazon EC2 instance. For more information, see [Installing the ElastiCache cluster client for PHP](Appendix.PHPAutoDiscoverySetup.md).
For a TLS supported client download the binary with PHP version 7.4 or higher.
To use the ElastiCache Cluster Client for .NET, you will first need to install it on your Amazon EC2 instance. For more information, see [Installing the ElastiCache cluster client for .NET](Appendix.DotNETAutoDiscoverySetup.md).
## Modify Your Application Program
Modify your application program so that it uses Auto Discovery. The following sections show how to use the ElastiCache Cluster Client for Java, PHP, and .NET.
**Important**
When specifying the cluster's configuration endpoint, be sure that the endpoint has ".cfg" in its address as shown here. Do not use a CNAME or an endpoint without ".cfg" in it.
```
"mycluster.fnjyzo.cfg.use1.cache.amazonaws.com";
```
Failure to explicitly specify the cluster's configuration endpoint results in configuring to a specific node.
# Using the ElastiCache Cluster Client for Java
The program below demonstrates how to use the ElastiCache Cluster Client to connect to a cluster configuration endpoint and add a data item to the cache. Using Auto Discovery, the program connects to all of the nodes in the cluster without any further intervention.
```
package com.amazon.elasticache;
import java.io.IOException;
import java.net.InetSocketAddress;
// Import the &AWS;-provided library with Auto Discovery support
import net.spy.memcached.MemcachedClient;
public class AutoDiscoveryDemo {
public static void main(String[] args) throws IOException {
String configEndpoint = "mycluster.fnjyzo.cfg.use1.cache.amazonaws.com";
Integer clusterPort = 11211;
MemcachedClient client = new MemcachedClient(
new InetSocketAddress(configEndpoint,
clusterPort));
// The client will connect to the other cache nodes automatically.
// Store a data item for an hour.
// The client will decide which cache host will store this item.
client.set("theKey", 3600, "This is the data value");
}
}
```
# Using the ElastiCache Cluster Client for PHP
The program below demonstrates how to use the ElastiCache Cluster Client to connect to a cluster configuration endpoint and add a data item to the cache. Using Auto Discovery, the program will connect to all of the nodes in the cluster without any further intervention.
To use the ElastiCache Cluster Client for PHP, you will first need to install it on your Amazon EC2 instance. For more information, see [Installing the ElastiCache cluster client for PHP](Appendix.PHPAutoDiscoverySetup.md)
```
setOption(Memcached::OPT_CLIENT_MODE, Memcached::DYNAMIC_CLIENT_MODE);
$dynamic_client->addServer($server_endpoint, $server_port);
/**
* Store the data for 60 seconds in the cluster.
* The client will decide which cache host will store this item.
*/
$dynamic_client->set('key', 'value', 60);
/**
* Configuring the client with Static client mode disables the usage of Auto Discovery
* and the client operates as it did before the introduction of Auto Discovery.
* The user can then add a list of server endpoints.
*/
$static_client = new Memcached('persistent-id');
$static_client->setOption(Memcached::OPT_CLIENT_MODE, Memcached::STATIC_CLIENT_MODE);
$static_client->addServer($server_endpoint, $server_port);
/**
* Store the data without expiration.
* The client will decide which cache host will store this item.
*/
$static_client->set('key', 'value');
?>
```
For an example on how to use the ElastiCache Cluster Client with TLS enabled, see [Using in transit encryption with PHP and Memcached](in-transit-encryption.md#in-transit-encryption-connect-php-mc).
# Using the ElastiCache Cluster Client for .NET
**Note**
The ElastiCache .NET cluster client has been deprecated as of May, 2022.
.NET client for ElastiCache is open source at [https://github.com/awslabs/elasticache-cluster-config-net](https://github.com/awslabs/elasticache-cluster-config-net).
.NET applications typically get their configurations from their config file. The following is a sample application config file.
```
```
The C\$1 program below demonstrates how to use the ElastiCache Cluster Client to connect to a cluster configuration endpoint and add a data item to the cache. Using Auto Discovery, the program will connect to all of the nodes in the cluster without any further intervention.
```
// *****************
// Sample C# code to show how to integrate with the Amazon ElastiCcache Auto Discovery feature.
using System;
using Amazon.ElastiCacheCluster;
using Enyim.Caching;
using Enyim.Caching.Memcached;
public class DotNetAutoDiscoveryDemo {
public static void Main(String[] args) {
// instantiate a new client.
ElastiCacheClusterConfig config = new ElastiCacheClusterConfig();
MemcachedClient memClient = new MemcachedClient(config);
// Store the data for 3600 seconds (1hour) in the cluster.
// The client will decide which cache host will store this item.
memClient.Store(StoreMode.Set, 3600, "This is the data value.");
} // end Main
} // end class DotNetAutoDiscoverDemo
```
# Connecting to Memcached Cache Nodes Manually
If your client program does not use Auto Discovery, it can manually connect to each of the Memcached cache nodes. This is the default behavior for Memcached clients.
You can obtain a list of cache node hostnames and port numbers from the [AWS Management Console](https://aws.amazon.com/console/). You can also use the AWS CLI `aws elasticache describe-cache-clusters` command with the `--show-cache-node-info` parameter.
**Example**
The following Java code snippet shows how to connect to all of the nodes in a four-node cluster:
```
...
ArrayList cacheNodes = new ArrayList(
Arrays.asList(
"mycachecluster.fnjyzo.0001.use1.cache.amazonaws.com:11211",
"mycachecluster.fnjyzo.0002.use1.cache.amazonaws.com:11211",
"mycachecluster.fnjyzo.0003.use1.cache.amazonaws.com:11211",
"mycachecluster.fnjyzo.0004.use1.cache.amazonaws.com:11211"));
MemcachedClient cache = new MemcachedClient(AddrUtil.getAddresses(cacheNodes));
...
```
**Important**
If you scale up or scale down your cluster by adding or removing nodes, you will need to update the list of nodes in the client code.
# Adding Auto Discovery to your Memcached client library
The configuration information for Auto Discovery is stored redundantly in each Memcached cluster node. Client applications can query any cache node and obtain the configuration information for all of the nodes in the cluster.
The way in which an application does this depends upon the cache engine version:
+ If the cache engine version is **1.4.14 or higher**, use the `config` command.
+ If the cache engine version is **lower than 1.4.14**, use the `get AmazonElastiCache:cluster` command.
The outputs from these two commands are identical, and are described in the [Output Format](#AutoDiscovery.AddingToYourClientLibrary.OutputFormat) section below.
## Cache engine version 1.4.14 or higher
For cache engine version 1.4.14 or higher, use the `config` command. This command has been added to the Memcached ASCII and binary protocols by ElastiCache, and is implemented in the ElastiCache Cluster Client. If you want to use Auto Discovery with another client library, then that library will need to be extended to support the `config` command.
**Note**
The following documentation pertains to the ASCII protocol; however, the `config` command supports both ASCII and binary. If you want to add Auto Discovery support using the binary protocol, refer to the [source code for the ElastiCache Cluster Client](https://github.com/amazonwebservices/aws-elasticache-cluster-client-memcached-for-java/tree/master/src/main/java/net/spy/memcached/protocol/binary).
**Syntax**
`config [sub-command] [key]`
### Options
| Name | Description | Required |
| --- | --- | --- |
| sub-command | The sub-command used to interact with a cache node. For Auto Discovery, this sub-command is `get`. | Yes |
| key | The key under which the cluster configuration is stored. For Auto Discovery, this key is named `cluster`. | Yes |
To get the cluster configuration information, use the following command:
```
config get cluster
```
## Cache engine version 1.4.14 or lower
To get the cluster configuration information, use the following command:
```
get AmazonElastiCache:cluster
```
**Note**
Do not tamper with the "AmazonElastiCache:cluster" key, since this is where the cluster configuration information resides. If you do overwrite this key, then the client may be incorrectly configured for a brief period of time (no more than 15 seconds) before ElastiCache automatically and correctly updates the configuration information.
## Output Format
Whether you use `config get cluster` or `get AmazonElastiCache:cluster`, the reply consists of two lines:
+ The version number of the configuration information. Each time a node is added or removed from the cluster, the version number increases by one.
+ A list of cache nodes. Each node in the list is represented by a *hostname\$1ip-address\$1port* group, and each node is delimited by a space.
A carriage return and a linefeed character (CR \$1 LF) appears at the end of each line. The data line contains a linefeed character (LF) at the end, to which the CR \$1 LF is added. The config version line is terminated by LF without the CR.
A cluster containing three nodes would be represented as follows:
```
configversion\n
hostname|ip-address|port hostname|ip-address|port hostname|ip-address|port\n\r\n
```
Each node is shown with both the CNAME and the private IP address. The CNAME will always be present; if the private IP address is not available, it will not be shown; however, the pipe characters "`|`" will still be printed.
**Example**
Here is an example of the payload returned when you query the configuration information:
```
CONFIG cluster 0 136\r\n
12\n
myCluster.pc4ldq.0001.use1.cache.amazonaws.com|10.82.235.120|11211 myCluster.pc4ldq.0002.use1.cache.amazonaws.com|10.80.249.27|11211\n\r\n
END\r\n
```
**Note**
The second line indicates that the configuration information has been modified twelve times so far.
In the third line, the list of nodes is in alphabetical order by hostname. This ordering might be in a different sequence from what you are currently using in your client application.
# ElastiCache clients with auto discovery
Cluster client programs can automatically identify and connect to all cluster nodes that are running the Memcached engine.
This section discusses installing and configuring the ElastiCache PHP and .NET clients for use with auto discovery.
**Topics**
+ [
# Installing & compiling cluster clients
](Appendix.InstallingClients.md)
+ [
# Configuring ElastiCache clients
](ClientConfig.md)
# Installing & compiling cluster clients
This section covers installing, configuring, and compiling the PHP and .NET Amazon ElastiCache auto discovery cluster clients.
**Topics**
+ [
# Installing the ElastiCache cluster client for .NET
](Appendix.DotNETAutoDiscoverySetup.md)
+ [
# Installing the ElastiCache cluster client for PHP
](Appendix.PHPAutoDiscoverySetup.md)
+ [
# Compiling the source code for the ElastiCache cluster client for PHP
](Appendix.PHPAutoDiscoveryCompile.md)
# Installing the ElastiCache cluster client for .NET
You can find the ElastiCache .NET Cluster Client code as open source at [https://github.com/awslabs/elasticache-cluster-config-net](https://github.com/awslabs/elasticache-cluster-config-net).
This section describes how to install, update, and remove the .NET components for the ElastiCache Cluster Client on Amazon EC2 instances. For more information about auto discovery, see [Automatically identify nodes in your cluster (Memcached)](AutoDiscovery.md). For sample .NET code to use the client, see [Using the ElastiCache Cluster Client for .NET](AutoDiscovery.Using.ModifyApp.DotNET.md).
**Topics**
+ [
## Installing .NET
](#Appendix.DotNETAutoDiscoverySetup.DotNET)
+ [
## Download the ElastiCache .NET cluster client for ElastiCache
](#Appendix.DotNETAutoDiscoverySetup.Downloading)
+ [
## Install AWS assemblies with NuGet
](#Appendix.DotNETAutoDiscoverySetup.Installing)
## Installing .NET
You must have .NET 3.5 or later installed to use the AWS .NET SDK for ElastiCache. If you don't have .NET 3.5 or later, you can download and install the latest version from [http://www.microsoft.com/net](http://www.microsoft.com/net).
## Download the ElastiCache .NET cluster client for ElastiCache
**To download the ElastiCache .NET cluster client**
1. Sign in to the AWS Management Console and open the ElastiCache console at [ https://console.aws.amazon.com/elasticache/](https://console.aws.amazon.com/elasticache/).
1. On the navigation pane, click **ElastiCache Cluster Client**.
1. In the **Download ElastiCache Memcached Cluster Client** list, select **.NET**, and then click **Download.**
## Install AWS assemblies with NuGet
NuGet is a package management system for the .NET platform. NuGet is aware of assembly dependencies and installs all required files automatically. NuGet installed assemblies are stored with your solution, rather than in a central location such as `Program Files`, so you can install versions specific to an application without creating compatibility issues.
### Installing NuGet
NuGet can be installed from the Installation Gallery on MSDN; see [https://visualstudiogallery.msdn.microsoft.com/27077b70-9dad-4c64-adcf-c7cf6bc9970c](https://visualstudiogallery.msdn.microsoft.com/27077b70-9dad-4c64-adcf-c7cf6bc9970c). If you are using Visual Studio 2010 or later, NuGet is automatically installed.
You can use NuGet from either **Solution Explorer** or **Package Manager Console**.
### Using NuGet from Solution Explorer
**To use NuGet from Solution Explorer in Visual Studio 2010**
1. From the **Tools** menu, select **Library Package Manager**.
1. Click **Package Manager Console**.
**To use NuGet from Solution Explorer in Visual Studio 2012 or Visual Studio 2013**
1. From the **Tools** menu, select **NuGet Package Manager**.
1. Click **Package Manager Console**.
From the command line, you can install the assemblies using `Install-Package`, as shown following.
```
Install-Package Amazon.ElastiCacheCluster
```
To see a page for every package that is available through NuGet, such as the AWSSDK and AWS.Extensions assemblies, see the NuGet website at [http://www.nuget.org](http://www.nuget.org). The page for each package includes a sample command line for installing the package using the console and a list of the previous versions of the package that are available through NuGet.
For more information on **Package Manager Console** commands, see [http://nuget.codeplex.com/wikipage?title=Package%20Manager%20Console%20Command%20Reference%20%28v1.3%29](http://nuget.codeplex.com/wikipage?title=Package%20Manager%20Console%20Command%20Reference%20%28v1.3%29).
# Installing the ElastiCache cluster client for PHP
This section describes how to install, update, and remove the PHP components for the ElastiCache Cluster Client on Amazon EC2 instances. For more information about Auto Discovery, see [Automatically identify nodes in your cluster (Memcached)](AutoDiscovery.md). For sample PHP code to use the client. see [Using the ElastiCache Cluster Client for PHP](AutoDiscovery.Using.ModifyApp.PHP.md).
**Topics**
+ [
# Downloading the installation package
](Appendix.PHPAutoDiscoverySetup.Downloading.md)
+ [
## For users who already have *php-memcached* extension installed
](#Appendix.PHPAutoDiscoverySetup.InstallingExisting)
+ [
# Installation steps for new users
](Appendix.PHPAutoDiscoverySetup.Installing.md)
+ [
# Removing the PHP cluster client
](Appendix.PHPAutoDiscoverySetup.Removing.md)
# Downloading the installation package
To ensure that you use the correct version of the ElastiCache Cluster Client for PHP, you will need to know what version of PHP is installed on your Amazon EC2 instance. You will also need to know whether your Amazon EC2 instance is running a 64-bit or 32-bit version of Linux.
**To determine the PHP version installed on your Amazon EC2 instance**
+ At the command prompt, run the following command:
```
php -v
```
The PHP version will be shown in the output, as in this example:
```
PHP 5.4.10 (cli) (built: Jan 11 2013 14:48:57)
Copyright (c) 1997-2012 The PHP Group
Zend Engine v2.4.0, Copyright (c) 1998-2012 Zend Technologies
```
**Note**
If your PHP and Memcached versions are incompatible, you will get an error message something like the following:
```
PHP Warning: PHP Startup: memcached: Unable to initialize module
Module compiled with module API=20100525
PHP compiled with module API=20131226
These options need to match
in Unknown on line 0
```
If this happens, you need to compile the module from the source code. For more information, see [Compiling the source code for the ElastiCache cluster client for PHP](Appendix.PHPAutoDiscoveryCompile.md).
**To determine your Amazon EC2 AMI architecture (64-bit or 32-bit)**
1. Sign in to the AWS Management Console and open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the **Instances** list, click your Amazon EC2 instance.
1. In the **Description** tab, look for the **AMI:** field. A 64-bit instance should have `x86_64` as part of the description; for a 32-bit instance, look for `i386` or `i686` in this field.
You are now ready to download the ElastiCache Cluster Client.
**To download the ElastiCache cluster client for PHP**
1. Sign in to the AWS Management Console and open the ElastiCache console at [ https://console.aws.amazon.com/elasticache/](https://console.aws.amazon.com/elasticache/).
1. From the ElastiCache console, choose **ElastiCache Cluster Client**.
1. From the **Download ElastiCache Memcached Cluster Client** list, choose the ElastiCache Cluster Client that matches your PHP version and AMI architecture, then choose the **Download** button.
## For users who already have *php-memcached* extension installed
**To update the `php-memcached` installation**
1. Remove the previous installation of the Memcached extension for PHP as described by the topic [Removing the PHP cluster client](Appendix.PHPAutoDiscoverySetup.Removing.md).
1. Install the new ElastiCache `php-memcached` extension as described previously in [Installation steps for new users](Appendix.PHPAutoDiscoverySetup.Installing.md).
# Installation steps for new users
**Topics**
+ [
## Installing PHP 7.x for new users
](#Appendix.PHPAutoDiscoverySetup.Installing.PHP7x)
+ [
## Installing PHP 5.x for new users
](#Appendix.PHPAutoDiscoverySetup.Installing.PHP5x)
## Installing PHP 7.x for new users
**Topics**
+ [
### To install PHP 7 on a Ubuntu server 14.04 LTS AMI (64-bit and 32-bit)
](#Appendix.PHPAutoDiscoverySetup.Installing.PHP7x.Ubuntu)
+ [
### To install PHP 7 on an Amazon Linux 201609 AMI
](#Appendix.PHPAutoDiscoverySetup.Installing.PHP7x.AmznLinux)
+ [
### To install PHP 7 on an SUSE Linux AMI
](#Appendix.PHPAutoDiscoverySetup.Installing.PHP7x.SuseLinux)
### To install PHP 7 on a Ubuntu server 14.04 LTS AMI (64-bit and 32-bit)
1. Launch a new instance from the AMI.
1. Run the following commands:
```
sudo apt-get update
sudo apt-get install gcc g++
```
1. Install PHP 7.
```
sudo yum install php70
```
1. Download the Amazon ElastiCache Cluster Client.
```
wget https://elasticache-downloads.s3.amazonaws.com/ClusterClient/PHP-7.0/latest-64bit
```
1. Extract `latest-64bit`.
```
tar -zxvf latest-64bit
```
1. With root permissions, copy the extracted artifact file `amazon-elasticache-cluster-client.so` into `/usr/lib/php/20151012`.
```
sudo mv artifact/amazon-elasticache-cluster-client.so /usr/lib/php/20151012
```
1. Insert the line `extension=amazon-elasticache-cluster-client.so` into the file `/etc/php/7.0/cli/php.ini`.
```
echo "extension=amazon-elasticache-cluster-client.so" | sudo tee --append /etc/php/7.0/cli/php.ini
```
1. Start or restart your Apache server.
```
sudo /etc/init.d/httpd start
```
### To install PHP 7 on an Amazon Linux 201609 AMI
1. Launch a new instance from the AMI.
1. Run the following command:
```
sudo yum install gcc-c++
```
1. Install PHP 7.
```
sudo yum install php70
```
1. Download the Amazon ElastiCache Cluster Client.
```
wget https://elasticache-downloads.s3.amazonaws.com/ClusterClient/PHP-7.0/latest-64bit
```
1. Extract `latest-64bit`.
```
tar -zxvf latest-64bit
```
1. With root permission, copy the extracted artifact file `amazon-elasticache-cluster-client.so` into `/usr/lib64/php/7.0/modules/`.
```
sudo mv artifact/amazon-elasticache-cluster-client.so /usr/lib64/php/7.0/modules/
```
1. Create the `50-memcached.ini` file.
```
echo "extension=amazon-elasticache-cluster-client.so" | sudo tee --append /etc/php-7.0.d/50-memcached.ini
```
1. Start or restart your Apache server.
```
sudo /etc/init.d/httpd start
```
### To install PHP 7 on an SUSE Linux AMI
1. Launch a new instance from the AMI.
1. Run the following command:
```
sudo zypper install gcc
```
1. Install PHP 7.
```
sudo yum install php70
```
1. Download the Amazon ElastiCache Cluster Client.
```
wget https://elasticache-downloads.s3.amazonaws.com/ClusterClient/PHP-7.0/latest-64bit
```
1. Extract `latest-64bit`.
```
tar -zxvf latest-64bit
```
1. With root permission, copy the extracted artifact file `amazon-elasticache-cluster-client.so` into `/usr/lib64/php7/extensions/`.
```
sudo mv artifact/amazon-elasticache-cluster-client.so /usr/lib64/php7/extensions/
```
1. Insert the line `extension=amazon-elasticache-cluster-client.so` into the file `/etc/php7/cli/php.ini`.
```
echo "extension=amazon-elasticache-cluster-client.so" | sudo tee --append /etc/php7/cli/php.ini
```
1. Start or restart your Apache server.
```
sudo /etc/init.d/httpd start
```
## Installing PHP 5.x for new users
**Topics**
+ [
### To install PHP 5 on an Amazon Linux AMI 2014.03 (64-bit and 32-bit)
](#Appendix.PHPAutoDiscoverySetup.Installing.PHP5x.AmznLinux)
+ [
### To install PHP 5 on a Red Hat Enterprise Linux 7.0 AMI (64-bit and 32-bit)
](#Appendix.PHPAutoDiscoverySetup.Installing.PHP5x.RHEL)
+ [
### To install PHP 5 on a Ubuntu server 14.04 LTS AMI (64-bit and 32-bit)
](#Appendix.PHPAutoDiscoverySetup.Installing.PHP5x.Ubuntu)
+ [
### To install PHP 5 for SUSE Linux enterprise server 11 AMI (64-bit or 32-bit)
](#Appendix.PHPAutoDiscoverySetup.Installing.PHP5x.SuseLinux)
+ [
### Other Linux distributions
](#Appendix.PHPAutoDiscoverySetup.Installing.PHP5x.Other)
### To install PHP 5 on an Amazon Linux AMI 2014.03 (64-bit and 32-bit)
1. Launch an Amazon Linux instance (either 64-bit or 32-bit) and log into it.
1. Install PHP dependencies:
```
sudo yum install gcc-c++ php php-pear
```
1. Download the correct `php-memcached` package for your Amazon EC2 instance and PHP version. For more information, see [Downloading the installation package](Appendix.PHPAutoDiscoverySetup.Downloading.md).
1. Install `php-memcached`. The URI should be the download path for the installation package:
```
sudo pecl install
```
Here is a sample installation command for PHP 5.4, 64-bit Linux. In this sample, replace *X.Y.Z* with the actual version number:
```
sudo pecl install /home/AmazonElastiCacheClusterClient-X.Y.Z-PHP54-64bit.tgz
```
**Note**
Be sure to use the latest version of the install artifact.
1. With root/sudo permission, add a new file named `memcached.ini` in the `/etc/php.d` directory, and insert "extension=amazon-elasticache-cluster-client.so" in the file:
```
echo "extension=amazon-elasticache-cluster-client.so" | sudo tee --append /etc/php.d/memcached.ini
```
1. Start or restart your Apache server.
```
sudo /etc/init.d/httpd start
```
### To install PHP 5 on a Red Hat Enterprise Linux 7.0 AMI (64-bit and 32-bit)
1. Launch a Red Hat Enterprise Linux instance (either 64-bit or 32-bit) and log into it.
1. Install PHP dependencies:
```
sudo yum install gcc-c++ php php-pear
```
1. Download the correct `php-memcached` package for your Amazon EC2 instance and PHP version. For more information, see [Downloading the installation package](Appendix.PHPAutoDiscoverySetup.Downloading.md).
1. Install `php-memcached`. The URI should be the download path for the installation package:
```
sudo pecl install
```
1. With root/sudo permission, add a new file named `memcached.ini` in the `/etc/php.d` directory, and insert `extension=amazon-elasticache-cluster-client.so` in the file.
```
echo "extension=amazon-elasticache-cluster-client.so" | sudo tee --append /etc/php.d/memcached.ini
```
1. Start or restart your Apache server.
```
sudo /etc/init.d/httpd start
```
### To install PHP 5 on a Ubuntu server 14.04 LTS AMI (64-bit and 32-bit)
1. Launch an Ubuntu Linux instance (either 64-bit or 32-bit) and log into it.
1. Install PHP dependencies:
```
sudo apt-get update
sudo apt-get install gcc g++ php5 php-pear
```
1. Download the correct `php-memcached` package for your Amazon EC2 instance and PHP version. For more information, see [Downloading the installation package](Appendix.PHPAutoDiscoverySetup.Downloading.md).
1. Install `php-memcached`. The URI should be the download path for the installation package.
```
sudo pecl install
```
**Note**
This installation step installs the build artifact `amazon-elasticache-cluster-client.so` into the `/usr/lib/php5/20121212*` directory. Verify the absolute path of the build artifact, because you need it in the next step.
If the previous command doesn't work, you need to manually extract the PHP client artifact `amazon-elasticache-cluster-client.so` from the downloaded `*.tgz` file, and copy it to the `/usr/lib/php5/20121212*` directory.
```
tar -xvf
cp amazon-elasticache-cluster-client.so /usr/lib/php5/20121212/
```
1. With root/sudo permission, add a new file named `memcached.ini` in the `/etc/php5/cli/conf.d` directory, and insert "extension=" in the file.
```
echo "extension=" | sudo tee --append /etc/php5/cli/conf.d/memcached.ini
```
1. Start or restart your Apache server.
```
sudo /etc/init.d/httpd start
```
### To install PHP 5 for SUSE Linux enterprise server 11 AMI (64-bit or 32-bit)
1. Launch a SUSE Linux instance (either 64-bit or 32-bit) and log into it.
1. Install PHP dependencies:
```
sudo zypper install gcc php53-devel
```
1. Download the correct `php-memcached` package for your Amazon EC2 instance and PHP version. For more information, see [Downloading the installation package](Appendix.PHPAutoDiscoverySetup.Downloading.md).
1. Install `php-memcached`. The URI should be the download path for the installation package.
```
sudo pecl install
```
1. With root/sudo permission, add a new file named `memcached.ini` in the `/etc/php5/conf.d` directory, and insert **extension=`amazon-elasticache-cluster-client.so`** in the file.
```
echo "extension=amazon-elasticache-cluster-client.so" | sudo tee --append /etc/php5/conf.d/memcached.ini
```
1. Start or restart your Apache server.
```
sudo /etc/init.d/httpd start
```
**Note**
If Step 5 doesn't work for any of the previous platforms, verify the install path for `amazon-elasticache-cluster-client.so`. Also, specify the full path of the binary in the extension. In addition, verify that the PHP in use is a supported version. We support versions 5.3 through 5.5.
### Other Linux distributions
On some systems, notably CentOS7 and Red Hat Enterprise Linux (RHEL) 7.1, `libsasl2.so.3` has replaced `libsasl2.so.2`. On those systems, when you load the ElastiCache cluster client, it attempts and fails to find and load `libsasl2.so.2`. To resolve this issue, create a symbolic link to `libsasl2.so.3` so that when the client attempts to load libsasl2.so.2, it is redirected to `libsasl2.so.3`. The following code creates this symbolic link.
```
cd /usr/lib64
sudo ln libsasl2.so.3 libsasl2.so.2
```
# Removing the PHP cluster client
**Topics**
+ [
## Removing an earlier version of PHP 7
](#Appendix.PHPAutoDiscoverySetup.Removing.PHP7x)
+ [
## Removing an earlier version of PHP 5
](#Appendix.PHPAutoDiscoverySetup.Removing.PHP5x)
## Removing an earlier version of PHP 7
**To remove an earlier version of PHP 7**
1. Remove the `amazon-elasticache-cluster-client.so` file from the appropriate PHP lib directory as previously indicated in the installation instructions. See the section for your installation at [For users who already have *php-memcached* extension installed](Appendix.PHPAutoDiscoverySetup.md#Appendix.PHPAutoDiscoverySetup.InstallingExisting).
1. Remove the line `extension=amazon-elasticache-cluster-client.so` from the `php.ini` file.
1. Start or restart your Apache server.
```
sudo /etc/init.d/httpd start
```
## Removing an earlier version of PHP 5
**To remove an earlier version of PHP 5**
1. Remove the `php-memcached` extension:
```
sudo pecl uninstall __uri/AmazonElastiCacheClusterClient
```
1. Remove the `memcached.ini` file added in the appropriate directory as indicated in the previous installation steps.
# Compiling the source code for the ElastiCache cluster client for PHP
This section covers how to obtain and compile the source code for the ElastiCache Cluster Client for PHP.
There are two packages you need to pull from GitHub and compile; [aws-elasticache-cluster-client-libmemcached](https://github.com/awslabs/aws-elasticache-cluster-client-libmemcached) and [aws-elasticache-cluster-client-memcached-for-php](https://github.com/awslabs/aws-elasticache-cluster-client-memcached-for-php).
**Topics**
+ [
## Compiling the libmemcached library
](#Appendix.PHPAutoDiscoveryCompile.Libmemcached)
+ [
## Compiling the ElastiCache Memcached auto discovery client for PHP
](#Appendix.PHPAutoDiscoveryCompile.Client)
## Compiling the libmemcached library
**To compile the aws-elasticache-cluster-client-libmemcached library**
1. Launch an Amazon EC2 instance.
1. Install the library dependencies.
+ On Amazon Linux 201509 AMI
```
sudo yum install gcc gcc-c++ autoconf libevent-devel
```
+ On Ubuntu 14.04 AMI
```
sudo apt-get update
sudo apt-get install libevent-dev gcc g++ make autoconf libsasl2-dev
```
1. Pull the repository and compile the code.
```
Download and install [ https://github.com/awslabs/aws-elasticache-cluster-client-libmemcached/archive/v1.0.18.tar.gz]( https://github.com/awslabs/aws-elasticache-cluster-client-libmemcached/archive/v1.0.18.tar.gz)
```
## Compiling the ElastiCache Memcached auto discovery client for PHP
The following sections describe how to compile the ElastiCache Memcached Auto Discovery Client
**Topics**
+ [
### Compiling the ElastiCache Memcached client for PHP 7
](#Appendix.PHPAudiscoveryCompile.Client.PHP7)
+ [
### Compiling the ElastiCache Memcached client for PHP 5
](#Appendix.PHPAudiscoveryCompile.PHP5)
### Compiling the ElastiCache Memcached client for PHP 7
Run the following set of commands under the code directory.
```
git clone https://github.com/awslabs/aws-elasticache-cluster-client-memcached-for-php.git
cd aws-elasticache-cluster-client-memcached-for-php
git checkout php7
sudo yum install php70-devel
phpize
./configure --with-libmemcached-dir= --disable-memcached-sasl
make
make install
```
**Note**
You can statically link the libmemcached library into the PHP binary so it can be ported across various Linux platforms. To do that, run the following command before `make`:
```
sed -i "s#-lmemcached#/lib/libmemcached.a -lcrypt -lpthread -lm -lstdc++ -lsasl2#" Makefile
```
### Compiling the ElastiCache Memcached client for PHP 5
Compile the `aws-elasticache-cluster-client-memcached-for-php` by running the following commands under the `aws-elasticache-cluster-client-memcached-for-php/` folder.
```
git clone https://github.com/awslabs/aws-elasticache-cluster-client-memcached-for-php.git
cd aws-elasticache-cluster-client-memcached-for-php
sudo yum install zlib-devel
phpize
./configure --with-libmemcached-dir=
make
make install
```
# Configuring ElastiCache clients
An ElastiCache cluster is protocol-compliant with Valkey, Memcached, and Redis OSS. The code, applications, and most popular tools that you use today with your existing environment will work seamlessly with the service.
This section discusses specific considerations for connecting to cache nodes in ElastiCache.
**Topics**
+ [
# Restricted commands
](ClientConfig.RestrictedCommands.md)
+ [
# Finding node endpoints and port numbers
](ClientConfig.FindingEndpointsAndPorts.md)
+ [
# Connecting for using auto discovery
](ClientConfig.AutoDiscovery.md)
+ [
# Connecting to nodes in a Valkey or Redis OSS cluster
](ClientConfig.ReplicationGroup.md)
+ [
# DNS names and underlying IP
](ClientConfig.DNS.md)
# Restricted commands
To deliver a managed service experience, ElastiCache restricts access to certain cache engine-specific commands that require advanced privileges. For clusters running Redis OSS, the following commands are unavailable:
+ `bgrewriteaof`
+ `bgsave`
+ `config`
+ `debug`
+ `migrate`
+ `replicaof`
+ `save`
+ `slaveof`
+ `shutdown`
+ `sync`
# Finding node endpoints and port numbers
To connect to a cache node, your application needs to know the endpoint and port number for that node.
## Finding node endpoints and port numbers (Console)
**To determine node endpoints and port numbers**
1. Sign in to the [Amazon ElastiCache management console](https://aws.amazon.com/elasticache) and choose the engine running on your cluster.
A list of all clusters running the chosen engine appears.
1. Continue below for the engine and configuration you're running.
1. Choose the name of the cluster of interest.
1. Locate the **Port** and **Endpoint** columns for the node you're interested in.
## Finding cache node endpoints and port numbers (AWS CLI)
To determine cache node endpoints and port numbers, use the command `describe-cache-clusters` with the `--show-cache-node-info` parameter.
```
aws elasticache describe-cache-clusters --show-cache-node-info
```
The fully qualified DNS names and port numbers are in the Endpoint section of the output.
## Finding cache node endpoints and port numbers (ElastiCache API)
To determine cache node endpoints and port numbers, use the action `DescribeCacheClusters` with the `ShowCacheNodeInfo=true` parameter.
**Example**
```
1. https://elasticache.us-west-2.amazonaws.com /
2. ?Action=DescribeCacheClusters
3. &ShowCacheNodeInfo=true
4. &SignatureVersion=4
5. &SignatureMethod=HmacSHA256
6. &Timestamp=20140421T220302Z
7. &Version=2014-09-30
8. &X-Amz-Algorithm=&AWS;4-HMAC-SHA256
9. &X-Amz-Credential=
10. &X-Amz-Date=20140421T220302Z
11. &X-Amz-Expires=20140421T220302Z
12. &X-Amz-Signature=
13. &X-Amz-SignedHeaders=Host
```
# Connecting for using auto discovery
If your applications use Auto Discovery, you only need to know the configuration endpoint for the cluster, rather than the individual endpoints for each cache node. For more information, see [Automatically identify nodes in your cluster (Memcached)](AutoDiscovery.md).
**Note**
At this time, Auto Discovery is only available for clusters running Memcached.
# Connecting to nodes in a Valkey or Redis OSS cluster
**Note**
At this time, clusters (API/CLI: replication groups) that support replication and read replicas are only supported for clusters running Valkey or Redis OSS.
For clusters, ElastiCache provides console, CLI, and API interfaces to obtain connection information for individual nodes.
For read-only activity, applications can connect to any node in the cluster. However, for write activity, we recommend that your applications connect to the primary endpoint (Valkey or Redis OSS (cluster mode disabled)) or configuration endpoint (Valkey or Redis OSS (cluster mode enabled)) for the cluster instead of connecting directly to a node. This will ensure that your applications can always find the correct node, even if you decide to reconfigure your cluster by promoting a read replica to the primary role.
## Connecting to clusters in a replication group (Console)
**To determine endpoints and port numbers**
+ See the topic, [Finding a Valkey or Redis OSS (Cluster Mode Disabled) Cluster's Endpoints (Console)](Endpoints.md#Endpoints.Find.Redis).
## Connecting to clusters in a replication group (AWS CLI)
**To determine cache node endpoints and port numbers**
Use the command `describe-replication-groups` with the name of your replication group:
```
aws elasticache describe-replication-groups redis2x2
```
This command should produce output similar to the following:
```
{
"ReplicationGroups": [
{
"Status": "available",
"Description": "2 shards, 2 nodes (1 + 1 replica)",
"NodeGroups": [
{
"Status": "available",
"Slots": "0-8191",
"NodeGroupId": "0001",
"NodeGroupMembers": [
{
"PreferredAvailabilityZone": "us-west-2c",
"CacheNodeId": "0001",
"CacheClusterId": "redis2x2-0001-001"
},
{
"PreferredAvailabilityZone": "us-west-2a",
"CacheNodeId": "0001",
"CacheClusterId": "redis2x2-0001-002"
}
]
},
{
"Status": "available",
"Slots": "8192-16383",
"NodeGroupId": "0002",
"NodeGroupMembers": [
{
"PreferredAvailabilityZone": "us-west-2b",
"CacheNodeId": "0001",
"CacheClusterId": "redis2x2-0002-001"
},
{
"PreferredAvailabilityZone": "us-west-2a",
"CacheNodeId": "0001",
"CacheClusterId": "redis2x2-0002-002"
}
]
}
],
"ConfigurationEndpoint": {
"Port": 6379,
"Address": "redis2x2.9dcv5r.clustercfg.usw2.cache.amazonaws.com"
},
"ClusterEnabled": true,
"ReplicationGroupId": "redis2x2",
"SnapshotRetentionLimit": 1,
"AutomaticFailover": "enabled",
"SnapshotWindow": "13:00-14:00",
"MemberClusters": [
"redis2x2-0001-001",
"redis2x2-0001-002",
"redis2x2-0002-001",
"redis2x2-0002-002"
],
"CacheNodeType": "cache.m3.medium",
"PendingModifiedValues": {}
}
]
}
```
## Connecting to clusters in a replication group (ElastiCache API)
**To determine cache node endpoints and port numbers**
Call `DescribeReplicationGroups` with the following parameter:
`ReplicationGroupId` = the name of your replication group.
**Example**
```
1. https://elasticache.us-west-2.amazonaws.com /
2. ?Action=DescribeCacheClusters
3. &ReplicationGroupId=repgroup01
4. &Version=2014-09-30
5. &SignatureVersion=4
6. &SignatureMethod=HmacSHA256
7. &Timestamp=20140421T220302Z
8. &X-Amz-Algorithm=&AWS;4-HMAC-SHA256
9. &X-Amz-Date=20140421T220302Z
10. &X-Amz-SignedHeaders=Host
11. &X-Amz-Expires=20140421T220302Z
12. &X-Amz-Credential=
13. &X-Amz-Signature=
```
# DNS names and underlying IP
Clients maintain a server list containing the addresses and ports of the servers holding the cache data. When using ElastiCache, the DescribeCacheClusters API (or the describe-cache-clusters command line utility) returns a fully qualified DNS entry and port number that can be used for the server list.
**Important**
It is important that client applications are configured to frequently resolve DNS names of cache nodes when they attempt to connect to a cache node endpoint.
ElastiCache ensures that the DNS name of cache nodes remain the same when cache nodes are recovered in case of failure.
Most client libraries support persistent cache node connections by default. We recommend using persistent cache node connections when using ElastiCache. Client-side DNS caching can occur in multiple places, including client libraries, the language runtime, or the client operating system. You should review your application configuration at each layer to ensure that you are frequently resolving IP addresses for your cache nodes.
# Data tiering in ElastiCache
ElastiCache for Valkey or Redis OSS clusters that comprise a replication group and use a node type from the r6gd family have their data tiered between memory and local SSD (solid state drives) storage. Data tiering provides a new price-performance option for Valkey or Redis OSS workloads by utilizing lower-cost solid state drives (SSDs) in each cluster node in addition to storing data in memory. It is ideal for workloads that access up to 20 percent of their overall dataset regularly, and for applications that can tolerate additional latency when accessing data on SSD.
On ElastiCache clusters with data tiering, ElastiCache monitors the last access time of every item it stores. When available memory (DRAM) is fully consumed, ElastiCache uses a least-recently used (LRU) algorithm to automatically move infrequently accessed items from memory to SSD. When data on SSD is subsequently accessed, ElastiCache automatically and asynchronously moves it back to memory before processing the request. If you have a workload that accesses only a subset of its data regularly, data tiering is an optimal way to scale your capacity cost-effectively.
Note that when using data tiering, keys themselves always remain in memory, while the LRU governs the placement of values on memory vs. disk. In general, we recommend that your key sizes are smaller than your value sizes when using data tiering.
Data tiering is designed to have minimal performance impact to application workloads. For example, assuming 500-byte String values, you can expect an additional 300 microseconds of latency on average for requests to data stored on SSD compared to requests to data in memory.
With the largest data tiering node size (cache.r6gd.16xlarge), you can store up to 1 petabyte in a single 500-node cluster (500 TB when using 1 read replica). Data tiering is compatible with all Valkey or Redis OSS commands and data structures supported in ElastiCache. You don't need any client-side changes to use this feature.
**Topics**
+ [
## Best practices
](#data-tiering-best-practices)
+ [
## Limitations
](#data-tiering-prerequisites)
+ [
## Pricing
](#data-tiering-pricing)
+ [
## Monitoring
](#data-tiering-monitoring)
+ [
## Using data tiering
](#data-tiering-enabling)
+ [
## Restoring data from backup into clusters with data tiering enabled
](#data-tiering-enabling-snapshots)
## Best practices
We recommend the following best practices:
+ Data tiering is ideal for workloads that access up to 20 percent of their overall dataset regularly, and for applications that can tolerate additional latency when accessing data on SSD.
+ When using SSD capacity available on data-tiered nodes, we recommend that value size be larger than the key size. When items are moved between DRAM and SSD, keys will always remain in memory and only the values are moved to the SSD tier.
## Limitations
Data tiering has the following limitations:
+ You can only use data tiering on clusters that are part of a replication group.
+ The node type you use must be from the r6gd family.
+ You must use an engine that is Valkey 7.2 or later, or a Redis OSS 6.2 or later.
+ You cannot restore a backup of an r6gd cluster into another cluster unless it also uses r6gd.
+ You cannot export a backup to Amazon S3 for data-tiering clusters.
+ Online migration is not supported for clusters running on the r6gd node type.
+ Scaling between clusters with data tiering enabled and data tiering disabled is not supported. To migrate data from an ElastiCache cluster with data tiering disabled to a cluster with data tiering enabled, you can restore a backup to a new cluster with data tiering enabled. For more information, see [Scaling ElastiCache](Scaling.md).
+ Auto scaling is supported on clusters using data tiering for Valkey version 7.2 and later, and Redis OSS version 7.0.7 and later. For more information, see [Auto Scaling Valkey and Redis OSS clusters](AutoScaling.md)
+ Data tiering only supports `volatile-lru`, `allkeys-lru`, `volatile-lfu`, `allkeys-lfu` and `noeviction` maxmemory policies.
+ Forkless save is supported for Valkey version 7.2 and later, and Redis OSS version 7.0.7 and later. For more information, see [How synchronization and backup are implemented](Replication.Redis.Versions.md).
+ Items larger than 128 MiB are not moved to SSD.
+ Starting from Valley 8.1 and later, an item whose key \$1 value size is less than 40 bytes will not be moved to the SSD.
## Pricing
R6gd nodes have 4.8x more total capacity (memory \$1 SSD) and can help you achieve over 60 percent savings when running at maximum utilization compared to R6g nodes (memory only). For more information, see [ElastiCache pricing](https://aws.amazon.com/elasticache/pricing/).
## Monitoring
ElastiCache offers metrics designed specifically to monitor the performance clusters that use data tiering. To monitor the ratio of items in DRAM compared to SSD, you can use the `CurrItems` metric at [Metrics for Valkey and Redis OSS](CacheMetrics.Redis.md). You can calculate the percentage as: *(CurrItems with Dimension: Tier = Memory \$1 100) / (CurrItems with no dimension filter)*.
If the configured eviction policy allows, then ElastiCache will start evicting items when the percentage of items in memory decreases below 5 percent. On nodes configured with noeviction policy, write operations will receive an out of memory error.
It is still recommended that you consider scaling out for Cluster Mode Enabled clusters or scaling up for Cluster Mode disabled clusters when the percentage of items in memory decreases below 5 percent. For more information on scaling see [Scaling Valkey or Redis OSS (Cluster Mode Enabled) clusters](scaling-redis-cluster-mode-enabled.md). For more information on metrics for Valkey or Redis OSS clusters that use data tiering see [Metrics for Valkey and Redis OSS](CacheMetrics.Redis.md).
## Using data tiering
### Using data tiering using the AWS Management Console
When creating a cluster as part of a replication group, you use data tiering by selecting a node type from the r6gd family, such as *cache.r6gd.xlarge*. Selecting that node type automatically enables data tiering.
For more information on creating a cluster, see [Creating a cluster for Valkey or Redis OSS](Clusters.Create.md).
### Enabling data tiering using the AWS CLI
When creating a replication group using the AWS CLI, you use data tiering by selecting a node type from the r6gd family, such as *cache.r6gd.xlarge* and setting the `--data-tiering-enabled` parameter.
You cannot opt out of data tiering when selecting a node type from the r6gd family. If you set the `--no-data-tiering-enabled` parameter, the operation will fail.
For Linux, macOS, or Unix:
```
aws elasticache create-replication-group \
--replication-group-id redis-dt-cluster \
--replication-group-description "Redis OSS cluster with data tiering" \
--num-node-groups 1 \
--replicas-per-node-group 1 \
--cache-node-type cache.r6gd.xlarge \
--engine redis \
--cache-subnet-group-name default \
--automatic-failover-enabled \
--data-tiering-enabled
```
For Windows:
```
aws elasticache create-replication-group ^
--replication-group-id redis-dt-cluster ^
--replication-group-description "Redis OSS cluster with data tiering" ^
--num-node-groups 1 ^
--replicas-per-node-group 1 ^
--cache-node-type cache.r6gd.xlarge ^
--engine redis ^
--cache-subnet-group-name default ^
--automatic-failover-enabled ^
--data-tiering-enabled
```
After running this operation, you will see a response similar to the following:
```
{
"ReplicationGroup": {
"ReplicationGroupId": "redis-dt-cluster",
"Description": "Redis OSS cluster with data tiering",
"Status": "creating",
"PendingModifiedValues": {},
"MemberClusters": [
"redis-dt-cluster"
],
"AutomaticFailover": "enabled",
"DataTiering": "enabled",
"SnapshotRetentionLimit": 0,
"SnapshotWindow": "06:00-07:00",
"ClusterEnabled": false,
"CacheNodeType": "cache.r6gd.xlarge",
"TransitEncryptionEnabled": false,
"AtRestEncryptionEnabled": false
}
}
```
## Restoring data from backup into clusters with data tiering enabled
You can restore a backup to a new cluster with data tiering enabled using the (Console), (AWS CLI) or (ElastiCache API). When you create a cluster using node types in the r6gd family, data tiering is enabled.
### Restoring data from backup into clusters with data tiering enabled (console)
**To restore a backup to a new cluster with data tiering enabled (console)**
1. Sign in to the AWS Management Console and open the ElastiCache console at [ https://console.aws.amazon.com/elasticache/](https://console.aws.amazon.com/elasticache/).
1. From the navigation pane, choose **Backups**.
1. In the list of backups, choose the box to the left of the backup name you want to restore from.
1. Choose **Restore**.
1. Complete the **Restore Cluster** dialog box. Be sure to complete all the **Required** fields and any of the others you want to change from the defaults.
1. **Cluster ID** – Required. The name of the new cluster.
1. **Cluster mode enabled (scale out)** – Choose this for a Valkey or Redis OSS (cluster mode enabled) cluster.
1. **Node Type** – Specify **cache.r6gd.xlarge** or any other node type from the r6gd family.
1. **Number of Shards** – Choose the number of shards you want in the new cluster (API/CLI: node groups).
1. **Replicas per Shard** – Choose the number of read replica nodes you want in each shard.
1. **Slots and keyspaces** – Choose how you want keys distributed among the shards. If you choose to specify the key distributions complete the table specifying the key ranges for each shard.
1. **Availability zone(s)** – Specify how you want the cluster's Availability Zones selected.
1. **Port** – Change this only if you want the new cluster to use a different port.
1. **Choose a VPC** – Choose the VPC in which to create this cluster.
1. **Parameter Group** – Choose a parameter group that reserves sufficient memory for Valkey or Redis OSS overhead for the node type you selected.
1. When the settings are as you want them, choose **Create**.
For more information on creating a cluster, see [Creating a cluster for Valkey or Redis OSS](Clusters.Create.md).
### Restoring data from backup into clusters with data tiering enabled (AWS CLI)
When creating a replication group using the AWS CLI, data tiering is by default used by selecting a node type from the r6gd family, such as *cache.r6gd.xlarge* and setting the `--data-tiering-enabled` parameter.
You cannot opt out of data tiering when selecting a node type from the r6gd family. If you set the `--no-data-tiering-enabled` parameter, the operation will fail.
For Linux, macOS, or Unix:
```
aws elasticache create-replication-group \
--replication-group-id redis-dt-cluster \
--replication-group-description "Redis OSS cluster with data tiering" \
--num-node-groups 1 \
--replicas-per-node-group 1 \
--cache-node-type cache.r6gd.xlarge \
--engine redis \
--cache-subnet-group-name default \
--automatic-failover-enabled \
--data-tiering-enabled \
--snapshot-name my-snapshot
```
For Linux, macOS, or Unix:
```
aws elasticache create-replication-group ^
--replication-group-id redis-dt-cluster ^
--replication-group-description "Redis OSS cluster with data tiering" ^
--num-node-groups 1 ^
--replicas-per-node-group 1 ^
--cache-node-type cache.r6gd.xlarge ^
--engine redis ^
--cache-subnet-group-name default ^
--automatic-failover-enabled ^
--data-tiering-enabled ^
--snapshot-name my-snapshot
```
After running this operation, you will see a response similar to the following:
```
{
"ReplicationGroup": {
"ReplicationGroupId": "redis-dt-cluster",
"Description": "Redis OSS cluster with data tiering",
"Status": "creating",
"PendingModifiedValues": {},
"MemberClusters": [
"redis-dt-cluster"
],
"AutomaticFailover": "enabled",
"DataTiering": "enabled",
"SnapshotRetentionLimit": 0,
"SnapshotWindow": "06:00-07:00",
"ClusterEnabled": false,
"CacheNodeType": "cache.r6gd.xlarge",
"TransitEncryptionEnabled": false,
"AtRestEncryptionEnabled": false
}
}
```
# Preparing a cluster in ElastiCache
Following, you can find instructions on creating a cluster using the ElastiCache console, the AWS CLI, or the ElastiCache API.
You can also create an ElastiCache cluster using [AWS CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html). For more information, see [AWS::ElastiCache::CacheCluster](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-elasticache-cache-cluster.html) in the *AWS Cloud Formation User Guide*, which includes guidance on how to implement that approach.
Whenever you create a cluster or replication group, it is a good idea to do some preparatory work so you won't need to upgrade or make changes right away.
**Topics**
+ [
# Determining your ElastiCache cluster requirements
](cluster-create-determine-requirements.md)
+ [
# Choosing your node size
](CacheNodes.SelectSize.md)
# Determining your ElastiCache cluster requirements
**Preparation**
Knowing the answers to the following questions helps make creating your ElastiCache cluster go smoother:
+ Which node instance type do you need?
For guidance on choosing an instance node type, see [Choosing your node size](CacheNodes.SelectSize.md).
+ Will you launch your cluster in a virtual private cloud (VPC) based on Amazon VPC?
**Important**
If you're going to launch your cluster in a VPC, make sure to create a subnet group in the same VPC before you start creating a cluster. For more information, see [Subnets and subnet groups](SubnetGroups.md).
ElastiCache is designed to be accessed from within AWS using Amazon EC2. However, if you launch in a VPC based on Amazon VPC and your cluster is in an VPC, you can provide access from outside AWS. For more information, see [Accessing ElastiCache resources from outside AWS](accessing-elasticache.md#access-from-outside-aws).
+ Do you need to customize any parameter values?
If you do, create a custom parameter group. For more information, see [Creating an ElastiCache parameter group](ParameterGroups.Creating.md).
If you're running Valkey or Redis OSS, consider setting `reserved-memory` or `reserved-memory-percent`. For more information, see [Managing reserved memory for Valkey and Redis OSS](redis-memory-management.md).
+ Do you need to create your own *VPC security group*?
For more information, see [Security in Your VPC](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Security.html).
+ How do you intend to implement fault tolerance?
For more information, see [Mitigating Failures](disaster-recovery-resiliency.md#FaultTolerance).
**Topics**
+ [
## ElastiCache memory and processor requirements
](#cluster-create-determine-requirements-memory)
+ [
## Memcached cluster configuration
](#memcached-cluster-configuration)
+ [
## Valkey and Redis OSS cluster configuration
](#redis-cluster-configuration)
+ [
## ElastiCache scaling requirements
](#cluster-create-determine-requirements-scaling)
+ [
## ElastiCache access requirements
](#cluster-create-determine-requirements-access)
+ [
## Region, Availability Zone and Local Zone requirements for ElastiCache
](#cluster-create-determine-requirements-region)
## ElastiCache memory and processor requirements
The basic building block of Amazon ElastiCache is the node. Nodes are configured singularly or in groupings to form clusters. When determining the node type to use for your cluster, take the cluster’s node configuration and the amount of data you have to store into consideration.
The Memcached engine is multi-threaded, so a node’s number of cores impacts the compute power available to the cluster.
## Memcached cluster configuration
ElastiCache for Memcached clusters are comprised of from 1 to 60 nodes. The data in a Memcached cluster is partitioned across the nodes in the cluster. Your application connects with a Memcached cluster using a network address called an Endpoint. Each node in a Memcached cluster has its own endpoint which your application uses to read from or write to the specific node. In addition to the node endpoints, the Memcached cluster itself has an endpoint called the *configuration endpoint*. Your application can use this endpoint to read from or write to the cluster, leaving the determination of which node to read from or write to up to auto discovery.
![\[Image showing how a Memcached cluster is partitioned across the nodes in the cluster.\]](http://docs.aws.amazon.com/AmazonElastiCache/latest/dg/images/ElastiCache-Cluster-Memcached.png)
For more information, see [Managing clusters in ElastiCache](Clusters.md).
## Valkey and Redis OSS cluster configuration
ElastiCache for Valkey and Redis OSS clusters are comprised of from 0 to 500 shards (also called node groups). The data in a Valkey or Redis OSS cluster is partitioned across the shards in the cluster. Your application connects with a Valkey or Redis OSS cluster using a network address called an Endpoint. The nodes in a Valkey or Redis OSS shard fulfill one of two roles: one read/write primary and all other nodes read-only secondaries (also called read replicas). In addition to the node endpoints, the Valkey or Redis OSS cluster itself has an endpoint called the *configuration endpoint*. Your application can use this endpoint to read from or write to the cluster, leaving the determination of which node to read from or write to up to ElastiCache for Redis OSS.
![\[Image comparing a Valkey or Redis OSS cluster in disabled mode vs. enabled mode.\]](http://docs.aws.amazon.com/AmazonElastiCache/latest/dg/images/ElastiCacheClusters-Redis-ClustersRGs.png)
For more information, see [Managing clusters in ElastiCache](Clusters.md).
## ElastiCache scaling requirements
All clusters can be scaled up by creating a new cluster with the new, larger node type. When you scale up a Memcached cluster, the new cluster starts out empty. When you scale up a Valkey or Redis OSS cluster, you can seed it from a backup and avoid having the new cluster start out empty.
Amazon ElastiCache for Memcached clusters can be scaled out or in. To scale a Memcached cluster out or in you merely add or remove nodes from the cluster. If you have enabled Automatic Discovery and your application is connecting to the cluster’s configuration endpoint, you do not need to make any changes in your application when you add or remove nodes.
For more information, see [Scaling ElastiCache](Scaling.md) in this guide.
## ElastiCache access requirements
By design, Amazon ElastiCache clusters are accessed from Amazon EC2 instances. Network access to an ElastiCache cluster is limited to the account that created the cluster. Therefore, before you can access a cluster from an Amazon EC2 instance, you must authorize the Amazon EC2 instance to access the cluster. The steps to do this vary, depending upon whether you launched into EC2-VPC or EC2-Classic.
If you launched your cluster into EC2-VPC you need to grant network ingress to the cluster. If you launched your cluster into EC2-Classic you need to grant the Amazon Elastic Compute Cloud security group associated with the instance access to your ElastiCache security group. For detailed instructions, see [Step 3. Authorize access to the cluster](SubnetGroups.designing-cluster-pre.valkey.md#GettingStarted.AuthorizeAccess.valkey) in this guide.
## Region, Availability Zone and Local Zone requirements for ElastiCache
Amazon ElastiCache supports all AWS regions. By locating your ElastiCache clusters in an AWS Region close to your application you can reduce latency. If your cluster has multiple nodes, locating your nodes in different Availability Zones or in Local Zones can reduce the impact of failures on your cluster.
For more information, see the following:
+ [Choosing regions and availability zones for ElastiCache](RegionsAndAZs.md)
+ [Using local zones with ElastiCache](Local_zones.md)
+ [Mitigating Failures](disaster-recovery-resiliency.md#FaultTolerance)
# Choosing your node size
The node size you select for your ElastiCache cluster impacts costs, performance, and fault tolerance.
## Node size (Valkey and Redis OSS)
For information about the benefits of Graviton processors, see [AWS Graviton Processor](https://aws.amazon.com/pm/ec2-graviton/).
Answering the following questions can help you determine the minimum node type you need for your Valkey or Redis OSS implementation:
+ Do you expect throughput-bound workloads with multiple client connections?
If this is the case and you're running Redis OSS version 5.0.6 or higher, you can get better throughput and latency with our enhanced I/O feature, where available CPUs are used for offloading the client connections, on behalf of the Redis OSS engine. If you're running Redis OSS version 7.0.4 or higher, on top of enhanced I/O, you will get additional acceleration with enhanced I/O multiplexing, where each dedicated network IO thread pipelines commands from multiple clients into the Redis OSS engine, taking advantage of Redis OSS' ability to efficiently process commands in batches. In ElastiCache for Redis OSS v7.1 and above, we extended the enhanced I/O threads functionality to also handle the presentation layer logic. By presentation layer, what we mean is that Enhanced I/O threads are now not only reading client input, but also parsing the input into Redis OSS binary command format, which is then forwarded to the main thread for execution, providing performance gain. Refer to the [blog post](https://aws.amazon.com/blogs/database/achieve-over-500-million-requests-per-second-per-cluster-with-amazon-elasticache-for-redis-7-1/) and the [supported versions](VersionManagement.md#supported-engine-versions) page for additional details.
+ Do you have workloads that access a small percentage of their data regularly?
If this is the case and you are running on Redis OSS engine version 6.2 or later, you can leverage data tiering by choosing the r6gd node type. With data tiering, least-recently used data is stored in SSD. When it is retrieved there is a small latency cost, which is balanced by cost savings. For more information, see [Data tiering in ElastiCache](data-tiering.md).
For more information, see [Supported node types](CacheNodes.SupportedTypes.md).
+ How much total memory do you need for your data?
To get a general estimate, take the size of the items that you want to cache. Multiply this size by the number of items that you want to keep in the cache at the same time. To get a reasonable estimation of the item size, first serialize your cache items, then count the characters. Then divide this over the number of shards in your cluster.
For more information, see [Supported node types](CacheNodes.SupportedTypes.md).
+ What version of Redis OSS are you running?
Redis OSS versions before 2.8.22 require you to reserve more memory for failover, snapshot, synchronizing, and promoting a replica to primary operations. This requirement occurs because you must have sufficient memory available for all writes that occur during the process.
Redis OSS version 2.8.22 and later use a forkless save process that requires less available memory than the earlier process.
For more information, see the following:
+ [How synchronization and backup are implemented](Replication.Redis.Versions.md)
+ [Ensuring you have enough memory to make a Valkey or Redis OSS snapshot](BestPractices.BGSAVE.md)
+ How write-heavy is your application?
Write heavy applications can require significantly more available memory, memory not used by data, when taking snapshots or failing over. Whenever the `BGSAVE` process is performed, you must have sufficient memory that is unused by data to accommodate all the writes that transpire during the `BGSAVE` process. Examples are when taking a snapshot, when syncing a primary cluster with a replica in a cluster, and when enabling the append-only file (AOF) feature. Another is when promoting a replica to primary (if you have Multi-AZ enabled). The worst case is when all of your data is rewritten during the process. In this case, you need a node instance size with twice as much memory as needed for data alone.
For more detailed information, see [Ensuring you have enough memory to make a Valkey or Redis OSS snapshot](BestPractices.BGSAVE.md).
+ Will your implementation be a standalone Valkey or Redis OSS (cluster mode disabled) cluster, or a Valkey or Redis OSS (cluster mode enabled) cluster with multiple shards?
**Valkey or Redis OSS (cluster mode disabled) cluster**
If you're implementing a Valkey or Redis OSS (cluster mode disabled) cluster, your node type must be able to accommodate all your data plus the necessary overhead as described in the previous bullet.
For example, suppose that you estimate that the total size of all your items is 12 GB. In this case, you can use a `cache.m3.xlarge` node with 13.3 GB of memory or a `cache.r3.large` node with 13.5 GB of memory. However, you might need more memory for `BGSAVE` operations. If your application is write-heavy, double the memory requirements to at least 24 GB. Thus, use either a `cache.m3.2xlarge` with 27.9 GB of memory or a `cache.r3.xlarge` with 30.5 GB of memory.
**Valkey or Redis OSS (cluster mode enabled) with multiple shards**
If you're implementing a Valkey or Redis OSS (cluster mode enabled) cluster with multiple shards, then the node type must be able to accommodate `bytes-for-data-and-overhead / number-of-shards` bytes of data.
For example, suppose that you estimate that the total size of all your items to be 12 GB and you have two shards. In this case, you can use a `cache.m3.large` node with 6.05 GB of memory (12 GB / 2). However, you might need more memory for `BGSAVE` operations. If your application is write-heavy, double the memory requirements to at least 12 GB per shard. Thus, use either a `cache.m3.xlarge` with 13.3 GB of memory or a `cache.r3.large` with 13.5 GB of memory.
+ Are you using Local Zones?
[Local Zones](Local_zones.md) enable you to place resources such as an ElastiCache cluster in multiple locations close to your users. But when you choose your node size, be aware that the available node sizes are limited to the following at this time, regardless of capacity requirements:
+ Current generation:
**M5 node types:** `cache.m5.large`, `cache.m5.xlarge`, `cache.m5.2xlarge`, `cache.m5.4xlarge`, `cache.m5.12xlarge`, `cache.m5.24xlarge`
**R5 node types:** `cache.r5.large`, `cache.r5.xlarge`, `cache.r5.2xlarge`, `cache.r5.4xlarge`, `cache.r5.12xlarge`, `cache.r5.24xlarge`
**T3 node types:** `cache.t3.micro`, `cache.t3.small`, `cache.t3.medium`
While your cluster is running, you can monitor the memory usage, processor utilization, cache hits, and cache misses metrics that are published to CloudWatch. You might notice that your cluster doesn't have the hit rate that you want or that keys are being evicted too often. In these cases, you can choose a different node size with larger CPU and memory specifications.
When monitoring CPU usage, remember Valkey and Redis OSS are single-threaded. Thus, multiply the reported CPU usage by the number of CPU cores to get that actual usage. For example, a four-core CPU reporting a 20-percent usage rate is actually the one core Redis OSS is running at 80 percent utilization.
## Node size (Memcached)
Memcached clusters contain one or more nodes with the cluster's data partitioned across the nodes. Because of this, the memory needs of the cluster and the memory of a node are related, but not the same. You can attain your needed cluster memory capacity by having a few large nodes or several smaller nodes. Further, as your needs change, you can add nodes to or remove nodes from the cluster and thus pay only for what you need.
The total memory capacity of your cluster is calculated by multiplying the number of nodes in the cluster by the RAM capacity of each node after deducting system overhead. The capacity of each node is based on the node type.
```
cluster_capacity = number_of_nodes * (node_capacity - system_overhead)
```
The number of nodes in the cluster is a key factor in the availability of your cluster running Memcached. The failure of a single node can have an impact on the availability of your application and the load on your backend database. In such a case, ElastiCache provisions a replacement for a failed node and it gets repopulated. To reduce this availability impact, spread your memory and compute capacity over more nodes with smaller capacity, rather than using fewer high-capacity nodes.
In a scenario where you want to have 35 GB of cache memory, you can set up any of the following configurations:
+ 11 `cache.t2.medium` nodes with 3.22 GB of memory and 2 threads each = 35.42 GB and 22 threads.
+ 6 `cache.m4.large` nodes with 6.42 GB of memory and 2 threads each = 38.52 GB and 12 threads.
+ 3 `cache.r4.large` nodes with 12.3 GB of memory and 2 threads each = 36.90 GB and 6 threads.
+ 3 `cache.m4.xlarge` nodes with 14.28 GB of memory and 4 threads each = 42.84 GB and 12 threads.
**Comparing node options**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonElastiCache/latest/dg/CacheNodes.SelectSize.html)
These options each provide similar memory capacity but different computational capacity and cost. To compare the costs of your specific options, see [Amazon ElastiCache Pricing](https://aws.amazon.com/elasticache/pricing/).
For clusters running Memcached, some of the available memory on each node is used for connection overhead. For more information, see [Memcached connection overhead](ParameterGroups.Engine.md#ParameterGroups.Memcached.Overhead)
Using multiple nodes requires spreading the keys across them. Each node has its own endpoint. For easy endpoint management, you can use the ElastiCache the Auto Discovery feature, which enables client programs to automatically identify all of the nodes in a cluster. For more information, see [Automatically identify nodes in your cluster (Memcached)](AutoDiscovery.md).
In some cases, you might be unsure how much capacity you need. If so, for testing we recommend starting with one `cache.m5.large` node. Then monitor the memory usage, CPU utilization, and cache hit rate with the ElastiCache metrics that are published to Amazon CloudWatch. For more information on CloudWatch metrics for ElastiCache, see [Monitoring use with CloudWatch Metrics](CacheMetrics.md). For production and larger workloads, the R5 nodes provide the best performance and RAM cost value.
If your cluster doesn't have the hit rate that you want, you can easily add more nodes to increase the total available memory in your cluster.
If your cluster is bound by CPU but has sufficient hit rate, set up a new cluster with a node type that provides more compute power.
# Creating a cluster for Valkey or Redis OSS
The following examples show how to create a Valkey or Redis OSS cluster using the AWS Management Console, AWS CLI and ElastiCache API.
## Creating a Valkey or Redis OSS (cluster mode disabled) (Console)
ElastiCache supports replication when you use the Valkey or Redis OSS engine. To monitor the latency between when data is written to a Valkey or Redis OSS read/write primary cluster and when it is propagated to a read-only secondary cluster, ElastiCache adds to the cluster a special key, `ElastiCacheMasterReplicationTimestamp`. This key is the current Universal Universal Time (UTC) time. Because a Valkey or Redis OSS cluster might be added to a replication group at a later time, this key is included in all Valkey or Redis OSS clusters, even if initially they are not members of a replication group. For more information on replication groups, see [High availability using replication groups](Replication.md).
To create a Valkey or Redis OSS (cluster mode disabled) cluster, follow the steps at [Creating a Valkey (cluster mode disabled) cluster (Console)](SubnetGroups.designing-cluster-pre.valkey.md#Clusters.Create.CON.valkey-gs).
As soon as your cluster's status is *available*, you can grant Amazon EC2 access to it, connect to it, and begin using it. For more information, see [Step 3. Authorize access to the cluster](SubnetGroups.designing-cluster-pre.valkey.md#GettingStarted.AuthorizeAccess.valkey) and [Step 4. Connect to the cluster's node](SubnetGroups.designing-cluster-pre.valkey.md#GettingStarted.ConnectToCacheNode.valkey).
**Important**
As soon as your cluster becomes available, you're billed for each hour or partial hour that the cluster is active, even if you're not actively using it. To stop incurring charges for this cluster, you must delete it. See [Deleting a cluster in ElastiCache](Clusters.Delete.md).
## Creating a Valkey or Redis OSS (cluster mode enabled) cluster (Console)
If you are running Redis OSS 3.2.4 or later, you can create a Valkey or Redis OSS (cluster mode enabled) cluster. Valkey or Redis OSS (cluster mode enabled) clusters support partitioning your data across 1 to 500 shards (API/CLI: node groups) but with some limitations. For a comparison of Valkey or Redis OSS (cluster mode disabled) and Valkey or Redis OSS (cluster mode enabled), see [Supported engines and versions](VersionManagement.md#supported-engine-versions).
**To create a Valkey or Redis OSS (cluster mode enabled) cluster using the ElastiCache console**
1. Sign in to the AWS Management Console and open the Amazon ElastiCache console at [https://console.aws.amazon.com/elasticache/](https://console.aws.amazon.com/elasticache/).
1. From the list in the upper-right corner, choose the AWS Region that you want to launch this cluster in.
1. Choose **Get started** from the navigation pane.
1. Choose **Create VPC** and follow the steps outlined at [Creating a Virtual Private Cloud (VPC)](VPCs.CreatingVPC.md).
1. On the ElastiCache dashboard page, choose **Create cluster** and then choose **Create Valkey cluster** or **Create Redis OSS cluster**.
1. Under **Cluster settings**, do the following:
1. Choose **Configure and create a new cluster**.
1. For **Cluster mode**, choose **Enabled**.
1. For **Cluster info** enter a value for **Name**.
1. (Optional) Enter a value for **Description**.
1. Under **Location**:
------
#### [ AWS Cloud ]
1. For **AWS Cloud**, we recommend you accept the default settings for **Multi-AZ** and **Auto-failover**. For more information, see [Minimizing downtime in ElastiCache for Redis OSS with Multi-AZ](AutoFailover.md).
1. Under **Cluster settings**
1. For **Engine version**, choose an available version.
1. For **Port**, use the default port, 6379. If you have a reason to use a different port, enter the port number.
1. For **Parameter group**, choose a parameter group or create a new one. Parameter groups control the runtime parameters of your cluster. For more information on parameter groups, see [Valkey and Redis OSS parameters](ParameterGroups.Engine.md#ParameterGroups.Redis) and [Creating an ElastiCache parameter group](ParameterGroups.Creating.md).
**Note**
When you select a parameter group to set the engine configuration values, that parameter group is applied to all clusters in the global datastore. On the **Parameter Groups** page, the yes/no **Global** attribute indicates whether a parameter group is part of a global datastore.
1. For **Node type**, choose the down arrow (![\[Downward-pointing triangle icon, typically used to indicate a dropdown menu.\]](http://docs.aws.amazon.com/AmazonElastiCache/latest/dg/images/ElastiCache-DnArrow.png)). In the **Change node type** dialog box, choose a value for **Instance family** for the node type that you want. Then choose the node type that you want to use for this cluster, and then choose **Save**.
For more information, see [Choosing your node size](CacheNodes.SelectSize.md).
If you choose an r6gd node type, data-tiering is automatically enabled. For more information, see [Data tiering in ElastiCache](data-tiering.md).
1. For **Number of shards**, choose the number of shards (partitions/node groups) that you want for this Valkey or Redis OSS (cluster mode enabled) cluster.
For some versions of Valkey or Redis OSS (cluster mode enabled), you can change the number of shards in your cluster dynamically:
+ **Redis OSS 3.2.10 and later** – If your cluster is running Redis OSS 3.2.10 or later versions, you can change the number of shards in your cluster dynamically. For more information, see [Scaling Valkey or Redis OSS (Cluster Mode Enabled) clusters](scaling-redis-cluster-mode-enabled.md).
+ **Other Redis OSS versions** – If your cluster is running a version of Redis OSS before version 3.2.10, there's another approach. To change the number of shards in your cluster in this case, create a new cluster with the new number of shards. For more information, see [Restoring from a backup into a new cache](backups-restoring.md).
1. For **Replicas per shard**, choose the number of read replica nodes that you want in each shard.
The following restrictions exist for Valkey or Redis OSS (cluster mode enabled).
+ If you have Multi-AZ enabled, make sure that you have at least one replica per shard.
+ The number of replicas is the same for each shard when creating the cluster using the console.
+ The number of read replicas per shard is fixed and cannot be changed. If you find you need more or fewer replicas per shard (API/CLI: node group), you must create a new cluster with the new number of replicas. For more information, see [Tutorial: Seeding a new node-based cluster with an externally created backup](backups-seeding-redis.md).
1. Under **Connectivity**
1. For **Network type**, choose the IP version(s) this cluster will support.
1. For **Subnet groups**, choose the subnet that you want to apply to this cluster. ElastiCache uses that subnet group to choose a subnet and IP addresses within that subnet to associate with your nodes. ElastiCache clusters require a dual-stack subnet with both IPv4 and IPv6 addresses assigned to them to operate in dual-stack mode and an IPv6-only subnet to operate as IPv6-only.
When creating a new subnet group, enter the **VPC ID** to which it belongs.
Select a **Discovery IP type**. Only the IP adresses of your chosen protocol are returned.
For more information, see:
+ [Choosing a network type in ElastiCache](network-type.md).
+ [Create a subnet in your VPC](https://docs.aws.amazon.com/vpc/latest/userguide/working-with-vpcs.html#AddaSubnet).
If you are [Using local zones with ElastiCache](Local_zones.md), you must create or choose a subnet that is in the local zone.
For more information, see [Subnets and subnet groups](SubnetGroups.md).
1. For **Availability zone placements**, you have two options:
+ **No preference** – ElastiCache chooses the Availability Zone.
+ **Specify availability zones** – You specify the Availability Zone for each cluster.
If you chose to specify the Availability Zones, for each cluster in each shard, choose the Availability Zone from the list.
For more information, see [Choosing regions and availability zones for ElastiCache](RegionsAndAZs.md).
1. Choose **Next**
1. Under **Advanced Valkey settings** or **Advanced Redis OSS settings** or
1. For **Security**:
1. To encrypt your data, you have the following options:
+ **Encryption at rest** – Enables encryption of data stored on disk. For more information, see [Encryption at Rest](at-rest-encryption.md).
**Note**
You have the option to supply a different encryption key by choosing **Customer Managed AWS KMS key** and choosing the key. For more information, see [Using customer managed keys from AWS KMS](at-rest-encryption.md#using-customer-managed-keys-for-elasticache-security).
+ **Encryption in-transit** – Enables encryption of data on the wire. For more information, see [encryption in transit](in-transit-encryption.md). For Valkey 7.2 and above or Redis OSS 6.0 and above, if you enable Encryption in-transit you will be prompted to specify one of the following **Access Control** options:
+ **No Access Control** – This is the default setting. This indicates no restrictions on user access to the cluster.
+ **User Group Access Control List** – Select a user group with a defined set of users that can access the cluster. For more information, see [Managing User Groups with the Console and CLI](Clusters.RBAC.md#User-Groups).
+ **AUTH Default User** – An authentication mechanism for a Valkey or Redis OSS server. For more information, see [AUTH](auth.md).
+ **AUTH** – An authentication mechanism for Valkey or Redis OSS server. For more information, see [AUTH](auth.md).
**Note**
For Redis OSS versions between 3.2.6 onward, excluding version 3.2.10, AUTH is the sole option.
1. For **Security groups**, choose the security groups that you want for this cluster. A *security group* acts as a firewall to control network access to your cluster. You can use the default security group for your VPC or create a new one.
For more information on security groups, see [Security groups for your VPC](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html) in the *Amazon VPC User Guide.*
1. For regularly scheduled automatic backups, select **Enable automatic backups** and then enter the number of days that you want each automatic backup retained before it is automatically deleted. If you don't want regularly scheduled automatic backups, clear the **Enable automatic backups** check box. In either case, you always have the option to create manual backups.
For more information on backup and restore, see [Snapshot and restore](backups.md).
1. (Optional) Specify a maintenance window. The *maintenance window* is the time, generally an hour in length, each week when ElastiCache schedules system maintenance for your cluster. You can allow ElastiCache to choose the day and time for your maintenance window (*No preference*), or you can choose the day, time, and duration yourself (*Specify maintenance window*). If you choose *Specify maintenance window* from the lists, choose the *Start day*, *Start time*, and *Duration* (in hours) for your maintenance window. All times are UCT times.
For more information, see [Managing ElastiCache cluster maintenance](maintenance-window.md).
1. (Optional) For **Logs**:
+ Under **Log format**, choose either **Text** or **JSON**.
+ Under **Destination Type**, choose either **CloudWatch Logs** or **Kinesis Firehose**.
+ Under **Log destination**, choose either **Create new** and enter either your CloudWatch Logs log group name or your Firehose stream name, or choose **Select existing** and then choose either your CloudWatch Logs log group name or your Firehose stream name,
1. For **Tags**, to help you manage your clusters and other ElastiCache resources, you can assign your own metadata to each resource in the form of tags. For mor information, see [Tagging your ElastiCache resources](Tagging-Resources.md).
1. Choose **Next**.
1. Review all your entries and choices, then make any needed corrections. When you're ready, choose **Create**.
------
#### [ On premises ]
1. For **On premises**, we recommend you leave **Auto-failover** enabled. For more information, see [Minimizing downtime in ElastiCache for Redis OSS with Multi-AZ](AutoFailover.md)
1. Follow the steps at [Using Outposts](ElastiCache-Outposts.md).
------
To create the equivalent using the ElastiCache API or AWS CLI instead of the ElastiCache console, see the following:
+ API: [CreateReplicationGroup](https://docs.aws.amazon.com/AmazonElastiCache/latest/APIReference/API_CreateReplicationGroup.html)
+ CLI: [create-replication-group](https://docs.aws.amazon.com/cli/latest/reference/elasticache/create-replication-group.html)
As soon as your cluster's status is *available*, you can grant EC2 access to it, connect to it, and begin using it. For more information, see [Step 3. Authorize access to the cluster](SubnetGroups.designing-cluster-pre.valkey.md#GettingStarted.AuthorizeAccess.valkey) and [Step 4. Connect to the cluster's node](SubnetGroups.designing-cluster-pre.valkey.md#GettingStarted.ConnectToCacheNode.valkey).
**Important**
As soon as your cluster becomes available, you're billed for each hour or partial hour that the cluster is active, even if you're not actively using it. To stop incurring charges for this cluster, you must delete it. See [Deleting a cluster in ElastiCache](Clusters.Delete.md).
## Creating a cluster (AWS CLI)
To create a cluster using the AWS CLI, use the `create-cache-cluster` command.
**Important**
As soon as your cluster becomes available, you're billed for each hour or partial hour that the cluster is active, even if you're not actively using it. To stop incurring charges for this cluster, you must delete it. See [Deleting a cluster in ElastiCache](Clusters.Delete.md).
### Creating a Valkey or Redis OSS (cluster mode disabled) cluster (CLI)
**Example – A Valkey or Redis OSS (cluster mode disabled) Cluster with no read replicas**
The following CLI code creates a Valkey or Redis OSS (cluster mode disabled) cluster with no replicas.
When creating cluster using a node type from the r6gd family, you must pass the `data-tiering-enabled` parameter.
For Linux, macOS, or Unix:
```
aws elasticache create-cache-cluster \
--cache-cluster-id my-cluster \
--cache-node-type cache.r4.large \
--engine redis \
--num-cache-nodes 1 \
--cache-parameter-group default.redis6.x \
--snapshot-arns arn:aws:s3:::amzn-s3-demo-bucket/snapshot.rdb
```
For Windows:
```
aws elasticache create-cache-cluster ^
--cache-cluster-id my-cluster ^
--cache-node-type cache.r4.large ^
--engine redis ^
--num-cache-nodes 1 ^
--cache-parameter-group default.redis6.x ^
--snapshot-arns arn:aws:s3:::amzn-s3-demo-bucket/snapshot.rdb
```
### Creating a Valkey or Redis OSS (cluster mode enabled) cluster (AWS CLI)
Valkey or Redis OSS (cluster mode enabled) clusters (API/CLI: replication groups) cannot be created using the `create-cache-cluster` operation. To create a Valkey or Redis OSS (cluster mode enabled) cluster (API/CLI: replication group), see [Creating a Valkey or Redis OSS (Cluster Mode Enabled) replication group from scratch (AWS CLI)](Replication.CreatingReplGroup.NoExistingCluster.Cluster.md#Replication.CreatingReplGroup.NoExistingCluster.Cluster.CLI).
For more information, see the AWS CLI for ElastiCache reference topic [https://docs.aws.amazon.com/cli/latest/reference/elasticache/create-replication-group.html](https://docs.aws.amazon.com/cli/latest/reference/elasticache/create-replication-group.html).
## Creating a cluster for Valkey or Redis OSS (ElastiCache API)
To create a cluster using the ElastiCache API, use the `CreateCacheCluster` action.
**Important**
As soon as your cluster becomes available, you're billed for each hour or partial hour that the cluster is active, even if you're not using it. To stop incurring charges for this cluster, you must delete it. See [Deleting a cluster in ElastiCache](Clusters.Delete.md).
**Topics**
+ [
### Creating a Valkey or Redis OSS (cluster mode disabled) cluster (ElastiCache API)
](#Clusters.Create.API.Redis)
+ [
### Creating a cluster in Valkey or Redis OSS (cluster mode enabled) (ElastiCache API)
](#Clusters.Create.API.RedisCluster)
### Creating a Valkey or Redis OSS (cluster mode disabled) cluster (ElastiCache API)
The following code creates a Valkey or Redis OSS (cluster mode disabled) cluster (ElastiCache API).
Line breaks are added for ease of reading.
```
https://elasticache.us-west-2.amazonaws.com/
?Action=CreateCacheCluster
&CacheClusterId=my-cluster
&CacheNodeType=cache.r4.large
&CacheParameterGroup=default.redis3.2
&Engine=redis
&EngineVersion=3.2.4
&NumCacheNodes=1
&SignatureVersion=4
&SignatureMethod=HmacSHA256
&SnapshotArns.member.1=arn%3Aaws%3As3%3A%3A%3AmyS3Bucket%2Fdump.rdb
&Timestamp=20150508T220302Z
&Version=2015-02-02
&X-Amz-Algorithm=&AWS;4-HMAC-SHA256
&X-Amz-Credential=
&X-Amz-Date=20150508T220302Z
&X-Amz-Expires=20150508T220302Z
&X-Amz-SignedHeaders=Host
&X-Amz-Signature=
```
### Creating a cluster in Valkey or Redis OSS (cluster mode enabled) (ElastiCache API)
Valkey or Redis OSS (cluster mode enabled) clusters (API/CLI: replication groups) cannot be created using the `CreateCacheCluster` operation. To create a Valkey or Redis OSS (cluster mode enabled) cluster (API/CLI: replication group), see [Creating a replication group in Valkey or Redis OSS (Cluster Mode Enabled) from scratch (ElastiCache API)](Replication.CreatingReplGroup.NoExistingCluster.Cluster.md#Replication.CreatingReplGroup.NoExistingCluster.Cluster.API).
For more information, see the ElastiCache API reference topic [https://docs.aws.amazon.com/AmazonElastiCache/latest/APIReference/API_CreateReplicationGroup.html](https://docs.aws.amazon.com/AmazonElastiCache/latest/APIReference/API_CreateReplicationGroup.html).
# Creating a cluster for Memcached
The following examples show how to create a cluster using the AWS Management Console, AWS CLI and ElastiCache API.
## Creating a Memcached cluster (console)
When you use the Memcached engine, Amazon ElastiCache supports horizontally partitioning your data over multiple nodes. Memcached enables auto discovery so you don't need to keep track of the endpoints for each node. Memcached tracks each node's endpoint, updating the endpoint list as nodes are added and removed. All your application needs to interact with the cluster is the configuration endpoint.
To create a Memcached cluster via the console, follow the steps at [Creating a Valkey (cluster mode disabled) cluster (Console)](Clusters.Create.md#Clusters.Create.CON.RedisCluster). When you reach step five, select **Create Memcached cache**.
As soon as your cluster's status is *available*, you can grant Amazon EC2 access to it, connect to it, and begin using it. For more information, see the similar steps [Step 3. Authorize access to the cluster](SubnetGroups.designing-cluster-pre.valkey.md#GettingStarted.AuthorizeAccess.valkey) and [Step 4. Connect to the cluster's node](SubnetGroups.designing-cluster-pre.valkey.md#GettingStarted.ConnectToCacheNode.valkey).
**Important**
As soon as your cluster becomes available, you're billed for each hour or partial hour that the cluster is active, even if you're not actively using it. To stop incurring charges for this cluster, you must delete it. See [Deleting a cluster in ElastiCache](Clusters.Delete.md).
## Creating a cluster (AWS CLI)
To create a cluster using the AWS CLI, use the `create-cache-cluster` command.
**Important**
As soon as your cluster becomes available, you're billed for each hour or partial hour that the cluster is active, even if you're not actively using it. To stop incurring charges for this cluster, you must delete it. See [Deleting a cluster in ElastiCache](Clusters.Delete.md).
### Creating a Memcached Cache Cluster (AWS CLI)
The following CLI code creates a Memcached cluster with 3 nodes.
For Linux, macOS, or Unix:
```
aws elasticache create-cache-cluster \
--cache-cluster-id my-cluster \
--cache-node-type cache.r4.large \
--engine memcached \
--engine-version 1.4.24 \
--cache-parameter-group default.memcached1.4 \
--num-cache-nodes 3
```
For Windows:
```
aws elasticache create-cache-cluster ^
--cache-cluster-id my-cluster ^
--cache-node-type cache.r4.large ^
--engine memcached ^
--engine-version 1.4.24 ^
--cache-parameter-group default.memcached1.4 ^
--num-cache-nodes 3
```
## Creating a cluster for Memcached (ElastiCache API)
To create a cluster using the ElastiCache API, use the `CreateCacheCluster` action.
**Important**
As soon as your cluster becomes available, you're billed for each hour or partial hour that the cluster is active, even if you're not using it. To stop incurring charges for this cluster, you must delete it. See [Deleting a cluster in ElastiCache](Clusters.Delete.md).
**Topics**
+ [
### Creating a Memcached cluster (ElastiCache API)
](#Clusters.Create.API.Memcached)
### Creating a Memcached cluster (ElastiCache API)
The following code creates a Memcached cluster with 3 nodes (ElastiCache API).
Line breaks are added for ease of reading.
```
https://elasticache.us-west-2.amazonaws.com/
?Action=CreateCacheCluster
&CacheClusterId=my-cluster
&CacheNodeType=cache.r4.large
&Engine=memcached
&NumCacheNodes=3
&SignatureVersion=4
&SignatureMethod=HmacSHA256
&Timestamp=20150508T220302Z
&Version=2015-02-02
&X-Amz-Algorithm=&AWS;4-HMAC-SHA256
&X-Amz-Credential=
&X-Amz-Date=20150508T220302Z
&X-Amz-Expires=20150508T220302Z
&X-Amz-SignedHeaders=Host
&X-Amz-Signature=
```
# Viewing an ElastiCache cluster's details
You can view detail information about one or more clusters using the ElastiCache console, AWS CLI, or ElastiCache API.
## Viewing a Memcached cluster's details (Console)
You can view the details of a Memcached cluster using the ElastiCache console, the AWS CLI for ElastiCache, or the ElastiCache API.
The following procedure details how to view the details of a Memcached cluster using the ElastiCache console.
**To view a Memcached cluster's details**
1. Sign in to the AWS Management Console and open the Amazon ElastiCache console at [https://console.aws.amazon.com/elasticache/](https://console.aws.amazon.com/elasticache/).
1. From the list in the upper-right corner, choose the AWS Region you are interested in.
1. In the ElastiCache engine dashboard, choose **Memcached**. Doing this displays a list of all your clusters that are running on the Memcached engine.
1. To see details of a cluster, choose the box to the left of the cluster's name.
1. To view node information, choose the **Nodes** tab, which displays information on node(s) status and endpoint.
1. To view metrics, choose the **Metrics** tab, which displays the relevant metrics for all nodes in the cluster. For more information, see [Monitoring use with CloudWatch Metrics](CacheMetrics.md)
1. Choose the **Network and security** tab to view details on the cluster's network connectivity and subnet group configuration and the VPC security group. For more information, see [Subnets and subnet groups](SubnetGroups.md).
1. Choose the **Maintenance** tab to view details on the cluster's maintenance settings. For more information, see [Managing ElastiCache cluster maintenance](maintenance-window.md).
1. Choose the **Tags** tab to view details on any tags applied to cluster resources. For more information, see [Tagging your ElastiCache resources](Tagging-Resources.md).
## Viewing Valkey or Redis OSS (Cluster Mode Disabled) details (Console)
You can view the details of a Valkey or Redis OSS (cluster mode disabled) cluster using the ElastiCache console, the AWS CLI for ElastiCache, or the ElastiCache API.
The following procedure details how to view the details of a Valkey or Redis OSS (cluster mode disabled) cluster using the ElastiCache console.
**To view a Valkey or Redis OSS (cluster mode disabled) cluster's details**
1. Sign in to the AWS Management Console and open the Amazon ElastiCache console at [https://console.aws.amazon.com/elasticache/](https://console.aws.amazon.com/elasticache/).
1. In the ElastiCache engine dashboard, choose either **Valkey**or **Redis OSS** to display a list of all your clusters that are running on that engine.
1. To see details of a cluster, select the check box to the left of the cluster's name. Make sure that you select a cluster running the Valkey or Redis OSS engine, not Clustered Valkey or Clustered Redis OSS. Doing this displays details about the cluster, including the cluster's primary endpoint.
1. To view node information:
1. Choose the cluster's name.
1. Choose the **Shards and nodes** tab. Doing this displays details about each node, including the node's endpoint which you need to use to read from the cluster.
1. To view metrics, choose the **Metrics** tab, which displays the relevant metrics for all nodes in the cluster. For more information, see [Monitoring use with CloudWatch Metrics](CacheMetrics.md)
1. To view logs, choose the **Logs** tab, which indicates if the cluster is using Slow logs or Engine logs and provides relevant details. For more information, see [Log delivery](Log_Delivery.md).
1. Choose the **Network and security** tab to view details on the cluster's network connectivity and subnet group configuration. For more information, see [Subnets and subnet groups](SubnetGroups.md).
1. Choose the **Maintenance** tab to view details on the cluster's maintenance settings. For more information, see [Managing ElastiCache cluster maintenance](maintenance-window.md).
1. Choose the **Service updates** tab to view details on any available service updates along with their recommended apply-by date. For more information, see [Service updates in ElastiCache](Self-Service-Updates.md).
1. Choose the **Tags** tab to view details on any tags applied to cluster resources. For more information, see [Tagging your ElastiCache resources](Tagging-Resources.md).
## Viewing details for a Valkey or Redis OSS (Cluster Mode Enabled) cluster (Console)
You can view the details of a Valkey or Redis OSS (cluster mode enabled) cluster using the ElastiCache console, the AWS CLI for ElastiCache, or the ElastiCache API.
The following procedure details how to view the details of a Valkey or Redis OSS (cluster mode enabled) cluster using the ElastiCache console.
**To view a Valkey or Redis OSS (cluster mode enabled) cluster's details**
1. Sign in to the AWS Management Console and open the Amazon ElastiCache console at [https://console.aws.amazon.com/elasticache/](https://console.aws.amazon.com/elasticache/).
1. From the list in the upper-right corner, choose the AWS Region you are interested in.
1. In the ElastiCache engine dashboard, choose **Valkey** or **Redis OSS** to display a list of all your clusters that are running on that engine.
1. To see details of a Valkey or Redis OSS (cluster mode enabled) cluster, choose the box to the left of the cluster's name. Make sure you choose a cluster running the Valkey or Clustered Redis OSS engine.
The screen expands below the cluster and display details about the cluster, including the cluster's configuration endpoint.
1. To see a listing of the cluster's shards and the number of nodes in each shard, choose the **Shards and nodes** tab.
1. To view specific information on a node:
1. Choose the shard's ID.
Doing this displays information about each node, including each node's endpoint that you need to use to read data from the cluster.
1. To view metrics, choose the **Metrics** tab, which displays the relevant metrics for all nodes in the cluster. For more information, see [Monitoring use with CloudWatch Metrics](CacheMetrics.md)
1. To view logs, choose the **Logs** tab, which indicates if the cluster is using Slow logs or Engine logs and provides relevant details. For more information, see [Log delivery](Log_Delivery.md).
1. Choose the **Network and security** tab to view details on the cluster's network connectivity and subnet group configuration, the VPC security group and what, if any, encryption method is enabled on the cluster. For more information, see [Subnets and subnet groups](SubnetGroups.md) and [Data security in Amazon ElastiCache](encryption.md).
1. Choose the **Maintenance** tab to view details on the cluster's maintenance settings. For more information, see [Managing ElastiCache cluster maintenance](maintenance-window.md).
1. Choose the **Service updates** tab to view details on any available service updates along with their recommended apply-by date. For more information, see [Service updates in ElastiCache](Self-Service-Updates.md).
1. Choose the **Tags** tab to view details on any tags applied to cluster resources. For more information, see [Tagging your ElastiCache resources](Tagging-Resources.md).
## Viewing an ElastiCache cluster's details (AWS CLI)
The following code lists the details for *my-cluster*:
```
aws elasticache describe-cache-clusters --cache-cluster-id my-cluster
```
Replace *my-cluster* with the name of your cluster in a case where the cluster is created with 1 cache node and 0 shards using the `create-cache-cluster` command.
```
{
"CacheClusters": [
{
"CacheClusterStatus": "available",
"SecurityGroups": [
{
"Status": "active",
"SecurityGroupId": "sg-dbe93fa2"
}
],
"ClientDownloadLandingPage": "https://console.aws.amazon.com/elasticache/home#client-download:",
"Engine": "redis",
"PreferredMaintenanceWindow": "wed:12:00-wed:13:00",
"CacheSubnetGroupName": "default",
"SnapshotWindow": "08:30-09:30",
"TransitEncryptionEnabled": false,
"AtRestEncryptionEnabled": false,
"CacheClusterId": "my-cluster1",
"CacheClusterCreateTime": "2018-02-26T21:06:43.420Z",
"PreferredAvailabilityZone": "us-west-2c",
"AuthTokenEnabled": false,
"PendingModifiedValues": {},
"CacheNodeType": "cache.r4.large",
"DataTiering": "disabled",
"CacheParameterGroup": {
"CacheNodeIdsToReboot": [],
"ParameterApplyStatus": "in-sync",
"CacheParameterGroupName": "default.redis3.2"
},
"SnapshotRetentionLimit": 0,
"AutoMinorVersionUpgrade": true,
"EngineVersion": "3.2.10",
"CacheSecurityGroups": [],
"NumCacheNodes": 1
}
```
```
{
"CacheClusters": [
{
"SecurityGroups": [
{
"Status": "active",
"SecurityGroupId": "sg-dbe93fa2"
}
],
"ClientDownloadLandingPage": "https://console.aws.amazon.com/elasticache/home#client-download:",
"AuthTokenEnabled": false,
"CacheSubnetGroupName": "default",
"SnapshotWindow": "12:30-13:30",
"AutoMinorVersionUpgrade": true,
"CacheClusterCreateTime": "2018-02-26T21:13:24.250Z",
"CacheClusterStatus": "available",
"AtRestEncryptionEnabled": false,
"PreferredAvailabilityZone": "us-west-2a",
"TransitEncryptionEnabled": false,
"ReplicationGroupId": "my-cluster2",
"Engine": "redis",
"PreferredMaintenanceWindow": "sun:08:30-sun:09:30",
"CacheClusterId": "my-cluster2-001",
"PendingModifiedValues": {},
"CacheNodeType": "cache.r4.large",
"DataTiering": "disabled",
"CacheParameterGroup": {
"CacheNodeIdsToReboot": [],
"ParameterApplyStatus": "in-sync",
"CacheParameterGroupName": "default.redis6.x"
},
"SnapshotRetentionLimit": 0,
"EngineVersion": "6.0",
"CacheSecurityGroups": [],
"NumCacheNodes": 1
},
{
"SecurityGroups": [
{
"Status": "active",
"SecurityGroupId": "sg-dbe93fa2"
}
],
"ClientDownloadLandingPage": "https://console.aws.amazon.com/elasticache/home#client-download:",
"AuthTokenEnabled": false,
"CacheSubnetGroupName": "default",
"SnapshotWindow": "12:30-13:30",
"AutoMinorVersionUpgrade": true,
"CacheClusterCreateTime": "2018-02-26T21:13:24.250Z",
"CacheClusterStatus": "available",
"AtRestEncryptionEnabled": false,
"PreferredAvailabilityZone": "us-west-2b",
"TransitEncryptionEnabled": false,
"ReplicationGroupId": "my-cluster2",
"Engine": "redis",
"PreferredMaintenanceWindow": "sun:08:30-sun:09:30",
"CacheClusterId": "my-cluster2-002",
"PendingModifiedValues": {},
"CacheNodeType": "cache.r4.large",
"DataTiering": "disabled",
"CacheParameterGroup": {
"CacheNodeIdsToReboot": [],
"ParameterApplyStatus": "in-sync",
"CacheParameterGroupName": "default.redis6.x"
},
"SnapshotRetentionLimit": 0,
"EngineVersion": "6.0",
"CacheSecurityGroups": [],
"NumCacheNodes": 1
},
{
"SecurityGroups": [
{
"Status": "active",
"SecurityGroupId": "sg-dbe93fa2"
}
],
"ClientDownloadLandingPage": "https://console.aws.amazon.com/elasticache/home#client-download:",
"AuthTokenEnabled": false,
"CacheSubnetGroupName": "default",
"SnapshotWindow": "12:30-13:30",
"AutoMinorVersionUpgrade": true,
"CacheClusterCreateTime": "2018-02-26T21:13:24.250Z",
"CacheClusterStatus": "available",
"AtRestEncryptionEnabled": false,
"PreferredAvailabilityZone": "us-west-2c",
"TransitEncryptionEnabled": false,
"ReplicationGroupId": "my-cluster2",
"Engine": "redis",
"PreferredMaintenanceWindow": "sun:08:30-sun:09:30",
"CacheClusterId": "my-cluster2-003",
"PendingModifiedValues": {},
"CacheNodeType": "cache.r4.large",
"DataTiering": "disabled",
"CacheParameterGroup": {
"CacheNodeIdsToReboot": [],
"ParameterApplyStatus": "in-sync",
"CacheParameterGroupName": "default.redis3.2"
},
"SnapshotRetentionLimit": 0,
"EngineVersion": "3.2.10",
"CacheSecurityGroups": [],
"NumCacheNodes": 1
}
```
```
{
"CacheClusters": [
{
"SecurityGroups": [
{
"Status": "active",
"SecurityGroupId": "sg-dbe93fa2"
}
],
"ClientDownloadLandingPage": "https://console.aws.amazon.com/elasticache/home#client-download:",
"AuthTokenEnabled": true,
"CacheSubnetGroupName": "default",
"SnapshotWindow": "12:30-13:30",
"AutoMinorVersionUpgrade": true,
"CacheClusterCreateTime": "2018-02-26T21:17:01.439Z",
"CacheClusterStatus": "available",
"AtRestEncryptionEnabled": true,
"PreferredAvailabilityZone": "us-west-2a",
"TransitEncryptionEnabled": true,
"ReplicationGroupId": "my-cluster3",
"Engine": "redis",
"PreferredMaintenanceWindow": "thu:11:00-thu:12:00",
"CacheClusterId": "my-cluster3-0001-001",
"PendingModifiedValues": {},
"CacheNodeType": "cache.r4.large",
"DataTiering": "disabled",
"CacheParameterGroup": {
"CacheNodeIdsToReboot": [],
"ParameterApplyStatus": "in-sync",
"CacheParameterGroupName": "default.redis6.x.cluster.on"
},
"SnapshotRetentionLimit": 0,
"EngineVersion": "6.0",
"CacheSecurityGroups": [],
"NumCacheNodes": 1
},
{
"SecurityGroups": [
{
"Status": "active",
"SecurityGroupId": "sg-dbe93fa2"
}
],
"ClientDownloadLandingPage": "https://console.aws.amazon.com/elasticache/home#client-download:",
"AuthTokenEnabled": true,
"CacheSubnetGroupName": "default",
"SnapshotWindow": "12:30-13:30",
"AutoMinorVersionUpgrade": true,
"CacheClusterCreateTime": "2018-02-26T21:17:01.439Z",
"CacheClusterStatus": "available",
"AtRestEncryptionEnabled": true,
"PreferredAvailabilityZone": "us-west-2b",
"TransitEncryptionEnabled": true,
"ReplicationGroupId": "my-cluster3",
"Engine": "redis",
"PreferredMaintenanceWindow": "thu:11:00-thu:12:00",
"CacheClusterId": "my-cluster3-0001-002",
"PendingModifiedValues": {},
"CacheNodeType": "cache.r4.large",
"DataTiering": "disabled",
"CacheParameterGroup": {
"CacheNodeIdsToReboot": [],
"ParameterApplyStatus": "in-sync",
"CacheParameterGroupName": "default.redis3.2.cluster.on"
},
"SnapshotRetentionLimit": 0,
"EngineVersion": "3.2.6",
"CacheSecurityGroups": [],
"NumCacheNodes": 1
},
{
"SecurityGroups": [
{
"Status": "active",
"SecurityGroupId": "sg-dbe93fa2"
}
],
"ClientDownloadLandingPage": "https://console.aws.amazon.com/elasticache/home#client-download:",
"AuthTokenEnabled": true,
"CacheSubnetGroupName": "default",
"SnapshotWindow": "12:30-13:30",
"AutoMinorVersionUpgrade": true,
"CacheClusterCreateTime": "2018-02-26T21:17:01.439Z",
"CacheClusterStatus": "available",
"AtRestEncryptionEnabled": true,
"PreferredAvailabilityZone": "us-west-2c",
"TransitEncryptionEnabled": true,
"ReplicationGroupId": "my-cluster3",
"Engine": "redis",
"PreferredMaintenanceWindow": "thu:11:00-thu:12:00",
"CacheClusterId": "my-cluster3-0001-003",
"PendingModifiedValues": {},
"CacheNodeType": "cache.r4.large",
"DataTiering": "disabled",
"CacheParameterGroup": {
"CacheNodeIdsToReboot": [],
"ParameterApplyStatus": "in-sync",
"CacheParameterGroupName": "default.redis6.x.cluster.on"
},
"SnapshotRetentionLimit": 0,
"EngineVersion": "6.0",
"CacheSecurityGroups": [],
"NumCacheNodes": 1
},
{
"SecurityGroups": [
{
"Status": "active",
"SecurityGroupId": "sg-dbe93fa2"
}
],
"ClientDownloadLandingPage": "https://console.aws.amazon.com/elasticache/home#client-download:",
"AuthTokenEnabled": true,
"CacheSubnetGroupName": "default",
"SnapshotWindow": "12:30-13:30",
"AutoMinorVersionUpgrade": true,
"CacheClusterCreateTime": "2018-02-26T21:17:01.439Z",
"CacheClusterStatus": "available",
"AtRestEncryptionEnabled": true,
"PreferredAvailabilityZone": "us-west-2b",
"TransitEncryptionEnabled": true,
"ReplicationGroupId": "my-cluster3",
"Engine": "redis",
"PreferredMaintenanceWindow": "thu:11:00-thu:12:00",
"CacheClusterId": "my-cluster3-0002-001",
"PendingModifiedValues": {},
"CacheNodeType": "cache.r4.large",
"DataTiering": "disabled",
"CacheParameterGroup": {
"CacheNodeIdsToReboot": [],
"ParameterApplyStatus": "in-sync",
"CacheParameterGroupName": "default.redis6.x.cluster.on"
},
"SnapshotRetentionLimit": 0,
"EngineVersion": "6.0",
"CacheSecurityGroups": [],
"NumCacheNodes": 1
},
{
"SecurityGroups": [
{
"Status": "active",
"SecurityGroupId": "sg-dbe93fa2"
}
],
"ClientDownloadLandingPage": "https://console.aws.amazon.com/elasticache/home#client-download:",
"AuthTokenEnabled": true,
"CacheSubnetGroupName": "default",
"SnapshotWindow": "12:30-13:30",
"AutoMinorVersionUpgrade": true,
"CacheClusterCreateTime": "2018-02-26T21:17:01.439Z",
"CacheClusterStatus": "available",
"AtRestEncryptionEnabled": true,
"PreferredAvailabilityZone": "us-west-2c",
"TransitEncryptionEnabled": true,
"ReplicationGroupId": "my-cluster3",
"Engine": "redis",
"PreferredMaintenanceWindow": "thu:11:00-thu:12:00",
"CacheClusterId": "my-cluster3-0002-002",
"PendingModifiedValues": {},
"CacheNodeType": "cache.r4.large",
"DataTiering": "disabled",
"CacheParameterGroup": {
"CacheNodeIdsToReboot": [],
"ParameterApplyStatus": "in-sync",
"CacheParameterGroupName": "default.redis3.2.cluster.on"
},
"SnapshotRetentionLimit": 0,
"EngineVersion": "3.2.6",
"CacheSecurityGroups": [],
"NumCacheNodes": 1
},
{
"SecurityGroups": [
{
"Status": "active",
"SecurityGroupId": "sg-dbe93fa2"
}
],
"ClientDownloadLandingPage": "https://console.aws.amazon.com/elasticache/home#client-download:",
"AuthTokenEnabled": true,
"CacheSubnetGroupName": "default",
"SnapshotWindow": "12:30-13:30",
"AutoMinorVersionUpgrade": true,
"CacheClusterCreateTime": "2018-02-26T21:17:01.439Z",
"CacheClusterStatus": "available",
"AtRestEncryptionEnabled": true,
"PreferredAvailabilityZone": "us-west-2a",
"TransitEncryptionEnabled": true,
"ReplicationGroupId": "my-cluster3",
"Engine": "redis",
"PreferredMaintenanceWindow": "thu:11:00-thu:12:00",
"CacheClusterId": "my-cluster3-0002-003",
"PendingModifiedValues": {},
"CacheNodeType": "cache.r4.large",
"DataTiering": "disabled",
"CacheParameterGroup": {
"CacheNodeIdsToReboot": [],
"ParameterApplyStatus": "in-sync",
"CacheParameterGroupName": "default.redis6.x.cluster.on"
},
"SnapshotRetentionLimit": 0,
"EngineVersion": "6.0",
"CacheSecurityGroups": [],
"NumCacheNodes": 1
}
]
}
```
In a case where the cluster is created using the AWS Management Console (cluster node enabled or disabled with 1 or more shards), use the following command to describe the cluster's details (replace *my-cluster* with the name of the replication group (name of your cluster):
```
aws elasticache describe-replication-groups --replication-group-id my-cluster
```
For more information, see the AWS CLI for ElastiCache topic [https://docs.aws.amazon.com/cli/latest/reference/elasticache/describe-cache-clusters.html](https://docs.aws.amazon.com/cli/latest/reference/elasticache/describe-cache-clusters.html).
## Viewing an ElastiCache cluster's details (ElastiCache API)
You can view the details for a cluster using the ElastiCache API `DescribeCacheClusters` action. If the `CacheClusterId` parameter is included, details for the specified cluster are returned. If the `CacheClusterId` parameter is omitted, details for up to `MaxRecords` (default 100) clusters are returned. The value for `MaxRecords` cannot be less than 20 or greater than 100.
The following code lists the details for `my-cluster`.
```
https://elasticache.us-west-2.amazonaws.com/
?Action=DescribeCacheClusters
&CacheClusterId=my-cluster
&Version=2015-02-02
&SignatureVersion=4
&SignatureMethod=HmacSHA256
&Timestamp=20150202T192317Z
&X-Amz-Credential=
```
The following code list the details for up to 25 clusters.
```
https://elasticache.us-west-2.amazonaws.com/
?Action=DescribeCacheClusters
&MaxRecords=25
&Version=2015-02-02
&SignatureVersion=4
&SignatureMethod=HmacSHA256
&Timestamp=20150202T192317Z
&X-Amz-Credential=
```
For more information, see the ElastiCache API reference topic [https://docs.aws.amazon.com/AmazonElastiCache/latest/APIReference/API_DescribeCacheClusters.html](https://docs.aws.amazon.com/AmazonElastiCache/latest/APIReference/API_DescribeCacheClusters.html).
# Modifying an ElastiCache cluster
In addition to adding or removing nodes from an ElastiCache cluster, there can be times where you need to make other changes such as adding a security group, changing the maintenance window or a parameter group.
We recommend that you have your maintenance window fall at the time of lowest usage. Thus it might need modification from time to time.
When you change a cluster's parameters, the change is applied to the cluster either immediately or after the cluster is restarted. This is true whether you change the cluster's parameter group itself or a parameter value within the cluster's parameter group. To determine when a particular parameter change is applied, see the **Changes Take Effect** section of the **Details** column in the tables for [Memcached specific parameters](ParameterGroups.Engine.md#ParameterGroups.Memcached) and [Valkey and Redis OSS parameters](ParameterGroups.Engine.md#ParameterGroups.Redis). For information on rebooting a cluster's nodes, see [Rebooting nodes](nodes.rebooting.md).
## Using the ElastiCache AWS Management Console
**To modify a cluster**
1. Sign in to the AWS Management Console and open the ElastiCache console at [ https://console.aws.amazon.com/elasticache/](https://console.aws.amazon.com/elasticache/).
1. From the list in the upper-right corner, choose the AWS Region where the cluster that you want to modify is located.
1. In the navigation pane, choose the engine running on the cluster that you want to modify.
A list of the chosen engine's clusters appears.
1. In the list of clusters, for the cluster that you want to modify, choose its name.
1. Choose **Actions** and then choose **Modify**.
The **Modify Cluster** window appears.
1. In the **Modify Cluster** window, make the modifications that you want. Options include:
+ Description
+ Cluster mode - To modify cluster mode from **Disabled** to **Enabled**, you must first set the cluster mode to **Compatible**.
Compatible mode allows your Valkey or Redis OSS clients to connect using both cluster mode enabled and cluster mode disabled. After you migrate all Valkey or Redis OSS clients to use cluster mode enabled, you can then complete cluster mode configuration and set the cluster mode to **Enabled**.
+ Engine Version Compatibility
**Important**
You can upgrade to newer engine versions. If you upgrade major engine versions, for example from 5.0.6 to 6.0, you need to select a parameter group family that is compatible with the new engine version. For more information on doing so, see [Version Management for ElastiCache](VersionManagement.md). However, you can't downgrade to older engine versions except by deleting the existing cluster and creating it again.
+ VPC Security Group(s)
+ Parameter Group
+ Node Type
**Note**
If the cluster is using a node type from the r6gd family, you can only choose a different node size from within that family. If you choose a node type from the r6gd family, data tiering will automatically be enabled. For more information, see [Data tiering](data-tiering.md).
+ Multi-AZ
+ Auto failover (cluster mode disabled only)
+ Enable Automatic Backups
+ Backup Node Id
+ Backup Retention Period
+ Backup Window
+ Topic for SNS Notification
+ Memcached Engine Version Compatibility
+ Network type
**Note**
If you are switching from IPv4 to IPv6, you must select or create subnet groups compatible with IPv6. For more information, see [Choosing a network type in ElastiCache](network-type.md).
+ VPC Security Group(s)
+ Parameter Group
+ Maintenance Window
+ Topic for SNS Notification
The **Apply Immediately** box applies only to engine version and node type modifications. To apply changes immediately, choose the **Apply Immediately** check box. If this box is not chosen, engine version modifications are applied during the next maintenance window. Other modifications, such as changing the maintenance window, are applied immediately.
**To enable/disable log delivery for Redis**
1. From the list of clusters, choose the cluster you want to modify. Choose the **Cluster name** and not the checkbox beside it.
1. On the **Cluster details** page, choose the **Logs** tab.
1. To enable or disable slow logs, choose either **Enable** or **Disable**.
If you choose enable:
1. Under **Log format**, choose either **JSON** or **Text**.
1. Under **Log destination type**, choose either **CloudWatch Logs** or **Kinesis Firehose**.
1. Under **Log destination**, you can choose **Create new** and enter either your CloudWatchLogs log group name or your Kinesis Data Firehose stream name. You can also choose **Select existing** and then choose either your CloudWatchLogs log group name or your Kinesis Data Firehose stream name.
1. Choose **Enable**.
**To change your configuration for Redis:**
1. Choose **Modify**.
1. Under **Log format**, choose either **JSON** or **Text**.
1. Under **Destination Type**, choose either **CloudWatch Logs** or **Kinesis Firehose**.
1. Under **Log destination**, choose either **Create new** and enter your CloudWatchLogs log group name or your Kinesis Data Firehose stream name. Or choose **Select existing** and then choose your CloudWatchLogs log group name or your Kinesis Data Firehose stream name.
## Using the AWS CLI with ElastiCache
You can modify an existing cluster using the AWS CLI `modify-cache-cluster` operation. To modify a cluster's configuration value, specify the cluster's ID, the parameter to change and the parameter's new value. The following example changes the maintenance window for a cluster named `my-cluster` and applies the change immediately.
**Important**
You can upgrade to newer Memcached engine versions. For more information on doing so, see [Version Management for ElastiCache](VersionManagement.md). However, you can't downgrade to older engine versions except by deleting the existing cluster and creating it again.
**Important**
You can upgrade to newer Valkey or Redis OSS engine versions. If you upgrade major engine versions, for example from Redis OSS 5.0.6 to Redis OSS 6.0, you need to select a parameter group family that is compatible with the new engine version. For more information on doing so, see [Version Management for ElastiCache](VersionManagement.md). However, you can't downgrade to older engine versions except by deleting the existing cluster and creating it again.
For Linux, macOS, or Unix:
```
aws elasticache modify-cache-cluster \
--cache-cluster-id my-cluster \
--preferred-maintenance-window sun:23:00-mon:02:00
```
For Windows:
```
aws elasticache modify-cache-cluster ^
--cache-cluster-id my-cluster ^
--preferred-maintenance-window sun:23:00-mon:02:00
```
The `--apply-immediately` parameter applies only to modifications in node type, engine version, and changing the number of nodes in a cluster. If you want to apply any of these changes immediately, use the `--apply-immediately` parameter. If you prefer postponing these changes to your next maintenance window, use the `--no-apply-immediately` parameter. Other modifications, such as changing the maintenance window, are applied immediately.
For more information, see the AWS CLI for ElastiCache topic [https://docs.aws.amazon.com/cli/latest/reference/elasticache/modify-cache-cluster.html](https://docs.aws.amazon.com/cli/latest/reference/elasticache/modify-cache-cluster.html).
## Using the ElastiCache API
You can modify an existing cluster using the ElastiCache API `ModifyCacheCluster` operation. To modify a cluster's configuration value, specify the cluster's ID, the parameter to change and the parameter's new value. The following example changes the maintenance window for a cluster named `my-cluster` and applies the change immediately.
**Important**
You can upgrade to newer Memcached engine versions. For more information on doing so, see [Version Management for ElastiCache](VersionManagement.md). However, you can't downgrade to older engine versions except by deleting the existing cluster and creating it again.
**Important**
You can upgrade to newer Valkey or Redis OSS engine versions. If you upgrade major engine versions, for example from Redis OSS 5.0.6 to Redis OSS 6.0, you need to select a parameter group family that is compatible with the new engine version. For more information on doing so, see [Version Management for ElastiCache](VersionManagement.md). However, you can't downgrade to older engine versions except by deleting the existing cluster and creating it again.
Line breaks are added for ease of reading.
```
https://elasticache.us-west-2.amazonaws.com/
?Action=ModifyCacheCluster
&CacheClusterId=my-cluster
&PreferredMaintenanceWindow=sun:23:00-mon:02:00
&SignatureVersion=4
&SignatureMethod=HmacSHA256
&Timestamp=20150901T220302Z
&X-Amz-Algorithm=&AWS;4-HMAC-SHA256
&X-Amz-Date=20150202T220302Z
&X-Amz-SignedHeaders=Host
&X-Amz-Expires=20150901T220302Z
&X-Amz-Credential=
&X-Amz-Signature=
```
The `ApplyImmediately` parameter applies only to modifications in node type, engine version, and changing the number of nodes in a cluster. If you want to apply any of these changes immediately, set the `ApplyImmediately` parameter to `true`. If you prefer postponing these changes to your next maintenance window, set the `ApplyImmediately` parameter to `false`. Other modifications, such as changing the maintenance window, are applied immediately.
For more information, see the ElastiCache API reference topic [https://docs.aws.amazon.com/AmazonElastiCache/latest/APIReference/API_ModifyCacheCluster.html](https://docs.aws.amazon.com/AmazonElastiCache/latest/APIReference/API_ModifyCacheCluster.html).
# Adding nodes to an ElastiCache cluster
Adding nodes to a Memcached cluster increases the number of your cluster's partitions. When you change the number of partitions in a cluster some of your key spaces need to be remapped so that they are mapped to the right node. Remapping key spaces temporarily increases the number of cache misses on the cluster. For more information, see [Configuring your ElastiCache client for efficient load balancing (Memcached)](BestPractices.LoadBalancing.md).
To reconfigure your Valkey or Redis OSS (cluster mode enabled) cluster, see [Scaling Valkey or Redis OSS (Cluster Mode Enabled) clusters](scaling-redis-cluster-mode-enabled.md)
You can use the ElastiCache Management Console, the AWS CLI or ElastiCache API to add nodes to your cluster.
## Using the ElastiCache AWS Management Console
If you want to add a node to a single-node Valkey or Redis OSS (cluster mode disabled) cluster (one without replication enabled), it's a two-step process: first add replication, and then add a replica node.
**Topics**
+ [To add replication to a Valkey or Redis OSS cluster with no shards](#AddReplication.CON)
+ [To add nodes to an ElastiCache cluster (console)](#AddNode.CON)
The following procedure adds replication to a single-node Valkey or Redis OSS that does not have replication enabled. When you add replication, the existing node becomes the primary node in the replication-enabled cluster. After replication is added, you can add up to 5 replica nodes to the cluster.
**To add replication to a Valkey or Redis OSS cluster with no shards**
1. Sign in to the AWS Management Console and open the ElastiCache console at [ https://console.aws.amazon.com/elasticache/](https://console.aws.amazon.com/elasticache/).
1. From the navigation pane, choose **Valkey clusters** or **Redis OSS clusters**.
A list of clusters running that engine is displayed.
1. Choose the name of a cluster, not the box to the left of the cluster's name, that you want to add nodes to.
The following is true of a Redis OSS cluster that does not have replication enabled:
+ It is running Redis OSS, not Clustered Redis OSS.
+ It has zero shards.
If the cluster has any shards, replication is already enabled on it and you can continue at [To add nodes to an ElastiCache cluster (console)](#AddNode.CON).
1. Choose **Add replication**.
1. In **Add Replication**, enter a description for this replication-enabled cluster.
1. Choose **Add**.
As soon as the cluster's status returns to *available* you can continue at the next procedure and add replicas to the cluster.
**To add nodes to an ElastiCache cluster (console)**
The following procedure can be used to add nodes to a cluster.
1. Sign in to the AWS Management Console and open the ElastiCache console at [ https://console.aws.amazon.com/elasticache/](https://console.aws.amazon.com/elasticache/).
1. In the navigation pane, choose the engine running on the cluster that you want to add nodes to.
A list of clusters running the chosen engine appears.
1. From the list of clusters, for the cluster that you want to add a node to, choose its name.
If your cluster is a Valkey or Redis OSS (cluster mode enabled) cluster, see [Scaling Valkey or Redis OSS (Cluster Mode Enabled) clusters](scaling-redis-cluster-mode-enabled.md).
If your cluster is a Valkey or Redis OSS (cluster mode disabled) cluster with zero shards, first complete the steps at [To add replication to a Valkey or Redis OSS cluster with no shards](#AddReplication.CON).
1. Choose **Add node**.
1. Complete the information requested in the **Add Node** dialog box.
1. Choose the **Apply Immediately - Yes** button to add this node immediately, or choose **No** to add this node during the cluster's next maintenance window.
**Impact of New Add and Remove Requests on Pending Requests**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonElastiCache/latest/dg/Clusters.AddNode.html)
To determine what operations are pending, choose the **Description** tab and check to see how many pending creations or deletions are shown. You cannot have both pending creations and pending deletions.
1. Choose the **Add** button.
After a few moments, the new nodes should appear in the nodes list with a status of **creating**. If they don't appear, refresh your browser page. When the node's status changes to *available* the new node is able to be used.
## Using the AWS CLI with ElastiCache
To add nodes to a cluster using the AWS CLI, use the AWS CLI operation `modify-cache-cluster` with the following parameters:
+ `--cache-cluster-id` The ID of the cluster that you want to add nodes to.
+ `--num-cache-nodes` The `--num-cache-nodes` parameter specifies the number of nodes that you want in this cluster after the modification is applied. To add nodes to this cluster, `--num-cache-nodes` must be greater than the current number of nodes in this cluster. If this value is less than the current number of nodes, ElastiCache expects the parameter `cache-node-ids-to-remove` and a list of nodes to remove from the cluster. For more information, see [Using the AWS CLI with ElastiCache](Clusters.DeleteNode.md#Clusters.DeleteNode.CLI).
+ `--apply-immediately` or `--no-apply-immediately` which specifies whether to add these nodes immediately or at the next maintenance window.
For Linux, macOS, or Unix:
```
aws elasticache modify-cache-cluster \
--cache-cluster-id my-cluster \
--num-cache-nodes 5 \
--apply-immediately
```
For Windows:
```
aws elasticache modify-cache-cluster ^
--cache-cluster-id my-cluster ^
--num-cache-nodes 5 ^
--apply-immediately
```
This operation produces output similar to the following (JSON format):
```
{
"CacheCluster": {
"Engine": "memcached",
"CacheParameterGroup": {
"CacheNodeIdsToReboot": [],
"CacheParameterGroupName": "default.memcached1.4",
"ParameterApplyStatus": "in-sync"
},
"CacheClusterId": "my-cluster",
"PreferredAvailabilityZone": "us-west-2b",
"ConfigurationEndpoint": {
"Port": 11211,
"Address": "rlh-mem000.7alc7bf-example.cfg.usw2.cache.amazonaws.com"
},
"CacheSecurityGroups": [],
"CacheClusterCreateTime": "2016-09-21T16:28:28.973Z",
"AutoMinorVersionUpgrade": true,
"CacheClusterStatus": "modifying",
"NumCacheNodes": 2,
"ClientDownloadLandingPage": "https://console.aws.amazon.com/elasticache/home#client-download:",
"SecurityGroups": [
{
"Status": "active",
"SecurityGroupId": "sg-dbe93fa2"
}
],
"CacheSubnetGroupName": "default",
"EngineVersion": "1.4.24",
"PendingModifiedValues": {
"NumCacheNodes": 5
},
"PreferredMaintenanceWindow": "sat:09:00-sat:10:00",
"CacheNodeType": "cache.m3.medium",
"DataTiering": "disabled",
}
}
```
For more information, see the AWS CLI topic [https://docs.aws.amazon.com/cli/latest/reference/elasticache/modify-cache-cluster.html](https://docs.aws.amazon.com/cli/latest/reference/elasticache/modify-cache-cluster.html).
## Using the AWS CLI with ElastiCache
If you want to add nodes to an existing Valkey or Redis OSS (cluster mode disabled) cluster that does not have replication enabled, you must first create the replication group specifying the existing cluster as the primary. For more information, see [Creating a replication group using an available Valkey or Redis OSS cluster (AWS CLI)](Replication.CreatingReplGroup.ExistingCluster.md#Replication.CreatingReplGroup.ExistingCluster.CLI). After the replication group is *available*, you can continue with the following process.
To add nodes to a cluster using the AWS CLI, use the AWS CLI operation `increase-replica-count` with the following parameters:
+ `--replication-group-id` The ID of the replicationn group that you want to add nodes to.
+ `--new-replica-count` specifies the number of nodes that you want in this replication group after the modification is applied. To add nodes to this cluster, `--new-replica-count` must be greater than the current number of nodes in this cluster.
+ `--apply-immediately` or `--no-apply-immediately` which specifies whether to add these nodes immediately or at the next maintenance window.
For Linux, macOS, or Unix:
```
aws elasticache increase-replica-count \
--replication-group-id my-replication-group \
--new-replica-count 4 \
--apply-immediately
```
For Windows:
```
aws elasticache increase-replica-count ^
--replication-group-id my-replication-group ^
--new-replica-count 4 ^
--apply-immediately
```
This operation produces output similar to the following (JSON format):
```
{
"ReplicationGroup": {
"ReplicationGroupId": "node-test",
"Description": "node-test",
"Status": "modifying",
"PendingModifiedValues": {},
"MemberClusters": [
"node-test-001",
"node-test-002",
"node-test-003",
"node-test-004",
"node-test-005"
],
"NodeGroups": [
{
"NodeGroupId": "0001",
"Status": "modifying",
"PrimaryEndpoint": {
"Address": "node-test.zzzzzz.ng.0001.usw2.cache.amazonaws.com",
"Port": 6379
},
"ReaderEndpoint": {
"Address": "node-test.zzzzzz.ng.0001.usw2.cache.amazonaws.com",
"Port": 6379
},
"NodeGroupMembers": [
{
"CacheClusterId": "node-test-001",
"CacheNodeId": "0001",
"ReadEndpoint": {
"Address": "node-test-001.zzzzzz.0001.usw2.cache.amazonaws.com",
"Port": 6379
},
"PreferredAvailabilityZone": "us-west-2a",
"CurrentRole": "primary"
},
{
"CacheClusterId": "node-test-002",
"CacheNodeId": "0001",
"ReadEndpoint": {
"Address": "node-test-002.zzzzzz.0001.usw2.cache.amazonaws.com",
"Port": 6379
},
"PreferredAvailabilityZone": "us-west-2c",
"CurrentRole": "replica"
},
{
"CacheClusterId": "node-test-003",
"CacheNodeId": "0001",
"ReadEndpoint": {
"Address": "node-test-003.zzzzzz.0001.usw2.cache.amazonaws.com",
"Port": 6379
},
"PreferredAvailabilityZone": "us-west-2b",
"CurrentRole": "replica"
}
]
}
],
"SnapshottingClusterId": "node-test-002",
"AutomaticFailover": "enabled",
"MultiAZ": "enabled",
"SnapshotRetentionLimit": 1,
"SnapshotWindow": "07:30-08:30",
"ClusterEnabled": false,
"CacheNodeType": "cache.r5.large",
"DataTiering": "disabled",
"TransitEncryptionEnabled": false,
"AtRestEncryptionEnabled": false,
"ARN": "arn:aws:elasticache:us-west-2:123456789012:replicationgroup:node-test"
}
}
```
For more information, see the AWS CLI topic [https://docs.aws.amazon.com/cli/latest/reference/elasticache/increase-replica-count.html](https://docs.aws.amazon.com/cli/latest/reference/elasticache/increase-replica-count.html).
## Using the ElastiCache API
If you want to add nodes to an existing Valkey or Redis OSS (cluster mode disabled) cluster that does not have replication enabled, you must first create the replication group specifying the existing cluster as the Primary. For more information, see [Adding replicas to a standalone Valkey or Redis OSS (Cluster Mode Disabled) cluster (ElastiCache API)](Replication.CreatingReplGroup.ExistingCluster.md#Replication.CreatingReplGroup.ExistingCluster.API). After the replication group is *available*, you can continue with the following process.
**To add nodes to a cluster (ElastiCache API)**
+ Call the `IncreaseReplicaCount` API operation with the following parameters:
+ `ReplicationGroupId` The ID of the cluster that you want to add nodes to.
+ `NewReplicaCount` The `NewReplicaCount` parameter specifies the number of nodes that you want in this cluster after the modification is applied. To add nodes to this cluster, `NewReplicaCount` must be greater than the current number of nodes in this cluster. If this value is less than the current number of nodes, use the `DecreaseReplicaCount` API with the number of nodes to remove from the cluster.
+ `ApplyImmediately` Specifies whether to add these nodes immediately or at the next maintenance window.
+ `Region` Specifies the AWS Region of the cluster that you want to add nodes to.
The following example shows a call to add nodes to a cluster.
**Example**
```
https://elasticache.us-west-2.amazonaws.com/
?Action=IncreaseReplicaCount
&ApplyImmediately=true
&NumCacheNodes=4
&ReplicationGroupId=my-replication-group
&Region=us-east-2
&Version=2014-12-01
&SignatureVersion=4
&SignatureMethod=HmacSHA256
&Timestamp=20141201T220302Z
&X-Amz-Algorithm=&AWS;4-HMAC-SHA256
&X-Amz-Date=20141201T220302Z
&X-Amz-SignedHeaders=Host
&X-Amz-Expires=20141201T220302Z
&X-Amz-Credential=
&X-Amz-Signature=
```
For more information, see ElastiCache API topic [https://docs.aws.amazon.com/AmazonElastiCache/latest/APIReference/API_IncreaseReplicaCount.html](https://docs.aws.amazon.com/AmazonElastiCache/latest/APIReference/API_IncreaseReplicaCount.html).
## Using the ElastiCache API
**To add nodes to a cluster (ElastiCache API)**
+ Call the `ModifyCacheCluster` API operation with the following parameters:
+ `CacheClusterId` The ID of the cluster that you want to add nodes to.
+ `NumCacheNodes` The `NumCachNodes` parameter specifies the number of nodes that you want in this cluster after the modification is applied. To add nodes to this cluster, `NumCacheNodes` must be greater than the current number of nodes in this cluster. If this value is less than the current number of nodes, ElastiCache expects the parameter `CacheNodeIdsToRemove` with a list of nodes to remove from the cluster (see [Using the ElastiCache API with Memcached](Clusters.DeleteNode.md#Clusters.DeleteNode.API)).
+ `ApplyImmediately` Specifies whether to add these nodes immediately or at the next maintenance window.
+ `Region` Specifies the AWS Region of the cluster that you want to add nodes to.
The following example shows a call to add nodes to a cluster.
**Example**
```
https://elasticache.us-west-2.amazonaws.com/
?Action=ModifyCacheCluster
&ApplyImmediately=true
&NumCacheNodes=5
&CacheClusterId=my-cluster
&Region=us-east-2
&Version=2014-12-01
&SignatureVersion=4
&SignatureMethod=HmacSHA256
&Timestamp=20141201T220302Z
&X-Amz-Algorithm=&AWS;4-HMAC-SHA256
&X-Amz-Date=20141201T220302Z
&X-Amz-SignedHeaders=Host
&X-Amz-Expires=20141201T220302Z
&X-Amz-Credential=
&X-Amz-Signature=
```
For more information, see ElastiCache API topic [https://docs.aws.amazon.com/AmazonElastiCache/latest/APIReference/API_ModifyCacheCluster.html](https://docs.aws.amazon.com/AmazonElastiCache/latest/APIReference/API_ModifyCacheCluster.html).
# Removing nodes from an ElastiCache cluster
You can delete a node from a Valkey, Memcached, or Redis OSS cluster using the AWS Management Console, the AWS CLI, or the ElastiCache API.
**Note**
Each time you change the number of nodes in a Memcached cluster, you must re-map at least some of your keyspace so it maps to the correct node. For more detailed information on load balancing a Memcached cluster, see [Configuring your ElastiCache client for efficient load balancing (Memcached)](BestPractices.LoadBalancing.md).
## Using the ElastiCache AWS Management Console
**To remove nodes from a cluster (console)**
1. Sign in to the AWS Management Console and open the ElastiCache console at [ https://console.aws.amazon.com/elasticache/](https://console.aws.amazon.com/elasticache/).
1. From the list in the upper-right corner, choose the AWS Region of the cluster that you want to remove nodes from.
1. In the navigation pane, choose the engine running on the cluster that you want to remove a node.
A list of clusters running the chosen engine appears.
1. From the list of clusters, choose the cluster name from which you want to remove a node.
A list of the cluster's nodes appears.
1. Choose the box to the left of the node ID for the node that you want to remove. Using the ElastiCache console, you can only delete one node at a time, so choosing multiple nodes means that you can't use the **Delete node** button.
The *Delete Node* page appears.
1. To delete the node, complete the **Delete Node** page and choose **Delete Node**. To keep the node, choose **Cancel**.
**Important**
With Valkey or Redis OSS, if you're deleting the node results in the cluster which are no longer Multi-AZ compliant, make sure to first clear the **Multi-AZ** check box and then delete the node. If you clear the **Multi-AZ** check box, you can choose to enable **Auto failover**.
**Impact of New Add and Remove Requests on Pending Requests**
| Scenarios | Pending Operation | New Request | Results |
| --- | --- | --- | --- |
| Scenario 1 | Delete | Delete | The new delete request, pending or immediate, replaces the pending delete request. For example, if nodes 0001, 0003, and 0007 are pending deletion and a new request to delete nodes 0002 and 0004 is issued, only nodes 0002 and 0004 will be deleted. Nodes 0001, 0003, and 0007 will not be deleted. |
| Scenario 2 | Delete | Create | The new create request, pending or immediate, replaces the pending delete request. For example, if nodes 0001, 0003, and 0007 are pending deletion and a new request to create a node is issued, a new node will be created and nodes 0001, 0003, and 0007 will not be deleted. |
| Scenario 3 | Create | Delete | The new delete request, pending or immediate, replaces the pending create request. For example, if there is a pending request to create two nodes and a new request is issued to delete node 0003, no new nodes will be created and node 0003 will be deleted. |
| Scenario 4 | Create | Create | The new create request is added to the pending create request. For example, if there is a pending request to create two nodes and a new request is issued to create three nodes, the new requests is added to the pending request and five nodes will be created. If the new create request is set to **Apply Immediately - Yes**, all create requests are performed immediately. If the new create request is set to **Apply Immediately - No**, all create requests are pending. |
To determine what operations are pending, choose the **Description** tab and check to see how many pending creations or deletions are shown. You cannot have both pending creations and pending deletions.
## Using the AWS CLI with ElastiCache
1. Identify the IDs of the nodes that you want to remove. For more information, see [Viewing an ElastiCache cluster's details](Clusters.ViewDetails.md).
1. Use the `decrease-replica-count` CLI operation with a list of the nodes to remove, as in the following example.
To remove nodes from a cluster using the command-line interface, use the command `decrease-replica-count` with the following parameters:
+ `--replication-group-id` The ID of the replication group that you want to remove nodes from.
+ `--new-replica-count` The `--new-replica-count` parameter specifies the number of nodes that you want in this cluster after the modification is applied.
+ `--replicas-to-remove` A list of node IDs that you want removed from this cluster.
+ `--apply-immediately` or `--no-apply-immediately` Specifies whether to remove these nodes immediately or at the next maintenance window.
+ `--region` Specifies the AWS Region of the cluster that you want to remove nodes from.
**Note**
You can pass only one of `--replicas-to-remove` or `--new-replica-count` parameters when calling this operation.
For Linux, macOS, or Unix:
```
aws elasticache decrease-replica-count \
--replication-group-id my-replication-group \
--new-replica-count 2 \
--region us-east-2 \
--apply-immediately
```
For Windows:
```
aws elasticache decrease-replica-count ^
--replication-group-id my-replication-group ^
--new-replica-count 3 ^
--region us-east-2 ^
--apply-immediately
```
This operation produces output similar to the following (JSON format):
```
{
"ReplicationGroup": {
"ReplicationGroupId": "node-test",
"Description": "node-test"
},
"Status": "modifying",
"PendingModifiedValues": {},
"MemberClusters": [
"node-test-001",
"node-test-002",
"node-test-003",
"node-test-004",
"node-test-005",
"node-test-006"
],
"NodeGroups": [
{
"NodeGroupId": "0001",
"Status": "modifying",
"PrimaryEndpoint": {
"Address": "node-test.zzzzzz.ng.0001.usw2.cache.amazonaws.com",
"Port": 6379
},
"ReaderEndpoint": {
"Address": "node-test-ro.zzzzzz.ng.0001.usw2.cache.amazonaws.com",
"Port": 6379
},
"NodeGroupMembers": [
{
"CacheClusterId": "node-test-001",
"CacheNodeId": "0001",
"ReadEndpoint": {
"Address": "node-test-001.zzzzzz.0001.usw2.cache.amazonaws.com",
"Port": 6379
},
"PreferredAvailabilityZone": "us-west-2a",
"CurrentRole": "primary"
},
{
"CacheClusterId": "node-test-002",
"CacheNodeId": "0001",
"ReadEndpoint": {
"Address": "node-test-002.zzzzzz.0001.usw2.cache.amazonaws.com",
"Port": 6379
},
"PreferredAvailabilityZone": "us-west-2c",
"CurrentRole": "replica"
},
{
"CacheClusterId": "node-test-003",
"CacheNodeId": "0001",
"ReadEndpoint": {
"Address": "node-test-003.zzzzzz.0001.usw2.cache.amazonaws.com",
"Port": 6379
},
"PreferredAvailabilityZone": "us-west-2b",
"CurrentRole": "replica"
},
{
"CacheClusterId": "node-test-004",
"CacheNodeId": "0001",
"ReadEndpoint": {
"Address": "node-test-004.zzzzzz.0001.usw2.cache.amazonaws.com",
"Port": 6379
},
"PreferredAvailabilityZone": "us-west-2c",
"CurrentRole": "replica"
},
{
"CacheClusterId": "node-test-005",
"CacheNodeId": "0001",
"ReadEndpoint": {
"Address": "node-test-005.zzzzzz.0001.usw2.cache.amazonaws.com",
"Port": 6379
},
"PreferredAvailabilityZone": "us-west-2b",
"CurrentRole": "replica"
},
{
"CacheClusterId": "node-test-006",
"CacheNodeId": "0001",
"ReadEndpoint": {
"Address": "node-test-006.zzzzzz.0001.usw2.cache.amazonaws.com",
"Port": 6379
},
"PreferredAvailabilityZone": "us-west-2b",
"CurrentRole": "replica"
}
]
}
],
"SnapshottingClusterId": "node-test-002",
"AutomaticFailover": "enabled",
"MultiAZ": "enabled",
"SnapshotRetentionLimit": 1,
"SnapshotWindow": "07:30-08:30",
"ClusterEnabled": false,
"CacheNodeType": "cache.r5.large",
"DataTiering": "disabled",
"TransitEncryptionEnabled": false,
"AtRestEncryptionEnabled": false,
"ARN": "arn:aws:elasticache:us-west-2:123456789012:replicationgroup:node-test"
}
}
```
Alternatively, you could call `decrease-replica-count` and instead of passing in the `--new-replica-count` parameter, you could pass the `--replicas-to-remove` parameter, as shown following:
For Linux, macOS, or Unix:
```
aws elasticache decrease-replica-count \
--replication-group-id my-replication-group \
--replicas-to-remove node-test-003 \
--region us-east-2 \
--apply-immediately
```
For Windows:
```
aws elasticache decrease-replica-count ^
--replication-group-id my-replication-group ^
--replicas-to-remove node-test-003 ^
--region us-east-2 ^
--apply-immediately
```
For more information, see the AWS CLI topics [https://docs.aws.amazon.com/cli/latest/reference/elasticache/decrease-replica-count.html](https://docs.aws.amazon.com/cli/latest/reference/elasticache/decrease-replica-count.html).
## Using the ElastiCache API with Valkey or Redis OSS
To remove nodes using the ElastiCache API, call the `DecreaseReplicaCount` API operation with the replication group Id and a list of nodes to remove, as shown:
+ `ReplicationGroupId` The ID of the replication group that you want to remove nodes from.
+ `ReplicasToRemove` The `ReplicasToRemove` parameter specifies the number of nodes that you want in this cluster after the modification is applied.
+ `ApplyImmediately` Specifies whether to remove these nodes immediately or at the next maintenance window.
+ `Region` Specifies the AWS Region of the cluster that you want to remove a node from.
The following example immediately removes nodes 0004 and 0005 from the cluster my-cluster.
```
https://elasticache.us-west-2.amazonaws.com/
?Action=DecreaseReplicaCount
&ReplicationGroupId=my-replication-group
&ApplyImmediately=true
&ReplicasToRemove=node-test-003
&Region us-east-2
&Version=2014-12-01
&SignatureVersion=4
&SignatureMethod=HmacSHA256
&Timestamp=20141201T220302Z
&X-Amz-Algorithm=&AWS;4-HMAC-SHA256
&X-Amz-Date=20141201T220302Z
&X-Amz-SignedHeaders=Host
&X-Amz-Expires=20141201T220302Z
&X-Amz-Credential=
&X-Amz-Signature=
```
For more information, see ElastiCache API topic [https://docs.aws.amazon.com/AmazonElastiCache/latest/APIReference/API_DecreaseReplicaCount.html](https://docs.aws.amazon.com/AmazonElastiCache/latest/APIReference/API_DecreaseReplicaCount.html).
## Using the ElastiCache API with Memcached
To remove nodes using the ElastiCache API, call the `ModifyCacheCluster` API operation with the cache cluster ID and a list of nodes to remove, as shown:
+ `CacheClusterId` The ID of the cluster that you want to remove nodes from.
+ `NumCacheNodes` The `NumCacheNodes` parameter specifies the number of nodes that you want in this cluster after the modification is applied.
+ `CacheNodeIdsToRemove.member.n` The list of node IDs to remove from the cluster.
+ `CacheNodeIdsToRemove.member.1=0004`
+ `CacheNodeIdsToRemove.member.1=0005`
+ `ApplyImmediately` Specifies whether to remove these nodes immediately or at the next maintenance window.
+ `Region` Specifies the AWS Region of the cluster that you want to remove a node from.
The following example immediately removes nodes 0004 and 0005 from the cluster my-cluster.
```
https://elasticache.us-west-2.amazonaws.com/
?Action=ModifyCacheCluster
&CacheClusterId=my-cluster
&ApplyImmediately=true
&CacheNodeIdsToRemove.member.1=0004
&CacheNodeIdsToRemove.member.2=0005
&NumCacheNodes=3
&Region us-east-2
&Version=2014-12-01
&SignatureVersion=4
&SignatureMethod=HmacSHA256
&Timestamp=20141201T220302Z
&X-Amz-Algorithm=&AWS;4-HMAC-SHA256
&X-Amz-Date=20141201T220302Z
&X-Amz-SignedHeaders=Host
&X-Amz-Expires=20141201T220302Z
&X-Amz-Credential=
&X-Amz-Signature=
```
For more information, see ElastiCache API topic [https://docs.aws.amazon.com/AmazonElastiCache/latest/APIReference/API_ModifyCacheCluster.html](https://docs.aws.amazon.com/AmazonElastiCache/latest/APIReference/API_ModifyCacheCluster.html).
# Canceling pending add or delete node operations in ElastiCache
If you elected to not apply an ElastiCache cluster change immediately, the operation has **pending** status until it is performed at your next maintenance window. You can cancel any pending add or delete operation.
To cancel a pending add or delete node operation with the AWS CLI, use the `modify-cache-cluster` command. Set `num-cache-nodes` equal to the current number of cache nodes in the cluster, and then add the `--apply-immediately` flag. This will override the pending change.
To cancel a pending node addition or deletion:
```
aws elasticache modify-cache-cluster
--cache-cluster-id
--num-cache-nodes
--apply-immediately
```
If it isn't clear whether any node additions or deletions are pending, you can confirm their status with the `describe-cache-clusters` command:
```
aws elasticache describe-cache-clusters
--cache-cluster-id
```
Any pending nodes should appear in the `PendingModifiedValues`output. For example:
```
"PendingModifiedValues": {
"NumCacheNodes": 3
},
```
# Deleting a cluster in ElastiCache
As long as an ElastiCache cluster is in the *available* state, you are being charged for it, whether or not you are actively using it. To stop incurring charges, delete the cluster.
**Warning**
When you delete an ElastiCache cluster, your manual snapshots are retained. You can also create a final snapshot before the cluster is deleted. Automatic cache snapshots are not retained.
## Using the AWS Management Console
The following procedure deletes a single cluster from your deployment. To delete multiple clusters, repeat the procedure for each cluster that you want to delete. You do not need to wait for one cluster to finish deleting before starting the procedure to delete another cluster.
**To delete a cluster**
1. Sign in to the AWS Management Console and open the Amazon ElastiCache console at [https://console.aws.amazon.com/elasticache/](https://console.aws.amazon.com/elasticache/).
1. In the ElastiCache engine dashboard, choose the engine that is running in the cluster that you want to delete.
A list of all clusters running that engine appears.
1. To choose the cluster to delete, choose the cluster's name from the list of clusters.
**Important**
You can only delete one cluster at a time from the ElastiCache console. Choosing multiple clusters disables the delete operation.
1. For **Actions**, choose **Delete**.
1. In the **Delete Cluster** confirmation screen, choose **Delete** to delete the cluster, or choose **Cancel** to keep the cluster.
If you chose **Delete**, the status of the cluster changes to *deleting*.
As soon as your cluster is no longer listed in the list of clusters, you stop incurring charges for it.
## Using the AWS CLI to delete an ElastiCache cluster
The following code deletes the ElastiCache cluster `my-cluster`.
```
aws elasticache delete-cache-cluster --cache-cluster-id my-cluster
```
The `delete-cache-cluster` CLI action only deletes one cluster. To delete multiple clusters, call `delete-cache-cluster` for each cache cluster that you want to delete. You do not need to wait for one cluster to finish deleting before deleting another.
For Linux, macOS, or Unix:
```
aws elasticache delete-cache-cluster \
--cache-cluster-id my-cluster \
--region us-east-2
```
For Windows:
```
aws elasticache delete-cache-cluster ^
--cache-cluster-id my-cluster ^
--region us-east-2
```
For more information, see the AWS CLI for ElastiCache topic [https://docs.aws.amazon.com/cli/latest/reference/elasticache/delete-cache-cluster.html](https://docs.aws.amazon.com/cli/latest/reference/elasticache/delete-cache-cluster.html).
## Using the ElastiCache API
The following code deletes the cluster `my-cluster`.
```
https://elasticache.us-west-2.amazonaws.com/
?Action=DeleteCacheCluster
&CacheClusterId=my-cluster
&Region us-east-2
&SignatureVersion=4
&SignatureMethod=HmacSHA256
&Timestamp=20150202T220302Z
&X-Amz-Algorithm=&AWS;4-HMAC-SHA256
&X-Amz-Date=20150202T220302Z
&X-Amz-SignedHeaders=Host
&X-Amz-Expires=20150202T220302Z
&X-Amz-Credential=
&X-Amz-Signature=
```
The `DeleteCacheCluster` API operation only deletes one cluster. To delete multiple clusters, call `DeleteCacheCluster` for each cluster that you want to delete. You do not need to wait for one cluster to finish deleting before deleting another.
For more information, see the ElastiCache API reference topic [https://docs.aws.amazon.com/AmazonElastiCache/latest/APIReference/API_DeleteCacheCluster.html](https://docs.aws.amazon.com/AmazonElastiCache/latest/APIReference/API_DeleteCacheCluster.html).
# Accessing your ElastiCache cluster or replication group
Your Amazon ElastiCache instances are designed to be accessed through an Amazon EC2 instance.
If you launched your ElastiCache instance in an Amazon Virtual Private Cloud (Amazon VPC), you can access your ElastiCache instance from an Amazon EC2 instance in the same Amazon VPC. Or, by using VPC peering, you can access your ElastiCache instance from an Amazon EC2 in a different Amazon VPC.
If you launched your ElastiCache instance in EC2 Classic, you allow the EC2 instance to access your cluster by granting the Amazon EC2 security group associated with the instance access to your cache security group. By default, access to a cluster is restricted to the account that launched the cluster.
**Topics**
+ [
## Grant access to your clusteror replication group
](#grant-access)
## Grant access to your clusteror replication group
### You launched your cluster into EC2-VPC
If you launched your cluster into an Amazon Virtual Private Cloud (Amazon VPC), you can connect to your ElastiCache cluster only from an Amazon EC2 instance that is running in the same Amazon VPC. In this case, you will need to grant network ingress to the cluster.
**Note**
If your are using *Local Zones*, make sure you have enabled it. For more information, see [Enable Local Zones](https://docs.aws.amazon.com//AWSEC2/latest/UserGuide/using-regions-availability-zones.html#opt-in-local-zone). By doing so, your VPC is extended to that Local Zone and your VPC will treat the subnet as any subnet in any other Availability Zone and relevant gateways, route tables and other security group considerations. will be automatically adjusted.
**To grant network ingress from an Amazon VPC security group to a cluster**
1. Sign in to the AWS Management Console and open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, under **Network & Security**, choose **Security Groups**.
1. From the list of security groups, choose the security group for your Amazon VPC. Unless you created a security group for ElastiCache use, this security group will be named *default*.
1. Choose the **Inbound** tab, and then do the following:
1. Choose **Edit**.
1. Choose **Add rule**.
1. In the **Type** column, choose **Custom TCP rule**.
1. In the **Port range** box, type the port number for your cluster node. This number must be the same one that you specified when you launched the cluster. The default port for Memcached is **11211** The default port for Valkey and Redis OSS is **6379**.
1. In the **Source** box, choose **Anywhere** which has the port range (0.0.0.0/0) so that any Amazon EC2 instance that you launch within your Amazon VPC can connect to your ElastiCache nodes.
**Important**
Opening up the ElastiCache cluster to 0.0.0.0/0 does not expose the cluster to the Internet because it has no public IP address and therefore cannot be accessed from outside the VPC. However, the default security group may be applied to other Amazon EC2 instances in the customer’s account, and those instances may have a public IP address. If they happen to be running something on the default port, then that service could be exposed unintentionally. Therefore, we recommend creating a VPC Security Group that will be used exclusively by ElastiCache. For more information, see [Custom Security Groups](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-network-security.html#creating-your-own-security-groups).
1. Choose **Save**.
When you launch an Amazon EC2 instance into your Amazon VPC, that instance will be able to connect to your ElastiCache cluster.
### Accessing ElastiCache resources from outside AWS
Amazon ElastiCache is an AWS service that provides cloud-based in-memory key-value store. The service is designed to be accessed exclusively from within AWS. However, if the ElastiCache cluster is hosted inside a VPC, you can use a Network Address Translation (NAT) instance to provide outside access.
#### Requirements
The following requirements must be met for you to access your ElastiCache resources from outside AWS:
+ The cluster must reside within a VPC and be accessed through a Network Address Translation (NAT) instance. There are no exceptions to this requirement.
+ The NAT instance must be launched in the same VPC as the cluster.
+ The NAT instance must be launched in a public subnet separate from the cluster.
+ An Elastic IP Address (EIP) must be associated with the NAT instance. The port forwarding feature of iptables is used to forward a port on the NAT instance to the cache node port within the VPC.
#### Considerations
The following considerations should be kept in mind when accessing your ElastiCache resources from outside ElastiCache.
+ Clients connect to the EIP and cache port of the NAT instance. Port forwarding on the NAT instance forwards traffic to the appropriate cluster node.
+ If a cluster node is added or replaced, the iptables rules need to be updated to reflect this change.
#### Limitations
This approach should be used for testing and development purposes only. It is not recommended for production use due to the following limitations:
+ The NAT instance is acting as a proxy between clients and multiple clusters. The addition of a proxy impacts the performance of the cluster. The impact increases with number of clusters you are accessing through the NAT instance.
+ The traffic from clients to the NAT instance is unencrypted. Therefore, you should avoid sending sensitive data via the NAT instance.
+ The NAT instance adds the overhead of maintaining another instance.
+ The NAT instance serves as a single point of failure. For information about how to set up high availability NAT on VPC, see [High Availability for Amazon VPC NAT Instances: An Example](https://aws.amazon.com/articles/2781451301784570).
#### How to access ElastiCache resources from outside AWS
The following procedure demonstrates how to connect to your ElastiCache resources using a NAT instance.
These steps assume the following:
+ `iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 6380 -j DNAT --to 10.0.1.231:6379`
+ `iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 6381 -j DNAT --to 10.0.1.232:6379`
Next you need NAT in the opposite direction:
`iptables -t nat -A POSTROUTING -o eth0 -j SNAT --to-source 10.0.0.55`
You also need to enable IP forwarding, which is disabled by default:
`sudo sed -i 's/net.ipv4.ip_forward=0/net.ipv4.ip_forward=1/g' /etc/sysctl.conf sudo sysctl --system`
+ You are accessing a Memcached cluster with:
+ IP address – *10.0.1.230*
+ Default Memcached port – *11211*
+ Security group – *\$110\$1.0\$1.0\$1.55\$1*
+ You are accessing a Valkey or Redis OSS cluster with:
+ IP address – *10.0.1.230*
+ Default port – *6379*
+ Security group – *sg-bd56b7da*
+ AWS instance IP address – *198.99.100.27*
+ Your trusted client has the IP address *198.51.100.27*.
+ Your NAT instance has the Elastic IP Address *203.0.113.73*.
+ Your NAT instance has security group *sg-ce56b7a9*.
**To connect to your ElastiCache resources using a NAT instance**
1. Create a NAT instance in the same VPC as your cluster but in a public subnet.
By default, the VPC wizard will launch a *cache.m1.small* node type. You should select a node size based on your needs. You must use EC2 NAT AMI to be able to access ElastiCache from outside AWS.
For information about creating a NAT instance, see [NAT Instances](https://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/VPC_NAT_Instance.html) in the AWS VPC User Guide.
1. Create security group rules for the cluster and NAT instance.
The NAT instance security group and the cluster instance should have the following rules:
+ Two inbound rules
+ With Memcached, the first rule is to allow TCP connections from trusted clients to each cache port forwarded from the NAT instance (11211 - 11213).
+ With Valkey and Redis OSS, the first rule is to allow TCP connections from trusted clients to each cache port forwarded from the NAT instance (6379 - 6381).
+ A second rule to allow SSH access to trusted clients.
**NAT instance security group - inbound rules with Memcached**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonElastiCache/latest/dg/accessing-elasticache.html)
**NAT instance security group - inbound rules with Valkey or Redis OSS**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonElastiCache/latest/dg/accessing-elasticache.html)
+ With Memcached, an outbound rule to allow TCP connections to cache port (11211).
**NAT instance security group - outbound rule**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonElastiCache/latest/dg/accessing-elasticache.html)
+ With Valkey or Redis OSS, an outbound rule to allow TCP connections to cache port (6379).
**NAT instance security group - outbound rule**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonElastiCache/latest/dg/accessing-elasticache.html)
+ With Memcached, an inbound rule for the cluster's security group that allows TCP connections from the NAT instance to the cache port (11211).
**Cluster instance security group - inbound rule**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonElastiCache/latest/dg/accessing-elasticache.html)
+ With Valkey or Redis OSS, an inbound rule for the cluster's security group that allows TCP connections from the NAT instance to the cache port (6379).
**Cluster instance security group - inbound rule**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonElastiCache/latest/dg/accessing-elasticache.html)
1. Validate the rules.
+ Confirm that the trusted client is able to SSH to the NAT instance.
+ Confirm that the trusted client is able to connect to the cluster from the NAT instance.
1. **Memcached**
Add an iptables rule to the NAT instance.
An iptables rule must be added to the NAT table for each node in the cluster to forward the cache port from the NAT instance to the cluster node. An example might look like the following:
```
iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 11211 -j DNAT --to 10.0.1.230:11211
```
The port number must be unique for each node in the cluster. For example, if working with a three node Memcached cluster using ports 11211 - 11213, the rules would look like the following:
```
iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 11211 -j DNAT --to 10.0.1.230:11211
iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 11212 -j DNAT --to 10.0.1.231:11211
iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 11213 -j DNAT --to 10.0.1.232:11211
```
Confirm that the trusted client is able to connect to the cluster.
The trusted client should connect to the EIP associated with the NAT instance and the cluster port corresponding to the appropriate cluster node. For example, the connection string for PHP might look like the following:
```
$memcached->connect( '203.0.113.73', 11211 );
$memcached->connect( '203.0.113.73', 11212 );
$memcached->connect( '203.0.113.73', 11213 );
```
A telnet client can also be used to verify the connection. For example:
```
telnet 203.0.113.73 11211
telnet 203.0.113.73 11212
telnet 203.0.113.73 11213
```
**Valkey or Redis OSS**
Add an iptables rule to the NAT instance.
An iptables rule must be added to the NAT table for each node in the cluster to forward the cache port from the NAT instance to the cluster node. An example might look like the following:
```
iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 6379 -j DNAT --to 10.0.1.230:6379
```
The port number must be unique for each node in the cluster. For example, if working with a three node Redis OSS cluster using ports 6379 - 6381, the rules would look like the following:
```
iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 6379 -j DNAT --to 10.0.1.230:6379
iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 6380 -j DNAT --to 10.0.1.231:6379
iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 6381 -j DNAT --to 10.0.1.232:6379
```
Confirm that the trusted client is able to connect to the cluster.
The trusted client should connect to the EIP associated with the NAT instance and the cluster port corresponding to the appropriate cluster node. For example, the connection string for PHP might look like the following:
```
redis->connect( '203.0.113.73', 6379 );
redis->connect( '203.0.113.73', 6380 );
redis->connect( '203.0.113.73', 6381 );
```
A telnet client can also be used to verify the connection. For example:
```
telnet 203.0.113.73 6379
telnet 203.0.113.73 6380
telnet 203.0.113.73 6381
```
1. Save the iptables configuration.
Save the rules after you test and verify them. If you are using a Redhat-based Linux distribution (like Amazon Linux), run the following command:
```
service iptables save
```
#### Related topics
The following topics may be of additional interest.
+ [Access Patterns for Accessing an ElastiCache Cache in an Amazon VPC](elasticache-vpc-accessing.md)
+ [Accessing an ElastiCache Cache from an Application Running in a Customer's Data Center](elasticache-vpc-accessing.md#elasticache-vpc-accessing-data-center)
+ [NAT Instances](https://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/VPC_NAT_Instance.html)
+ [Configuring ElastiCache Clients](ClientConfig.md)
+ [High Availability for Amazon VPC NAT Instances: An Example](https://aws.amazon.com/articles/2781451301784570)
# Finding connection endpoints in ElastiCache
Your application connects to your ElastiCache cluster using endpoints. An endpoint is a node or cluster's unique address.
You can also establish a private connection between your VPC and ElastiCache API endpoints by creating an interface VPC endpoint through AWS PrivateLink. For more information, see [ElastiCache API and interface VPC endpoints (AWS PrivateLink)](elasticache-privatelink.md).
**Which endpoints to use with Valkey or Redis OSS.**
+ For a **standalone node**, use the node's endpoint for both read and write operations.
+ For **Valkey or Redis OSS (cluster mode disabled) clusters**, use the *Primary Endpoint* for all write operations. Use the *Reader Endpoint* to evenly split incoming connections to the endpoint between all read replicas. Use the individual *Node Endpoints* for read operations (In the API/CLI these are referred to as Read Endpoints).
+ For **Valkey or Redis OSS (cluster mode enabled) clusters**, use the cluster's *Configuration Endpoint* for all operations that support cluster mode enabled commands. You must use a client that supports either Valkey Cluster, or Redis OSS Cluster on Redis OSS 3.2 and above. You can still read from individual node endpoints (In the API/CLI these are referred to as Read Endpoints).
The following sections guide you through discovering the endpoints you'll need for the engine you're running.
**Which endpoints to use with Memcached.**
For **ElastiCache serverless cache for Memcached**, simply acquire the cluster endpoint DNS and port from the console.
From the AWS CLI, use the `describe-serverless-caches` command to acquire the Endpoint information.
Linux
```
aws elasticache describe-serverless-caches --serverless-cache-name CacheName
```
Windows
```
aws elasticache describe-serverless-caches --serverless-cache-name CacheName
```
The output from the above operation should look something like this (JSON format):
```
{
"ServerlessCaches": [
{
"ServerlessCacheName": "serverless-memcached",
"Description": "test",
"CreateTime": 1697659642.136,
"Status": "available",
"Engine": "memcached",
"MajorEngineVersion": "1.6",
"FullEngineVersion": "21",
"SecurityGroupIds": [
"sg-083eda453e1e51310"
],
"Endpoint": {
"Address": "serverless-memcached-01.amazonaws.com",
"Port":11211
},
"ARN": "",
"SubnetIds": [
"subnet-0cf759df15bd4dc65",
"subnet-09e1307e8f1560d17"
],
"SnapshotRetentionLimit": 0,
"DailySnapshotTime": "03:00"
}
]
}
```
For an **instance based Memcached cluster**, if you use Automatic Discovery then you can use the cluster's *configuration endpoint* to configure your Memcached client. This means you must use a client that supports Automatic Discovery.
If you don't use Automatic Discovery, you must configure your client to use the individual node endpoints for reads and writes. You must also keep track of them as you add and remove nodes.
## Finding a Valkey or Redis OSS (Cluster Mode Disabled) Cluster's Endpoints (Console)
If a Valkey or Redis OSS (cluster mode disabled) cluster has only one node, the node's endpoint is used for both reads and writes. If a Valkey or Redis OSS (cluster mode disabled) cluster has multiple nodes, there are three types of endpoints; the *primary endpoint*, the *reader endpoint* and the *node endpoints*.
The primary endpoint is a DNS name that always resolves to the primary node in the cluster. The primary endpoint is immune to changes to your cluster, such as promoting a read replica to the primary role. For write activity, we recommend that your applications connect to the primary endpoint.
A reader endpoint will evenly split incoming connections to the endpoint between all read replicas in a ElastiCache for Redis OSS cluster. Additional factors such as when the application creates the connections or how the application (re)-uses the connections will determine the traffic distribution. Reader endpoints keep up with cluster changes in real-time as replicas are added or removed. You can place your ElastiCache for Redis OSS cluster’s multiple read replicas in different AWS Availability Zones (AZ) to ensure high availability of reader endpoints.
**Note**
A reader endpoint is not a load balancer. It is a DNS record that will resolve to an IP address of one of the replica nodes in a round robin fashion.
For read activity, applications can also connect to any node in the cluster. Unlike the primary endpoint, node endpoints resolve to specific endpoints. If you make a change in your cluster, such as adding or deleting a replica, you must update the node endpoints in your application.
**To find a Valkey or Redis OSS (cluster mode disabled) cluster's endpoints**
1. Sign in to the AWS Management Console and open the ElastiCache console at [ https://console.aws.amazon.com/elasticache/](https://console.aws.amazon.com/elasticache/).
1. From the navigation pane, choose **Valkey clusters** or **Redis OSS clusters**.
The clusters screen will appear with a list of Valkey or Redis OSS (cluster mode disabled) and Valkey or Redis OSS (cluster mode enabled) clusters.
1. To find the cluster's Primary and/or Reader endpoints, choose the cluster's name (not the button to its left).
![\[Image: Primary endpoint for a Valkey or Redis OSS (cluster mode disabled) cluster\]](http://docs.aws.amazon.com/AmazonElastiCache/latest/dg/images/Reader-Endpoint.png)
*Primary and Reader endpoints for a Valkey or Redis OSS (cluster mode disabled) cluster*
If there is only one node in the cluster, there is no primary endpoint and you can continue at the next step.
1. If the Valkey or Redis OSS (cluster mode disabled) cluster has replica nodes, you can find the cluster's replica node endpoints by choosing the cluster's name and then choosing the **Nodes** tab.
The nodes screen appears with each node in the cluster, primary and replicas, listed with its endpoint.
![\[Image: Node endpoints for a Valkey or Redis OSS (cluster mode disabled) cluster\]](http://docs.aws.amazon.com/AmazonElastiCache/latest/dg/images/ElastiCache-Endpoints-Redis-Node.png)
*Node endpoints for a Valkey or Redis OSS (cluster mode disabled) cluster*
1. To copy an endpoint to your clipboard:
1. One endpoint at a time, find the endpoint you want to copy.
1. Choose the copy icon directly in front of the endpoint.
The endpoint is now copied to your clipboard. For information on using the endpoint to connect to a node, see [Connecting to Memcached nodes](nodes-connecting.md#nodes-connecting.mem).
A Valkey or Redis OSS (cluster mode disabled) primary endpoint looks something like the following. There is a difference depending upon whether or not In-Transit encryption is enabled.
**In-transit encryption not enabled**
```
clusterName.xxxxxx.nodeId.regionAndAz.cache.amazonaws.com:port
redis-01.7abc2d.0001.usw2.cache.amazonaws.com:6379
```
**In-transit encryption enabled**
```
master.clusterName.xxxxxx.regionAndAz.cache.amazonaws.com:port
master.ncit.ameaqx.use1.cache.amazonaws.com:6379
```
## Finding Endpoints for a Valkey or Redis OSS (Cluster Mode Enabled) Cluster (Console)
A Valkey or Redis OSS (cluster mode enabled) cluster has a single configuration endpoint. By connecting to the configuration endpoint, your application is able to discover the primary and read endpoints for each shard in the cluster.
**To find a Valkey or Redis OSS (cluster mode enabled) cluster's endpoint**
1. Sign in to the AWS Management Console and open the ElastiCache console at [ https://console.aws.amazon.com/elasticache/](https://console.aws.amazon.com/elasticache/).
1. From the navigation pane, choose **Valkey clusters** or **Redis OSS clusters**.
The clusters screen will appear with a list of clusters. Choose the cluster you wish to connect to.
1. To find the cluster's Configuration endpoint, choose the cluster's name (not the radio button).
1. The **Configuration endpoint** is displayed under **Cluster details**. To copy it, choose the *copy* icon to the left of the endpoint.
## Finding a Cluster's Endpoints (Console) (Memcached)
All Memcached endpoints are read/write endpoints. To connect to nodes in a Memcached cluster your application can use either the endpoints for each node, or the cluster's configuration endpoint along with Automatic Discovery. To use Automatic Discovery you must use a client that supports Automatic Discovery.
When using Automatic Discovery, your client application connects to your Memcached cluster using the configuration endpoint. As you scale your cluster by adding or removing nodes, your application will automatically "know" all the nodes in the cluster and be able to connect to any of them. Without Automatic Discovery your application would have to do this, or you'd have to manually update endpoints in your application each time you added or removed a node.
To copy an endpoint, choose the copy icon directly in front of the endpoint address. For information on using the endpoint to connect to a node, see [Connecting to Memcached nodes](nodes-connecting.md#nodes-connecting.mem).
Configuration and node endpoints look very similar. The differences are highlighted with **bold** following.
```
myclustername.xxxxxx.cfg.usw2.cache.amazonaws.com:port # configuration endpoint contains "cfg"
myclustername.xxxxxx.0001.usw2.cache.amazonaws.com:port # node endpoint for node 0001
```
**Important**
If you choose to create a CNAME for your Memcached configuration endpoint, in order for your automatic discovery client to recognize the CNAME as a configuration endpoint, you must include `.cfg.` in the CNAME.
## Finding Endpoints (AWS CLI)
For Memcached, you can use the AWS CLI for Amazon ElastiCache to discover the endpoints for nodes and clusters.
For Redis OSS, you can use the AWS CLI for Amazon ElastiCache to discover the endpoints for nodes, clusters, and also replication groups.
**Topics**
+ [
### Finding Endpoints for Nodes and Clusters (AWS CLI)
](#Endpoints.Find.CLI.Nodes)
+ [
### Finding the Endpoints for Valkey or Redis OSS Replication Groups (AWS CLI)
](#Endpoints.Find.CLI.ReplGroups)
### Finding Endpoints for Nodes and Clusters (AWS CLI)
You can use the AWS CLI to discover the endpoints for a cluster and its nodes with the `describe-cache-clusters` command. For Valkey or Redis OSS clusters, the command returns the cluster endpoint. For Memcached clusters, the command returns the configuration endpoint. If you include the optional parameter `--show-cache-node-info`, the command will also return the endpoints of the individual nodes in the cluster.
**Example**
The following command retrieves the configuration endpoint (`ConfigurationEndpoint`) and individual node endpoints (`Endpoint`) for the Memcached cluster *mycluster*.
For Linux, macOS, or Unix:
```
aws elasticache describe-cache-clusters \
--cache-cluster-id mycluster \
--show-cache-node-info
```
For Windows:
```
aws elasticache describe-cache-clusters ^
--cache-cluster-id mycluster ^
--show-cache-node-info
```
Output from the above operation should look something like this (JSON format).
```
{
"CacheClusters": [
{
"Engine": "memcached",
"CacheNodes": [
{
"CacheNodeId": "0001",
"Endpoint": {
"Port": 11211,
"Address": "mycluster.amazonaws.com"
},
"CacheNodeStatus": "available",
"ParameterGroupStatus": "in-sync",
"CacheNodeCreateTime": "2016-09-22T21:30:29.967Z",
"CustomerAvailabilityZone": "us-west-2b"
},
{
"CacheNodeId": "0002",
"Endpoint": {
"Port": 11211,
"Address": "mycluster.amazonaws.com"
},
"CacheNodeStatus": "available",
"ParameterGroupStatus": "in-sync",
"CacheNodeCreateTime": "2016-09-22T21:30:29.967Z",
"CustomerAvailabilityZone": "us-west-2b"
},
{
"CacheNodeId": "0003",
"Endpoint": {
"Port": 11211,
"Address": "mycluster.amazonaws.com"
},
"CacheNodeStatus": "available",
"ParameterGroupStatus": "in-sync",
"CacheNodeCreateTime": "2016-09-22T21:30:29.967Z",
"CustomerAvailabilityZone": "us-west-2b"
}
],
"CacheParameterGroup": {
"CacheNodeIdsToReboot": [],
"CacheParameterGroupName": "default.memcached1.4",
"ParameterApplyStatus": "in-sync"
},
"CacheClusterId": "mycluster",
"PreferredAvailabilityZone": "us-west-2b",
"ConfigurationEndpoint": {
"Port": 11211,
"Address": "mycluster.amazonaws.com"
},
"CacheSecurityGroups": [],
"CacheClusterCreateTime": "2016-09-22T21:30:29.967Z",
"AutoMinorVersionUpgrade": true,
"CacheClusterStatus": "available",
"NumCacheNodes": 3,
"ClientDownloadLandingPage": "https://console.aws.amazon.com/elasticache/home#client-download:",
"CacheSubnetGroupName": "default",
"EngineVersion": "1.4.24",
"PendingModifiedValues": {},
"PreferredMaintenanceWindow": "mon:09:00-mon:10:00",
"CacheNodeType": "cache.m4.large",
"DataTiering": "disabled"
}
]
}
```
If you choose to create a CNAME for your Memcached configuration endpoint, in order for your auto discovery client to recognize the CNAME as a configuration endpoint, you must include `.cfg.` in the CNAME. For example, `mycluster.cfg.local` in your php.ini file for the `session.save_path` parameter.
**Example**
For Valkey and Redis OSS, the following command retrieves the cluster information for the single-node cluster *mycluster*.
The parameter `--cache-cluster-id` can be used with single-node Valkey or Redis OSS (cluster mode disabled) cluster id or specific node ids in replication groups. The `--cache-cluster-id` of a replication group is a 4-digit value such as `0001`. If `--cache-cluster-id` is the id of a cluster (node) in a replication group, the `replication-group-id` is included in the output.
For Linux, macOS, or Unix:
```
aws elasticache describe-cache-clusters \
--cache-cluster-id redis-cluster \
--show-cache-node-info
```
For Windows:
```
aws elasticache describe-cache-clusters ^
--cache-cluster-id redis-cluster ^
--show-cache-node-info
```
Output from the above operation should look something like this (JSON format).
```
{
"CacheClusters": [
{
"CacheClusterStatus": "available",
"SecurityGroups": [
{
"SecurityGroupId": "sg-77186e0d",
"Status": "active"
}
],
"CacheNodes": [
{
"CustomerAvailabilityZone": "us-east-1b",
"CacheNodeCreateTime": "2018-04-25T18:19:28.241Z",
"CacheNodeStatus": "available",
"CacheNodeId": "0001",
"Endpoint": {
"Address": "redis-cluster.amazonaws.com",
"Port": 6379
},
"ParameterGroupStatus": "in-sync"
}
],
"AtRestEncryptionEnabled": false,
"CacheClusterId": "redis-cluster",
"TransitEncryptionEnabled": false,
"CacheParameterGroup": {
"ParameterApplyStatus": "in-sync",
"CacheNodeIdsToReboot": [],
"CacheParameterGroupName": "default.redis3.2"
},
"NumCacheNodes": 1,
"PreferredAvailabilityZone": "us-east-1b",
"AutoMinorVersionUpgrade": true,
"Engine": "redis",
"AuthTokenEnabled": false,
"PendingModifiedValues": {},
"PreferredMaintenanceWindow": "tue:08:30-tue:09:30",
"CacheSecurityGroups": [],
"CacheSubnetGroupName": "default",
"CacheNodeType": "cache.t2.small",
"DataTiering": "disabled"
"EngineVersion": "3.2.10",
"ClientDownloadLandingPage": "https://console.aws.amazon.com/elasticache/home#client-download:",
"CacheClusterCreateTime": "2018-04-25T18:19:28.241Z"
}
]
}
```
For more information, see the topic [describe-cache-clusters](https://docs.aws.amazon.com/cli/latest/reference/elasticache/describe-cache-clusters.html).
### Finding the Endpoints for Valkey or Redis OSS Replication Groups (AWS CLI)
You can use the AWS CLI to discover the endpoints for a replication group and its clusters with the `describe-replication-groups` command. The command returns the replication group's primary endpoint and a list of all the clusters (nodes) in the replication group with their endpoints, along with the reader endpoint.
The following operation retrieves the primary endpoint and reader endpoint for the replication group `myreplgroup`. Use the primary endpoint for all write operations.
```
aws elasticache describe-replication-groups \
--replication-group-id myreplgroup
```
For Windows:
```
aws elasticache describe-replication-groups ^
--replication-group-id myreplgroup
```
Output from this operation should look something like this (JSON format).
```
{
"ReplicationGroups": [
{
"Status": "available",
"Description": "test",
"NodeGroups": [
{
"Status": "available",
"NodeGroupMembers": [
{
"CurrentRole": "primary",
"PreferredAvailabilityZone": "us-west-2a",
"CacheNodeId": "0001",
"ReadEndpoint": {
"Port": 6379,
"Address": "myreplgroup-001.amazonaws.com"
},
"CacheClusterId": "myreplgroup-001"
},
{
"CurrentRole": "replica",
"PreferredAvailabilityZone": "us-west-2b",
"CacheNodeId": "0001",
"ReadEndpoint": {
"Port": 6379,
"Address": "myreplgroup-002.amazonaws.com"
},
"CacheClusterId": "myreplgroup-002"
},
{
"CurrentRole": "replica",
"PreferredAvailabilityZone": "us-west-2c",
"CacheNodeId": "0001",
"ReadEndpoint": {
"Port": 6379,
"Address": "myreplgroup-003.amazonaws.com"
},
"CacheClusterId": "myreplgroup-003"
}
],
"NodeGroupId": "0001",
"PrimaryEndpoint": {
"Port": 6379,
"Address": "myreplgroup.amazonaws.com"
},
"ReaderEndpoint": {
"Port": 6379,
"Address": "myreplgroup-ro.amazonaws.com"
}
}
],
"ReplicationGroupId": "myreplgroup",
"AutomaticFailover": "enabled",
"SnapshottingClusterId": "myreplgroup-002",
"MemberClusters": [
"myreplgroup-001",
"myreplgroup-002",
"myreplgroup-003"
],
"PendingModifiedValues": {}
}
]
}
```
For more information, see [describe-replication-groups](https://docs.aws.amazon.com/cli/latest/reference/elasticache/describe-replication-groups.html) in the *AWS CLI Command Reference*.
## Finding Endpoints (ElastiCache API)
For Memcached, you can use the Amazon ElastiCache API to discover the endpoints for nodes and clusters.
For Redis OSS, you can use the Amazon ElastiCache API to discover the endpoints for nodes, clusters, and also replication groups.
**Topics**
+ [
### Finding Endpoints for Nodes and Clusters (ElastiCache API)
](#Endpoints.Find.API.Nodes)
+ [
### Finding Endpoints for Valkey or Redis OSS Replication Groups (ElastiCache API)
](#Endpoints.Find.API.ReplGroups)
### Finding Endpoints for Nodes and Clusters (ElastiCache API)
You can use the ElastiCache API to discover the endpoints for a cluster and its nodes with the `DescribeCacheClusters` action. For Valkey or Redis OSS clusters, the command returns the cluster endpoint. For Memcached clusters, the command returns the configuration endpoint. If you include the optional parameter `ShowCacheNodeInfo`, the action also returns the endpoints of the individual nodes in the cluster.
**Example**
For Memcached, the following command retrieves the configuration endpoint (`ConfigurationEndpoint`) and individual node endpoints (`Endpoint`) for the Memcached cluster *mycluster*.
```
https://elasticache.us-west-2.amazonaws.com/
?Action=DescribeCacheClusters
&CacheClusterId=mycluster
&ShowCacheNodeInfo=true
&SignatureVersion=4
&SignatureMethod=HmacSHA256
&Timestamp=20150202T192317Z
&Version=2015-02-02
&X-Amz-Credential=
```
If you choose to create a CNAME for your Memcached configuration endpoint, in order for your auto discovery client to recognize the CNAME as a configuration endpoint, you must include `.cfg.` in the CNAME. For example, `mycluster.cfg.local` in your php.ini file for the `session.save_path` parameter.
### Finding Endpoints for Valkey or Redis OSS Replication Groups (ElastiCache API)
You can use the ElastiCache API to discover the endpoints for a replication group and its clusters with the `DescribeReplicationGroups` action. The action returns the replication group's primary endpoint and a list of all the clusters in the replication group with their endpoints, along with the reader endpoint.
The following operation retrieves the primary endpoint (PrimaryEndpoint), reader endpoint (ReaderEndpoint) and individual node endpoints (ReadEndpoint) for the replication group `myreplgroup`. Use the primary endpoint for all write operations.
```
https://elasticache.us-west-2.amazonaws.com/
?Action=DescribeReplicationGroups
&ReplicationGroupId=myreplgroup
&SignatureVersion=4
&SignatureMethod=HmacSHA256
&Timestamp=20150202T192317Z
&Version=2015-02-02
&X-Amz-Credential=
```
For more information, see [DescribeReplicationGroups](https://docs.aws.amazon.com/AmazonElastiCache/latest/APIReference/API_DescribeReplicationGroups.html).
# Working with shards in ElastiCache
A shard (API/CLI: node group) is a collection of one to six ElastiCache for Valkey or Redis OSS nodes. A Valkey or Redis OSS (cluster mode disabled) cluster will never have more than one shard. With shards, you can separate large databases into smaller, faster, and more easily managed parts called data shards. This can increase database efficiency by distributing operations across multiple separate sections. Using shards can offer many benefits including improved performance, scalability, and cost efficiency.
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 cluster's data is partitioned across the cluster's shards. If there is more than one node in a shard, the shard implements replication with one node being the read/write primary node and the other nodes read-only replica nodes.
The node or shard limit can be increased to a maximum of 500 per cluster if the engine version is Valkey 7.2 and higher, or Redis OSS 5.0.6 to 7.1. 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. For more information, see [Creating a subnet group](SubnetGroups.Creating.md).
For versions below 5.0.6, the limit is 250 per cluster.
To request a limit increase, see [AWS service limits](https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html) and choose the limit type **Nodes per cluster per instance type**.
When you create a Valkey or Redis OSS (cluster mode enabled) cluster using the ElastiCache console, you specify the number of shards in the cluster and the number of nodes in the shards. For more information, see [Creating a Valkey or Redis OSS (cluster mode enabled) cluster (Console)](Clusters.Create.md#Clusters.Create.CON.RedisCluster). If you use the ElastiCache API or AWS CLI to create a cluster (called *replication group* in the API/CLI), you can configure the number of nodes in a shard (API/CLI: node group) independently. For more information, see the following:
+ API: [CreateReplicationGroup](https://docs.aws.amazon.com/AmazonElastiCache/latest/APIReference/API_CreateReplicationGroup.html)
+ CLI: [create-replication-group](https://docs.aws.amazon.com/cli/latest/reference/elasticache/create-replication-group.html)
Each node in a shard has the same compute, storage and memory specifications. The ElastiCache API lets you control shard-wide attributes, such as the number of nodes, security settings, and system maintenance windows.
![\[Image: Valkey or Redis OSS shard configurations.\]](http://docs.aws.amazon.com/AmazonElastiCache/latest/dg/images/ElastiCacheClusters-CSN-RedisShards.png)
*Valkey or Redis OSS shard configurations*
For more information, see [Offline resharding for Valkey or Redis OSS (cluster mode enabled)](scaling-redis-cluster-mode-enabled.md#redis-cluster-resharding-offline) and [Online resharding for Valkey or Redis OSS (cluster mode enabled)](scaling-redis-cluster-mode-enabled.md#redis-cluster-resharding-online).
## Finding a shard's ID
You can find a shard's ID using the AWS Management Console, the AWS CLI or the ElastiCache API.
### Using the AWS Management Console
**Topics**
+ [
#### For Valkey or Redis OSS (Cluster Mode Disabled)
](#shard-find-id-con-classic)
+ [
#### For Valkey or Redis OSS (Cluster Mode Enabled)
](#shard-find-id-con-cluster)
#### For Valkey or Redis OSS (Cluster Mode Disabled)
Valkey or Redis OSS (cluster mode disabled) replication group shard IDs are always `0001`.
#### For Valkey or Redis OSS (Cluster Mode Enabled)
The following procedure uses the AWS Management Console to find a Valkey or Redis OSS (cluster mode enabled)'s replication group's shard ID.
**To find the shard ID in a Valkey or Redis OSS (cluster mode enabled) replication group**
1. Sign in to the AWS Management Console and open the ElastiCache console at [ https://console.aws.amazon.com/elasticache/](https://console.aws.amazon.com/elasticache/).
1. On the navigation pane, choose **Valkey** or **Redis OSS**, then choose the name of the Valkey or Redis OSS (cluster mode enabled) replication group you want to find the shard IDs for.
1. In the **Shard Name** column, the shard ID is the last four digits of the shard name.
### Using the AWS CLI
To find shard (node group) ids for either Valkey or Redis OSS (cluster mode disabled) or Valkey or Redis OSS (cluster mode enabled) replication groups use the AWS CLI operation `describe-replication-groups` with the following optional parameter.
+ **`--replication-group-id`**—An optional parameter which when used limits the output to the details of the specified replication group. If this parameter is omitted, the details of up to 100 replication groups is returned.
**Example**
This command returns the details for `sample-repl-group`.
For Linux, macOS, or Unix:
```
aws elasticache describe-replication-groups \
--replication-group-id sample-repl-group
```
For Windows:
```
aws elasticache describe-replication-groups ^
--replication-group-id sample-repl-group
```
Output from this command looks something like this. The shard (node group) ids are *highlighted* here to make finding them easier.
```
{
"ReplicationGroups": [
{
"Status": "available",
"Description": "2 shards, 2 nodes (1 + 1 replica)",
"NodeGroups": [
{
"Status": "available",
"Slots": "0-8191",
"NodeGroupId": "0001",
"NodeGroupMembers": [
{
"PreferredAvailabilityZone": "us-west-2c",
"CacheNodeId": "0001",
"CacheClusterId": "sample-repl-group-0001-001"
},
{
"PreferredAvailabilityZone": "us-west-2a",
"CacheNodeId": "0001",
"CacheClusterId": "sample-repl-group-0001-002"
}
]
},
{
"Status": "available",
"Slots": "8192-16383",
"NodeGroupId": "0002",
"NodeGroupMembers": [
{
"PreferredAvailabilityZone": "us-west-2b",
"CacheNodeId": "0001",
"CacheClusterId": "sample-repl-group-0002-001"
},
{
"PreferredAvailabilityZone": "us-west-2a",
"CacheNodeId": "0001",
"CacheClusterId": "sample-repl-group-0002-002"
}
]
}
],
"ConfigurationEndpoint": {
"Port": 6379,
"Address": "sample-repl-group.9dcv5r.clustercfg.usw2.cache.amazonaws.com"
},
"ClusterEnabled": true,
"ReplicationGroupId": "sample-repl-group",
"SnapshotRetentionLimit": 1,
"AutomaticFailover": "enabled",
"SnapshotWindow": "13:00-14:00",
"MemberClusters": [
"sample-repl-group-0001-001",
"sample-repl-group-0001-002",
"sample-repl-group-0002-001",
"sample-repl-group-0002-002"
],
"CacheNodeType": "cache.m3.medium",
"DataTiering": "disabled",
"PendingModifiedValues": {}
}
]
}
```
### Using the ElastiCache API
To find shard (node group) ids for either Valkey or Redis OSS (cluster mode disabled) or Valkey or Redis OSS (cluster mode enabled) replication groups use the AWS CLI operation `describe-replication-groups` with the following optional parameter.
+ **`ReplicationGroupId`**—An optional parameter which when used limits the output to the details of the specified replication group. If this parameter is omitted, the details of up to *xxx* replication groups is returned.
**Example**
This command returns the details for `sample-repl-group`.
For Linux, macOS, or Unix:
```
https://elasticache.us-west-2.amazonaws.com/
?Action=DescribeReplicationGroup
&ReplicationGroupId=sample-repl-group
&Version=2015-02-02
&SignatureVersion=4
&SignatureMethod=HmacSHA256
&Timestamp=20150202T192317Z
&X-Amz-Credential=
```