/amazon-elasticache

Connectivity Diagnostics for ElastiCache

Decision-tree diagnostic for "I can't connect to my cache." Work through steps in order; fix at the step where it fails.

Step 0: Are You in the VPC?

ElastiCache has no public endpoints. Determine where the client runs before diagnosing.

Tunnel setup:

python3 scripts/find_tunnel_host.py --vpc-id <vpc-id> --region <region>
python3 scripts/start_tunnel.py --instance-id <id> --cache-host <endpoint> --region <region>
python3 scripts/test_connection.py 127.0.0.1 --port 6379 --tunnel-mode --server-name <endpoint>

If tunnel fails: check SSM agent status, AmazonSSMManagedInstanceCore policy, and routes to SSM endpoints (NAT or VPC endpoints for ssm, ssmmessages, ec2messages).

Step 1: DNS Resolution

Retrieve the correct endpoint:

# Serverless
aws elasticache describe-serverless-caches --serverless-cache-name <name> \
  --query 'ServerlessCaches[0].Endpoint'

# Node-based (cluster-mode enabled) -- uses ConfigurationEndpoint
aws elasticache describe-replication-groups --replication-group-id <name> \
  --query 'ReplicationGroups[0].ConfigurationEndpoint'

# Node-based (cluster-mode disabled) -- uses NodeGroups[0].PrimaryEndpoint
aws elasticache describe-replication-groups --replication-group-id <name> \
  --query 'ReplicationGroups[0].NodeGroups[0].PrimaryEndpoint'

Note: ConfigurationEndpoint is null for cluster-mode-disabled clusters. Use PrimaryEndpoint and ReaderEndpoint from NodeGroups[0] instead.

Common mistakes:

• Using ConfigurationEndpoint for cluster-mode-disabled clusters (it will be null)
• Using a node endpoint instead of the configuration endpoint for cluster-mode-enabled caches
• Including the port in the hostname (endpoint:6379 instead of just endpoint)

If DNS times out: verify VPC has enableDnsSupport and enableDnsHostnames set to true.

Step 2: TCP / Port Reachability

Serverless caches need both ports open: 6379 (primary) AND 6380 (reader) in the security group.

Find the cache's security group:

aws elasticache describe-serverless-caches \
  --serverless-cache-name <name> \
  --query 'ServerlessCaches[0].SecurityGroupIds'

Failure causes:

• Timeout: security group inbound rule missing for TCP 6379 (and 6380 for serverless) from client's SG or CIDR
• Refused: cache not in available status, or wrong port
• Lambda: must have VPC attachment. Verify with aws lambda get-function-configuration --function-name <name> --query 'VpcConfig'

Step 3: TLS Handshake

Serverless always requires TLS. Node-based requires TLS only if created with --transit-encryption-enabled, or if TLS was enabled later via the preferred→required migration path (available for Redis OSS 7.0+/Valkey 7.2+).

ElastiCache-specific failures:

Step 4: Authentication

Test with CLI:

# RBAC with password
valkey-cli -h <endpoint> -p 6379 --tls --user <username> --pass <password> PING

# IAM auth -- generate token via Python (no CLI equivalent exists)
# python3 -c "
# import boto3; from botocore.signers import RequestSigner; from botocore.model import ServiceId
# s = boto3.Session(); c = s.get_credentials().get_frozen_credentials()
# sr = RequestSigner(ServiceId('elasticache'), '<region>', 'elasticache', 'v4', c, s._session.get_component('event_emitter'))
# For serverless caches, add ResourceType=ServerlessCache:
# url = sr.generate_presigned_url({'method':'GET','url':'https://<endpoint>/?Action=connect&User=<user-id>&ResourceType=ServerlessCache','body':{},'headers':{},'context':{}}, operation_name='connect', expires_in=900, region_name='<region>')
# For node-based caches, omit ResourceType:
# url = sr.generate_presigned_url({'method':'GET','url':'https://<endpoint>/?Action=connect&User=<user-id>','body':{},'headers':{},'context':{}}, operation_name='connect', expires_in=900, region_name='<region>')
# print(url[len('https://'):])
# "
# Then pass the output as TOKEN:
valkey-cli -h <endpoint> -p 6379 --tls --user <user-id> --pass "$TOKEN" PING

ElastiCache-specific auth failures:

IAM permission check:

aws iam simulate-principal-policy --policy-source-arn <role-arn> \
  --action-names elasticache:Connect \
  --resource-arns \
    arn:aws:elasticache:<region>:<account>:serverlesscache:<cache-name> \
    arn:aws:elasticache:<region>:<account>:user:<user-id>

Step 5: Command Permissions (RBAC ACL)

Commands requiring special categories:

Access string changes take effect on new connections only. Existing connections retain old permissions until reconnect.