# 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.