BetterDB-inc/monitor

ElastiCache IAM Authentication

The BetterDB Agent now supports AWS IAM authentication for ElastiCache for Valkey 7.2+ and Redis OSS 7.0+. Instead of a static password, the agent mints short-lived SigV4-signed tokens from the host's AWS credentials and rotates them automatically on every reconnect — no secrets to configure or rotate.

Setup

Enable IAM mode with --auth-mode elasticache-iam (or AGENT_AUTH_MODE=elasticache-iam) alongside three required fields:

| Flag | Env var | Description |
|------|---------|-------------|
| --auth-mode elasticache-iam | AGENT_AUTH_MODE | Enable IAM auth (default: password) |
| --aws-region | AWS_REGION | AWS region of the cluster |
| --aws-resource-name | AWS_RESOURCE_NAME | Replication group ID or serverless cache name |
| --aws-user-id | AWS_USER_ID | ElastiCache IAM user-id (must equal user-name) |
| --aws-serverless | AWS_SERVERLESS | Set to true for ElastiCache Serverless |

TLS is required — the agent will exit with a clear error if --valkey-tls true is not set.

AWS credentials are resolved from the standard chain: environment variables, ~/.aws/credentials, EC2 instance profile, and container role. On EC2, attach an instance profile with elasticache:Connect on the cluster and user ARNs and no further credential configuration is needed.

Example

docker run -d --name betterdb-agent \
  --restart=always \
  -e BETTERDB_TOKEN="<your-token>" \
  -e BETTERDB_CLOUD_URL="wss://<your-workspace>.app.betterdb.com/agent/ws" \
  -e VALKEY_HOST="<your-elasticache-endpoint>" \
  -e VALKEY_PORT="6379" \
  -e VALKEY_USERNAME="<your-iam-user-id>" \
  -e VALKEY_TLS="true" \
  -e AGENT_AUTH_MODE="elasticache-iam" \
  -e AWS_REGION="us-east-1" \
  -e AWS_RESOURCE_NAME="<your-cache-name>" \
  -e AWS_USER_ID="<your-iam-user-id>" \
  betterdb/agent

Requirements

- ElastiCache for Valkey 7.2+ or Redis OSS 7.0+
- Encryption in transit (TLS) enabled on the cluster
- An ElastiCache user with authentication-mode Type=iam — the user-id must equal the user-name
- The user assigned to a user group attached to the cluster
- An IAM policy granting elasticache:Connect on the cluster and user ARNs

See the https://docs.betterdb.com/providers/aws-elasticache for a full walkthrough including user group setup for Valkey-engine clusters.

Backwards compatibility

Password authentication is unchanged and remains the default. Existing deployments require no changes.