# Valkey on Amazon ElastiCache

ARNscope shows an ElastiCache cache from the outside (its endpoints, nodes, security and users) and, through a tunnel, from the inside: every key and its value, any Pub/Sub channel or pattern, and new entries on any stream. It reads by default. For operational work, such as publishing an event during disaster recovery so other servers refresh or run a job, you can turn on writes for one connection; see [Writing (danger zone)](#writing-danger-zone). ARNscope never configures a cache, runs scripts or flushes data.

<figure class="doc-video">
<video controls playsinline preload="none" poster="/media/docs/valkey/valkey-explainer.webp?v=1" aria-label="Valkey in ARNscope: a narrated two-minute tour">
<source src="/media/docs/valkey/valkey-explainer.webm?v=1" type="video/webm">
<source src="/media/docs/valkey/valkey-explainer.mp4?v=1" type="video/mp4">
<track kind="captions" srclang="en" label="English" src="/media/docs/valkey/valkey-explainer.vtt?v=1" default>
</video>
<figcaption>A two-minute narrated tour, with captions: the Overview, connecting through a tunnel, keys, Pub/Sub, streams and writes. Sample data.</figcaption>
</figure>

## Two kinds of tabs

Open **Valkey** in ARNscope, choose the profile and region, and select a cache. The list shows Valkey and Redis OSS caches: node-based replication groups and serverless caches.

| Tab | Where the data comes from | Needs a tunnel |
| --- | --- | --- |
| **Overview** | The ElastiCache API (`DescribeReplicationGroups`, `DescribeCacheClusters`, `DescribeServerlessCaches`, `DescribeUserGroups`, `DescribeUsers`) | No |
| **Keys** | The cache | Yes |
| **Pub/Sub** | The cache | Yes |
| **Streams** | The cache | Yes |

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/valkey/valkey-overview.webp?v=1" aria-label="Selecting a cache and reading its Overview: endpoints, nodes, security and users marked Read-only or Can write.">
<source src="/media/docs/valkey/valkey-overview.webm?v=1" type="video/webm">
<source src="/media/docs/valkey/valkey-overview.mp4?v=1" type="video/mp4">
</video>
<figcaption>The Overview: endpoints and nodes, then every user, marked <strong>Read-only</strong> or <strong>Can write</strong>.</figcaption>
</figure>

ElastiCache is only reachable inside its VPC, so the last three tabs need an ARNscope Valkey tunnel: a saved tunnel on the **Tunnels** page that opens one SSM session to the cache's primary endpoint through an instance in your network. See [SSM tunnels](https://arnscope.com/docs/ssm-tunnels).

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/valkey/valkey-connect.webp?v=1" aria-label="Starting the cache tunnel, choosing a read-only user and connecting.">
<source src="/media/docs/valkey/valkey-connect.webm?v=1" type="video/webm">
<source src="/media/docs/valkey/valkey-connect.mp4?v=1" type="video/mp4">
</video>
<figcaption>Start the tunnel, choose a user and connect: the bar shows who you are connected as and how many keys the cache holds.</figcaption>
</figure>

## Requirements

- **In-transit encryption.** ARNscope connects with TLS and checks the certificate against the cache's real host name, through the tunnel.
- **An ElastiCache user** in the cache's user group:
  - **IAM users** (recommended): ARNscope signs a short-lived IAM token with your AWS profile; no password is stored. The user's id and name must be the same (an AWS rule for IAM users).
  - **Password users**, and the `default` user of a cache with an AUTH token: choose a Secrets Manager secret holding the password (plain text, or JSON with a `password`, `auth_token` or `token` key, or one you pick) or type it in. ARNscope reads the secret when you connect and never saves the password; a typed one lasts for that session only.
- **`elasticache:Connect`** for your role on the cache and on the user (IAM users), or **`secretsmanager:ListSecrets`** and **`secretsmanager:GetSecretValue`** on the secret (password users from Secrets Manager).
- **A bastion** that the cache's security group allows on port 6379.

### A read-only ElastiCache user

For browsing, a user that can only read is the safest choice. For example:

```text
on ~* &* -@all +@read +subscribe +psubscribe +ssubscribe +unsubscribe +punsubscribe +sunsubscribe +ping +acl|whoami +client|setname
```

Optionally add `+pubsub|channels +pubsub|shardchannels` (for **Active channels**) and `+info` (to show the server version). Narrow `~*` and `&*` to the keys and channels the user may read, for example `~chart:* &chart:*`.

ARNscope lists every IAM and password user in the cache's user groups. It suggests a read-only one and labels users that may write with **Can write**; writes stay off as them until you turn them on. Password users ask where the password comes from before connecting, and suggest Secrets Manager secrets whose name, description or tags mention the cache or the user. Users with no password cannot be used.

## Read by default

Every read passes an allowlist before a single byte is sent: `SCAN`, `TYPE`, `PTTL`, `OBJECT ENCODING`, `MEMORY USAGE`, the length and range reads of each type, `XINFO`, plain `XREAD`, the subscribe commands, `PUBSUB CHANNELS`, `INFO`, `JSON.GET` and connection housekeeping (`AUTH`, `PING`, `ACL WHOAMI`, `CLIENT SETNAME`). `KEYS`, consumer groups (`XREADGROUP`, `XACK`), `MONITOR`, `CONFIG` and scripts are always refused. Writes never go through this path; they have their own, below.

## Writing (danger zone)

Every write is a danger-zone operation.

- **Allow writes, per connection.** A connection starts with writes off. The **Allow writes** switch in the connection bar asks for confirmation in a native dialog (the page itself cannot turn writes on); while writes are on, the bar shows a red **Writes on** chip with the minutes left. Writes turn off again after 15 minutes without a write, when the connection or the tunnel is lost, and on every reconnect, user, tunnel or cache change and app restart.
- **A confirmation per write.** Each write shows a red confirmation naming the operation, the key or channel, the cache and user, and the size. Deletes and overwrites say they can't be undone; removing a member says Valkey deletes the key when it was the last one.
- **No raw commands.** Writes are typed operations; ARNscope builds the exact command and checks its shape before sending: `PUBLISH`/`SPUBLISH`; `XADD` with an auto id (to an existing stream it adds `NOMKSTREAM`, so a typo never creates one; only **New key → Stream** creates a stream) and never `MAXLEN` or `MINID` trimming; `SET` with `NX`/`XX` and `KEEPTTL` or `PX`; `HSET`/`HDEL`; `LPUSH`/`RPUSH`; `SADD`/`SREM`; `ZADD`/`ZREM`; `UNLINK`; `PEXPIRE` (at least 1 ms) and `PERSIST`. Each value is at most 1 MiB and each write at most 100 fields, members or values.
- **Sent once.** A write is never retried. If the connection fails after a write was sent, ARNscope says the write may have been applied and asks you to check before retrying.
- **The cache's ACL decides.** A user without the command or key gets the cache's `NOPERM`, shown with the user's access string and a hint to connect as a user allowed to run it. Users ARNscope classifies as read-only show the write controls disabled.
- **Recorded locally, without values.** Every attempt goes to the local activity log: time, cache and user, operation, key or channel, value size and the result (success, failed, or outcome unknown). Values and payloads are never stored.

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/valkey/valkey-writes-toggle.webp?v=1" aria-label="Turning on Allow writes for a connection, confirming the native dialog, and turning writes off again.">
<source src="/media/docs/valkey/valkey-writes-toggle.webm?v=1" type="video/webm">
<source src="/media/docs/valkey/valkey-writes-toggle.mp4?v=1" type="video/mp4">
</video>
<figcaption><strong>Allow writes</strong> asks first, then shows the red <strong>Writes on</strong> chip with the minutes left. Turning it off makes the connection read-only again.</figcaption>
</figure>

What you can do:

| Where | Writes |
| --- | --- |
| **Pub/Sub → Publish** | Publish a message to a channel (or a sharded channel). The result counts subscribers on the primary only; subscribers on replicas are not counted, so 0 does not mean nobody received it. |
| **Streams → Add entry** | Add an entry with fields and values to an existing stream; the result shows the new id. |
| **Keys → New key** | Create a string (`SET … NX`, never replacing a key), hash, list, set, sorted set or stream. |
| **Keys → selected key** | Edit a string (only after its full value is loaded, up to 1 MiB; binary values as base64, written back exactly), set or delete hash fields, push to a list, add or remove set and sorted-set members, add a stream entry, set or remove the TTL, delete the key (`UNLINK`). Elements shown truncated can't be removed, since ARNscope can't name them exactly. |

A user that may publish to one channel, for example, needs an access string like `on resetkeys resetchannels &jobs:refresh -@all +publish`.

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/valkey/valkey-publish.webp?v=1" aria-label="Publishing a message to jobs:refresh, confirming the red danger bar, and reading how many subscribers received it.">
<source src="/media/docs/valkey/valkey-publish.webm?v=1" type="video/webm">
<source src="/media/docs/valkey/valkey-publish.mp4?v=1" type="video/mp4">
</video>
<figcaption>Publish: the red confirmation names the command, cache, user and size; the result counts subscribers on the primary.</figcaption>
</figure>

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/valkey/valkey-edit-key.webp?v=1" aria-label="Creating a string key with SET NX, overwriting its value with SET XX KEEPTTL, then deleting it, each after a red confirmation.">
<source src="/media/docs/valkey/valkey-edit-key.webm?v=1" type="video/webm">
<source src="/media/docs/valkey/valkey-edit-key.mp4?v=1" type="video/mp4">
</video>
<figcaption>New key, edit a loaded value and delete the key. Each write asks first and says when it can't be undone.</figcaption>
</figure>

## Keys

Keys are read a page at a time with `SCAN` (never `KEYS`), filtered by pattern and type. The pattern starts from the user's key rule. Each page reads the type and TTL of its keys; memory is read only for the key you open. Keys the user may not read are listed as **No access**. Binary key names are shown in base64 and round-trip exactly.

Opening a key shows its type, TTL, encoding, memory and length, and its value: strings as text or JSON (binary values in the bytes viewer, with image and hex views), hashes, lists, sets and sorted sets as tables, streams with their entries, consumer groups and consumers, and JSON documents (`ReJSON-RL`). Collections load a page at a time, sized to about 4 MiB. Strings show their first 64 KiB; **Load full value** reads up to 10 MiB.

The list holds at most 20,000 keys; **Clear list** empties it. Only database 0 is browsed.

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/valkey/valkey-keys.webp?v=1" aria-label="Loading more keys, filtering by pattern and type, and opening a hash and a stream.">
<source src="/media/docs/valkey/valkey-keys.webm?v=1" type="video/webm">
<source src="/media/docs/valkey/valkey-keys.mp4?v=1" type="video/mp4">
</video>
<figcaption>Load more keys, filter by pattern and type, then open a hash and a stream with its consumer group.</figcaption>
</figure>

## Pub/Sub

Add channels (`SUBSCRIBE`), patterns (`PSUBSCRIBE`) or sharded channels (`SSUBSCRIBE`) and press **Subscribe**. Nothing starts on its own. The user's channel rules are offered as one-click patterns.

### Sharded or classic

Valkey has two Pub/Sub systems that never cross over: a message sent with `SPUBLISH` reaches only `SSUBSCRIBE` listeners, and one sent with `PUBLISH` reaches only `SUBSCRIBE` and `PSUBSCRIBE` listeners. Sharded channels take exact names; there is no pattern form, so `PSUBSCRIBE *` hears nothing from services that use `SPUBLISH`.

ARNscope reads the cache's users to tell which kind its services use. Users allowed to publish only one way decide it (`+spublish` without `+publish` means sharded); when no user publishes, users allowed to subscribe only one way do. Users allowed both, such as an admin with `+@all`, say nothing. If the users point one way, the tab starts on that kind and names the users it went by; if they disagree or say nothing, it says so. Either way the choice stays yours, and picking the other kind shows a warning.

ElastiCache checks channel names against the user's `&` rules as globs, but compares `PSUBSCRIBE` patterns with them literally: with `&chart:*`, the pattern `chart:*` works but `chart:AAPL:*` does not. ARNscope checks typed patterns before subscribing and explains a refusal.

Subscribing to `*` on a busy cache can slow the tunnel for browsing too, so ARNscope asks first. Pub/Sub keeps no history: you see what is published from the moment you subscribe.

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/valkey/valkey-pubsub.webp?v=1" aria-label="Adding the user's channel pattern with one click, subscribing, watching messages arrive and pausing.">
<source src="/media/docs/valkey/valkey-pubsub.webm?v=1" type="video/webm">
<source src="/media/docs/valkey/valkey-pubsub.mp4?v=1" type="video/mp4">
</video>
<figcaption>One click adds the user's pattern; <strong>Subscribe</strong> starts the live view and <strong>Pause</strong> keeps counting what arrives.</figcaption>
</figure>

Channels, patterns, stream keys and key patterns you use are remembered per cache (names only, the 20 most recent of each kind) and offered as one-click chips; × forgets one.

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/valkey/valkey-recent-names.webp?v=1" aria-label="Recent patterns, channels and streams offered as chips after switching tabs, forgetting one and reusing another.">
<source src="/media/docs/valkey/valkey-recent-names.webm?v=1" type="video/webm">
<source src="/media/docs/valkey/valkey-recent-names.mp4?v=1" type="video/mp4">
</video>
<figcaption>Recent names come back on every tab; × forgets one, a click uses one again.</figcaption>
</figure>

## Finding channels

**Find channels** merges four sources, each tagged:

- **From access rules:** the `&` rules of the cache's users. Literal rules are channel names (sharded ones when the cache's services use sharded Pub/Sub); rules with `*`, `?` or `[` are patterns.
- **By listening:** a `PSUBSCRIBE` of one of your user's channel rules for 5 to 30 seconds, on its own connection. Payloads are discarded as they arrive; only channel names and message counts are kept (at most 1,000 names). Only channels with traffic during the listen show up. Listening cannot hear sharded channels.
- **Active channels:** `PUBSUB CHANNELS`, when the user may run it.
- **Shard channels:** `PUBSUB SHARDCHANNELS`, the sharded channels with a subscriber right now, when the user may run it. This is how to find sharded channel names.

Click a channel to add it, or a pattern to add it as a pattern. On the Streams tab, literal key rules of users that may `XADD` or `XREADGROUP` are suggested as stream keys.

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/valkey/valkey-find-channels.webp?v=1" aria-label="Opening Find channels, listening for five seconds, and adding a heard channel.">
<source src="/media/docs/valkey/valkey-find-channels.webm?v=1" type="video/webm">
<source src="/media/docs/valkey/valkey-find-channels.mp4?v=1" type="video/mp4">
</video>
<figcaption><strong>Find channels</strong>: names from access rules, then a five-second listen with message counts. Click one to add it.</figcaption>
</figure>

## Streams

Add stream keys (or use **Find streams**, a `SCAN` for streams), then **Load latest** reads the newest entries of each, or **Live tail** follows new entries. The tail starts from each stream's newest entry and never joins a consumer group, so it does not affect your consumers. Pausing stops reading; the tail resumes where it paused without missing entries.

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/valkey/valkey-streams.webp?v=1" aria-label="Finding streams, loading their latest entries and starting a live tail.">
<source src="/media/docs/valkey/valkey-streams.webm?v=1" type="video/webm">
<source src="/media/docs/valkey/valkey-streams.mp4?v=1" type="video/mp4">
</video>
<figcaption><strong>Find streams</strong>, <strong>Load latest</strong>, then <strong>Live tail</strong>, paused to read.</figcaption>
</figure>

## Memory limits

Busy channels never grow ARNscope's memory without bound, and nothing received is written to disk or to logs.

- Each live message keeps at most 16 KiB of its payload; the rest is read and discarded, and the full size is shown.
- Each live view keeps the newest 1,000 messages or 8 MiB, whichever comes first. **Live limits** raises this to at most 5,000 messages or 32 MiB. Older messages are dropped and counted.
- A paused or overloaded Pub/Sub view keeps reading and counts what it discards, so the cache never disconnects a slow subscriber.
- At most 8 live views run at once. A live view stops when you leave its tab or the page.

## Permissions

| What | Actions |
| --- | --- |
| List caches | `elasticache:DescribeReplicationGroups`, `elasticache:DescribeServerlessCaches`, `elasticache:DescribeCacheClusters`, `elasticache:DescribeUserGroups`, `elasticache:DescribeUsers` |
| Overview | The same |
| Keys, Pub/Sub and Streams | `elasticache:Connect` (on the cache and the user) for IAM users, or `secretsmanager:ListSecrets` and `secretsmanager:GetSecretValue` for passwords from Secrets Manager; plus the tunnel's SSM permissions |
| Writes | `elasticache:Connect`; what succeeds is decided by the ElastiCache user's access string |

## Limitations

- Caches in cluster mode enabled or compatible show their Overview only; browsing them is not supported yet.
- Serverless caches are supported, with what ElastiCache Serverless allows: no pattern subscriptions (`PSUBSCRIBE`, so no **Listen** in Find channels; subscribe to exact channels), and key details show no encoding or memory (`OBJECT` and `MEMORY` are unavailable). Streams in different hash slots are tailed with one `XREAD` per slot.
- Only database 0, through the primary endpoint. The reader endpoint is not used.
- IAM users, password users and AUTH tokens. Users with no password and caches without authentication are not supported.
- No CloudWatch metrics, no `MONITOR`, no keyspace notifications.
- IAM connections are renewed before ElastiCache's 12-hour limit; a Pub/Sub view may miss messages during the reconnect and says so.

Source: https://arnscope.com/docs/valkey
