Menu
Amazon ElastiCache for Redis
ElastiCache for Redis User Guide (API Version 2015-02-02)

Finding Connection Endpoints

Your application connects to your cluster using endpoints. An endpoint is a node or cluster's unique address.

Which endpoints to use

  • Redis standalone node, use the node's endpoint for both read and write operations.

     

  • Redis (cluster mode disabled) clusters, use the Primary Endpoint for all write operations. Use the individual Node Endpoints for read operations (In the API/CLI these are referred to as Read Endpoints).

     

  • Redis (cluster mode enabled) clusters, use the cluster's Configuration Endpoint for all operations. You must use a client that supports Redis Cluster (Redis 3.2). 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.

Finding a Redis (cluster mode disabled) Cluster's Endpoints (Console)

If a Redis (cluster mode disabled) cluster has only one node, the node's endpoint is used for both reads and writes. If a Redis (cluster mode disabled) cluster has multiple nodes, there are two types of endpoints, the Primary endpoint which always points to whichever node is serving as Primary, and the node endpoints. The Primary endpoint is used for writes. The node endpoints are used for reads.

To find a Redis (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/.

  2. From the navigation pane, choose Redis.

    The clusters screen will appear with a list of Redis (cluster mode disabled) and Redis (cluster mode enabled) clusters.

  3. To find the cluster's Primary endpoint, choose the box to the left of cluster's name.

    If there is only one node in the cluster, there is no primary endpoint and you can continue at the next step.

    Image: Primary endpoint for a Redis (cluster mode disabled) cluster

    Primary endpoint for a Redis (cluster mode disabled) cluster

  4. If the Redis (cluster mode disabled) cluster has replica nodes, you can find the cluster's replica node endpoints by choosing the cluster's name.

    The nodes screen appears with each node in the cluster, primary and replicas, listed with its endpoint.

    Image: Node endpoints for a Redis (cluster mode disabled) cluster

    Node endpoints for a Redis (cluster mode disabled) cluster

  5. To copy an endpoint to your clipboard:

    1. One endpoint at a time, find then highlight the endpoint you want to copy.

    2. Right-click the highlighted endpoint, then choose Copy from the context menu.

    The highlighted endpoint is now copied to your clipboard.

A Redis (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 a Redis (cluster mode enabled) Cluster's Endpoints (Console)

Use the Configuration Endpoint for both read and write operations. Redis determines which of the cluster's node to access.

The following procedure demonstrates how to find and copy Redis (cluster mode enabled) cluster endpoints.

To find the configuration endpoint for a Redis (cluster mode enabled) cluster

  1. Sign in to the AWS Management Console and open the ElastiCache console at https://console.aws.amazon.com/elasticache/.

  2. From the navigation pane, choose Redis.

    A list of clusters running any version of Redis appears.

  3. From the list of clusters, choose the box to the left of a cluster running "Clustered Redis".

    The screen expands showing details about the selected cluster.

  4. Locate the Configuration endpoint.

    Image: Configuration endpoint for a Redis (cluster mode enabled) cluster

    Configuration endpoint for a Redis (cluster mode enabled) cluster

To find the node endpoints for a Redis (cluster mode enabled) cluster

  1. Sign in to the AWS Management Console and open the ElastiCache console at https://console.aws.amazon.com/elasticache/.

  2. From the navigation pane, choose Redis.

    A list of clusters running any version of Redis appears.

  3. From the list of clusters, choose the cluster name of a cluster running "Clustered Redis".

    The shards page opens.

  4. Choose the name of the shard you want node endpoint for.

    A list of the shard's nodes appears with each node's endpoint.

  5. Locate the Endpoint column and read the endpoint for each node.

    Image: Node endpoints for a Redis (cluster mode enabled) cluster

    Node endpoints for a Redis (cluster mode enabled) cluster

To copy an endpoint to your clipboard

  1. Find the endpoint you want to copy using one of the preceeding procedures.

  2. Highlight the endpoint that you want to copy.

  3. Right-click the highlighted endpoint and choose Copy from the context menu.

    The highlighted endpoint is now copied to your clipboard.

A Redis (cluster mode enabled) configuration endpoint looks something like the following.

In-transit encryption not enabled

clusterName.xxxxxx.regionAndAz.cache.amazonaws.com:port rce.ameaqx.use1.cache.amazonaws.com:6379

In-transit encryption enabled

clustercfg.clusterName.xxxxxx.regionAndAz.cache.amazonaws.com:port clustercfg.rce.ameaqx.use1.cache.amazonaws.com:6379

Finding Endpoints (AWS CLI)

You can use the AWS CLI for Amazon ElastiCache to discover the endpoints for nodes, clusters, and replication groups.

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 Redis clusters, the command returns the cluster 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.

The following command retrieves the clusster information for the single-node Redis (cluster mode disabled) cluster mycluster.

Important

The parameter --cache-cluster-id can be used with single-node Redis (cluster mode disabled) cluster id or specific node ids in Redis replication groups. The --cache-cluster-id of a Redis replication group is a 4-digit value such as 0001. If --cache-cluster-id is the id of a cluster (node) in a Redis 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.ameaqx.0001.use1.cache.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", "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.

Finding the Endpoints for 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.

The following operation retrieves the primary endpoint (PrimaryEndpoint) and individual node endpoints (ReadEndpoint) for the replication group myreplgroup. Use the primary endpoint for all write operations and the individual node endpoints for all read operations.

For Linux, macOS, or Unix:

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.1abc4d.0001.usw2.cache.amazonaws.com" }, "CacheClusterId": "myreplgroup-001" }, { "CurrentRole": "replica", "PreferredAvailabilityZone": "us-west-2b", "CacheNodeId": "0001", "ReadEndpoint": { "Port": 6379, "Address": "myreplgroup-002.1abc4d.0001.usw2.cache.amazonaws.com" }, "CacheClusterId": "myreplgroup-002" }, { "CurrentRole": "replica", "PreferredAvailabilityZone": "us-west-2c", "CacheNodeId": "0001", "ReadEndpoint": { "Port": 6379, "Address": "myreplgroup-003.1abc4d.0001.usw2.cache.amazonaws.com" }, "CacheClusterId": "myreplgroup-003" } ], "NodeGroupId": "0001", "PrimaryEndpoint": { "Port": 6379, "Address": "myreplgroup.1abc4d.ng.0001.usw2.cache.amazonaws.com" } } ], "ReplicationGroupId": "myreplgroup", "AutomaticFailover": "enabled", "SnapshottingClusterId": "myreplgroup-002", "MemberClusters": [ "myreplgroup-001", "myreplgroup-002", "myreplgroup-003" ], "PendingModifiedValues": {} } ] }

For more information, see describe-replication-groups in the AWS CLI Command Reference.

Finding Endpoints (ElastiCache API)

You can use the Amazon ElastiCache API to discover the endpoints for nodes, clusters, and replication groups.

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 Redis clusters, the command returns the cluster endpoint. If you include the optional parameter ShowCacheNodeInfo, the action also returns the endpoints of the individual nodes in the cluster.

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=<credential>

Finding Endpoints for 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.

The following operation retrieves the primary endpoint (PrimaryEndpoint) and individual node endpoints (ReadEndpoint) for the replication group myreplgroup. Use the primary endpoint for all write operations and the individual node endpoints for all read 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=<credential>

For more information, see DescribeReplicationGroups.