managing-elasticache

name	managing-elasticache
description	Use when working with Elasticache — amazon ElastiCache cluster health, node status, replication group management, parameter group analysis, and performance monitoring.
connection_type	aws
preload	false

ElastiCache Management Skill

Analyze and manage ElastiCache clusters with safe, read-only operations.

MANDATORY: Two-Phase Execution

You MUST follow this two-phase pattern. Skipping Phase 1 causes hallucinated cluster/node names.

Phase 1: Discovery (ALWAYS run first)

#!/bin/bash

# 1. List Redis clusters
aws elasticache describe-cache-clusters --output json | jq '.CacheClusters[] | {CacheClusterId, Engine, EngineVersion, CacheNodeType, NumCacheNodes, CacheClusterStatus}'

# 2. List replication groups (Redis)
aws elasticache describe-replication-groups --output json | jq '.ReplicationGroups[] | {ReplicationGroupId, Status, ClusterEnabled, NodeGroups: (.NodeGroups | length)}'

# 3. List Memcached clusters (if applicable)
aws elasticache describe-cache-clusters --show-cache-node-info --output json | jq '.CacheClusters[] | select(.Engine == "memcached")'

# 4. List parameter groups
aws elasticache describe-cache-parameter-groups --output json | jq '.CacheParameterGroups[] | {CacheParameterGroupName, CacheParameterGroupFamily}'

Phase 1 outputs:

• Cache clusters with engine types and node types
• Replication groups with topology
• Parameter groups in use

Phase 2: Analysis (only after Phase 1)

Only reference cluster IDs, replication groups, and node types confirmed in Phase 1.

Shell Script Patterns

Helper Function

#!/bin/bash

# Core ElastiCache helper — always use this
ec_cmd() {
    aws elasticache "$@" --output json
}

# CloudWatch metric for ElastiCache
ec_metric() {
    local cluster_id="$1" metric="$2" stat="${3:-Average}" period="${4:-300}"
    aws cloudwatch get-metric-statistics \
        --namespace AWS/ElastiCache \
        --metric-name "$metric" \
        --dimensions Name=CacheClusterId,Value="$cluster_id" \
        --start-time "$(date -u -v-1H +%Y-%m-%dT%H:%M:%S 2>/dev/null || date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%S)" \
        --end-time "$(date -u +%Y-%m-%dT%H:%M:%S)" \
        --period "$period" \
        --statistics "$stat" \
        --output json
}

# Redis CLI helper (if direct access available)
redis_cmd() {
    local endpoint="$1" port="${2:-6379}" cmd="$3"
    redis-cli -h "$endpoint" -p "$port" --tls $cmd
}

Anti-Hallucination Rules

• NEVER reference a cluster ID without confirming via describe-cache-clusters
• NEVER reference a replication group without confirming via describe-replication-groups
• NEVER assume node types — always check cluster description
• NEVER guess parameter group names — always list first
• NEVER assume engine version — check cluster metadata

Safety Rules

• READ-ONLY ONLY: Use only describe-, list-, CloudWatch get-metric-statistics, Redis INFO/MONITOR
• FORBIDDEN: modify-cache-cluster, delete-cache-cluster, create-snapshot, reboot-cache-cluster without explicit user request
• NEVER run KEYS * on production — use SCAN instead
• Monitor memory usage before any investigation queries

Common Operations

Cluster Health Overview

#!/bin/bash
echo "=== Cache Clusters ==="
ec_cmd describe-cache-clusters --show-cache-node-info | jq '.CacheClusters[] | {CacheClusterId, Engine, EngineVersion, CacheNodeType, NumCacheNodes, CacheClusterStatus, PreferredMaintenanceWindow}'

echo ""
echo "=== Replication Groups ==="
ec_cmd describe-replication-groups | jq '.ReplicationGroups[] | {ReplicationGroupId, Status, ClusterEnabled, AutomaticFailover, MultiAZ, NodeGroups: [.NodeGroups[] | {NodeGroupId, Status, PrimaryEndpoint: .PrimaryEndpoint.Address, Slots}]}'

echo ""
echo "=== Subnet Groups ==="
ec_cmd describe-cache-subnet-groups | jq '.CacheSubnetGroups[] | {CacheSubnetGroupName, VpcId}'

Node & Replication Status

#!/bin/bash
CLUSTER_ID="${1:-my-cluster}"

echo "=== Node Details ==="
ec_cmd describe-cache-clusters --cache-cluster-id "$CLUSTER_ID" --show-cache-node-info | jq '.CacheClusters[0].CacheNodes[] | {CacheNodeId, CacheNodeStatus, Endpoint: .Endpoint.Address, ParameterGroupStatus}'

echo ""
echo "=== Replication Lag ==="
ec_metric "$CLUSTER_ID" "ReplicationLag" "Maximum" | jq -r '.Datapoints | sort_by(.Timestamp) | .[-5:][] | "\(.Timestamp)\t\(.Maximum)s"'

Performance Metrics

#!/bin/bash
CLUSTER_ID="${1:-my-cluster}"

echo "=== CPU Utilization ==="
ec_metric "$CLUSTER_ID" "CPUUtilization" "Average" | jq -r '.Datapoints | sort_by(.Timestamp) | .[-5:][] | "\(.Timestamp)\t\(.Average)%"'

echo ""
echo "=== Memory Usage ==="
ec_metric "$CLUSTER_ID" "DatabaseMemoryUsagePercentage" "Average" | jq -r '.Datapoints | sort_by(.Timestamp) | .[-5:][] | "\(.Timestamp)\t\(.Average)%"'

echo ""
echo "=== Cache Hits/Misses ==="
ec_metric "$CLUSTER_ID" "CacheHitRate" "Average" | jq -r '.Datapoints | sort_by(.Timestamp) | .[-5:][] | "\(.Timestamp)\t\(.Average)%"'

echo ""
echo "=== Evictions ==="
ec_metric "$CLUSTER_ID" "Evictions" "Sum" | jq -r '.Datapoints | sort_by(.Timestamp) | .[-5:][] | "\(.Timestamp)\t\(.Sum)"'

echo ""
echo "=== Current Connections ==="
ec_metric "$CLUSTER_ID" "CurrConnections" "Average" | jq -r '.Datapoints | sort_by(.Timestamp) | .[-5:][] | "\(.Timestamp)\t\(.Average)"'

Parameter Group Analysis

#!/bin/bash
PARAM_GROUP="${1:-default.redis7}"

echo "=== Parameter Group Settings ==="
ec_cmd describe-cache-parameters --cache-parameter-group-name "$PARAM_GROUP" | jq '.Parameters[] | select(.Source != "system") | {ParameterName, ParameterValue, DataType, IsModifiable}'

echo ""
echo "=== Key Parameters ==="
ec_cmd describe-cache-parameters --cache-parameter-group-name "$PARAM_GROUP" | jq '.Parameters[] | select(.ParameterName | test("maxmemory|timeout|tcp-keepalive|notify")) | {ParameterName, ParameterValue}'

Output Format

Present results as a structured report:

Managing Elasticache Report
═══════════════════════════
Resources discovered: [count]

Resource       Status    Key Metric    Issues
──────────────────────────────────────────────
[name]         [ok/warn] [value]       [findings]

Summary: [total] resources | [ok] healthy | [warn] warnings | [crit] critical
Action Items: [list of prioritized findings]

Target ≤50 lines of output. Use tables for multi-resource comparisons.

Counter-Rationalizations

Shortcut	Counter	Why
"I'll skip discovery and check known resources"	Always run Phase 1 discovery first	Resource names change, new resources appear — assumed names cause errors
"The user only asked for a quick check"	Follow the full discovery → analysis flow	Quick checks miss critical issues; structured analysis catches silent failures
"Default configuration is probably fine"	Audit configuration explicitly	Defaults often leave logging, security, and optimization features disabled
"Metrics aren't needed for this"	Always check relevant metrics when available	API/CLI responses show current state; metrics reveal trends and intermittent issues
"I don't have access to that"	Try the command and report the actual error	Assumed permission failures prevent useful investigation; actual errors are informative

Common Pitfalls

• Eviction pressure: High eviction rate means memory is full — check maxmemory-policy
• Replication lag: Lag spikes indicate overloaded replicas or network issues
• KEYS command: Never use KEYS on production — use SCAN with cursor
• Cluster mode: Cluster mode enabled vs disabled have different topology — verify before connecting
• Maintenance windows: Patching during maintenance windows causes brief unavailability
• Snapshot overhead: Creating snapshots on single-node clusters causes latency spikes