Amazon ElastiCache for Valkey

Qovery creates it in the AWS account of the environment’s cluster, as a Blueprint service in one of your environments.


Catalog name	`aws-elasticache-valkey`
Category	Databases & Caches
Provider	AWS
Engine	terraform
Major versions (latest release)	`9` (1.0.2)
Source	AWS/valkey/9

New to this? You don’t need to know Kubernetes or Terraform. Qovery sets up Amazon ElastiCache for Valkey in your cloud account and manages it for you: you fill in a form, or paste the prompt below into your coding agent. The values it publishes, listed under Outputs, reach your other services as environment variables. Qovery tells you when a newer version of the Blueprint is available. Check the requirements in the Reference section before you start, and try it first in a development environment.

Create it

Console
CLI and API
Coding agent

Open the environment, then New service › Blueprint.
Find Amazon ElastiCache for Valkey in the catalog and pick the major version.
Fill in the variables. Required ones are marked; the others use their defaults.
Create the service, and deploy it now or later.

List the catalog to get the latest tag, then create the service from it. qovery api signs the requests with your CLI session.

ORG_ID="REPLACE_WITH_ORGANIZATION_ID"
ENV_ID="REPLACE_WITH_ENVIRONMENT_ID"

qovery api "organization/$ORG_ID/blueprint/catalog" | jq '.. | objects | select(.name? == "aws-elasticache-valkey")'

cat > blueprint.json <<'EOF'
{
  "name": "aws-elasticache-valkey",
  "tag": "AWS/valkey/9/1.0.2",
  "icon": "app://qovery-console/redis",
  "variables": [
    {
      "name": "valkey_name",
      "value": "REPLACE_WITH_VALKEY_NAME"
    },
    {
      "name": "instance_class",
      "value": "REPLACE_WITH_INSTANCE_CLASS"
    }
  ],
  "spec_overrides": {
    "engine_version": "1.9.7"
  }
}
EOF
BLUEPRINT_ID=$(qovery api "environment/$ENV_ID/blueprint" --method POST --input - < blueprint.json | jq -r .id)
rm blueprint.json   # it can hold secret values
qovery api "blueprint/$BLUEPRINT_ID/deploy" --method POST
qovery api "blueprint/$BLUEPRINT_ID"   # status of the latest deployment

Replace each REPLACE_WITH_ value. Add optional variables to variables the same way.

Paste this into Claude Code, Cursor, Codex or another coding agent with the Qovery agent skills installed (curl -fsSL https://skill.qovery.com/install.sh | bash).

Prompt

Add the Qovery Blueprint Amazon ElastiCache for Valkey (aws-elasticache-valkey) to one of my Qovery environments and deploy it. Ask me for valkey_name and instance_class.
Ask me before deploying to a production environment.
Docs: https://www.qovery.com/docs/configuration/blueprints/aws-elasticache-valkey.md

You don’t add any file to your repository. Qovery creates the Blueprint from the Console or the API.

Variables and outputs

Generated from qbm.yml at AWS/valkey/9/1.0.2, the manifest the Console form is built from.

All 17 variables

Name	Type	Required	Default	Secret	Description
`valkey_name`	string	Yes			Letters, digits, single hyphens; must start with a letter and end with a letter or digit; max 40 chars. No underscores.
`valkey_password`	string			Yes	Leave empty and Qovery generates a 32-character alphanumeric auth token. To set your own: 16–128 chars, must not contain /, @, ”, or spaces.
`instance_class`	string	Yes	`cache.t3.micro`		ElastiCache node type
`engine_version`	string		`9.0`		Valkey engine version
`port`	number		`6379`		Valkey port
`instances_number`	number		`1`		Shards: 1 = single node; more enables cluster mode (a replica per shard, Multi-AZ). Pick at creation: cluster mode cannot be turned on later.
`at_rest_encryption_enabled`	bool		`true`		Encrypt data at rest
`parameter_group_name`	string				Leave empty — derived from the topology: default.valkey9 for a single node group, default.valkey9.cluster.on when instances_number > 1.
`subnet_group_name`	string				Leave empty — derived from the cluster’s ElastiCache subnet group. Set it only on a user-provided VPC.
`security_group_ids`	string				Leave empty — derived from the cluster’s workers security group. Set it (comma-separated ids) only on a user-provided VPC.
`apply_changes_now`	bool		`false`		Apply changes immediately instead of waiting for the next maintenance window
`auto_minor_version_upgrade`	bool		`true`		Automatically apply minor version upgrades during the maintenance window
`preferred_maintenance_window`	string		`Tue:02:00-Tue:04:00`		UTC, format ddd:hh24:mi-ddd:hh24:mi.
`preferred_backup_window`	string		`00:00-01:00`		Daily, UTC, format hh24:mi-hh24:mi. Only used when backup_retention_period > 0.
`backup_retention_period`	number		`14`		Days to retain automatic snapshots (0 disables)
`skip_final_snapshot`	bool		`false`		Skip the final snapshot on deletion. False leaves a snapshot behind after the group is destroyed.
`snapshot_name`	string				Unset = start empty. Else an existing ElastiCache snapshot to seed from; read at creation only.

Outputs become environment variables that other services in the environment can use. By default Qovery also creates an alias for each output, prefixed with the Blueprint’s name; see Aliases Qovery creates for outputs for the naming rules and the cases where no alias is created.

All 12 outputs

Name	Secret	Description
`valkey_identifier`		ElastiCache replication group id (what the AWS console shows as the cluster name)
`valkey_host`		Hostname to connect to: configuration endpoint in cluster mode, else primary
`valkey_port`		Valkey port
`valkey_username`		Valkey user applications authenticate as — always the built-in ‘default’ user
`valkey_password`	Yes	Auth token (generated when the input was left empty)
`valkey_url`	Yes	Connection URL over TLS
`valkey_primary_endpoint_address`		Primary endpoint hostname (empty in cluster mode)
`valkey_reader_endpoint_address`		Reader endpoint hostname, load-balanced across replicas (empty in cluster mode)
`valkey_configuration_endpoint_address`		Configuration endpoint hostname (empty when instances_number = 1)
`valkey_arn`		Replication group ARN
`valkey_engine_version_actual`		Engine version actually running (may include the patch AWS chose)
`valkey_member_clusters`		Cache cluster ids that make up the replication group

Secret variables and outputs are encrypted and masked in Qovery, but Terraform can also keep their values, and values derived from them, in its state. With the Qovery-managed state backend (the default), Qovery stores the state. If you use your own backend, protect it and keep state files out of version control.

Reference

From the Blueprint’s README. Creates an AWS ElastiCache for Valkey 9 replication group with configurable node type, topology, backups, maintenance window, and network settings. Traffic is encrypted in transit and protected by an auth token, and data is encrypted at rest. The replication group id is valkey_name lowercased (AWS requirement). Applications connect over TLS as the built-in default user with the auth token as password: rediss://default:<token>@<host>:6379/0, published as the valkey_url output. The rediss:// scheme is correct here and not a leftover: Valkey speaks the Redis protocol, so Redis clients and URLs work unchanged — which is what makes it a drop-in replacement. Engine versions 9.0 and 9.1 share the valkey9 parameter group family, so either can be selected without changing the derived parameter group. AWS states that Valkey 9 parameter groups are incompatible with Valkey 8.x and Redis, which is why Valkey 9 is its own blueprint rather than a version choice inside the Valkey 8 one.

Variables

Required

Name	Type	Sensitive	Description
`valkey_name`	string		Replication group name. Must start with a letter, end with a letter or digit, and use single hyphens between them; max 40 chars. Underscores are not allowed.
`instance_class`	string		ElastiCache node type. Default suggestion: `cache.t3.micro`.

Available node types: cache.t3.micro, cache.t3.small, cache.t3.medium, cache.t4g.micro, cache.r6g.large, cache.r6g.xlarge — the same set the Redis blueprint offers.

Credentials

Name	Type	Sensitive	Default	Description
`valkey_password`	string	yes	generated	Omit and Qovery generates a 32-character alphanumeric auth token. To set your own: 16–128 chars, must not contain /, @, ”, or spaces.

In the Console, leaving the field blank omits it. Through the API or Terraform, omit the variable rather than sending an empty string: the platform rejects an empty variable value.

Instance & topology

Name	Type	Default	Description
`engine_version`	string	`9.0`	Valkey engine version: `9.0`, `9.1`
`port`	number	`6379`	Valkey port
`instances_number`	number	`1`	Node groups (shards). 1 = a single node with no replica. Above 1 enables cluster mode with one replica per shard, and forces failover and Multi-AZ. Pick it at creation — ElastiCache cannot turn cluster mode on later.
`parameter_group_name`	string		Leave empty — derived from the topology.

instances_number = 1 creates a single node with no replica. Above 1, the group switches to cluster mode: N shards, one replica each (so 2N nodes), with automatic failover and Multi-AZ enabled because AWS requires both there, and the default.valkey9.cluster.on parameter group instead of default.valkey9. Clients then need a cluster-aware Valkey library and the valkey_configuration_endpoint_address output. Pick the topology at creation. ElastiCache cannot turn cluster mode on for an existing group, so raising instances_number from 1 fails at apply rather than resharding — deploy a new service instead. Changing it between two cluster-mode values (2 → 4) does reshard in place.

Security

Name	Type	Default	Description
`at_rest_encryption_enabled`	bool	`true`	Encrypt data at rest

Encryption in transit is always on and is not a variable: ElastiCache only accepts an auth token on a TLS-enabled group, so a group without TLS would also be a group reachable with no password by anything inside the cluster security group. Clients must connect with rediss://.

Network

Name	Type	Default	Description
`subnet_group_name`	string		Leave empty — derived from the Qovery cluster’s ElastiCache subnet group. Set it only on a cluster with a user-provided VPC, where that lookup finds nothing.
`security_group_ids`	string		Leave empty — derived from the Qovery cluster’s workers security group. Set it (comma-separated ids) only on a cluster with a user-provided VPC, where that lookup finds nothing.

By default the group is attached to the Qovery cluster network: the ElastiCache subnet group created at cluster bootstrap (named elasticache-<cluster vpc id>) and the cluster workers security group, so pods in the cluster can reach Valkey out of the box. On clusters deployed into an existing VPC (user-provided network), the ClusterId tag lookup may not resolve and the bootstrap subnet group may not exist; set both variables explicitly in that case.

Maintenance & upgrades

Name	Type	Default	Description
`apply_changes_now`	bool	`false`	Apply changes immediately
`auto_minor_version_upgrade`	bool	`true`	Auto-apply minor version upgrades during maintenance
`preferred_maintenance_window`	string	`Tue:02:00-Tue:04:00`	Maintenance window (UTC), `ddd:hh24:mi-ddd:hh24:mi`

The window is lowercased before it reaches AWS, which is how AWS stores and reports it, so a changed window applies without leaving a diff behind.

Backups

Name	Type	Default	Description
`preferred_backup_window`	string	`00:00-01:00`	Daily snapshot window (UTC), `hh24:mi-hh24:mi`
`backup_retention_period`	number	`14`	Days to retain automatic snapshots (0–35). `0` disables.
`skip_final_snapshot`	bool	`false`	Skip the final snapshot on deletion
`snapshot_name`	string		Existing snapshot to seed the group from. Unset = start empty.

With skip_final_snapshot = false, destroying the service leaves a snapshot named <replication group id>-final-snap-<creation timestamp> behind, which keeps costing storage until deleted. The timestamp is stamped once at creation, so it is unique per group — successive create/destroy cycles of the same name do not collide on an existing snapshot id — while staying stable across plans. snapshot_name is read at creation only: pointing it at a different snapshot later does nothing.

Outputs

Name	Sensitive	Description
`valkey_identifier`		ElastiCache replication group id (AWS console cluster name)
`valkey_host`		Hostname to connect to (configuration endpoint in cluster mode, primary endpoint otherwise)
`valkey_port`		Valkey port
`valkey_username`		Always `default`, the built-in Valkey user
`valkey_password`	yes	Auth token (generated when the input was left empty)
`valkey_url`	yes	`rediss://default:<token>@<host>:<port>/0`
`valkey_primary_endpoint_address`		Primary endpoint hostname (empty in cluster mode)
`valkey_reader_endpoint_address`		Reader endpoint hostname, load-balanced across replicas (empty in cluster mode)
`valkey_configuration_endpoint_address`		Configuration endpoint hostname (empty when `instances_number = 1`)
`valkey_arn`		Replication group ARN
`valkey_engine_version_actual`		Engine version actually running (incl. AWS-chosen patch)
`valkey_member_clusters`		Cache cluster ids making up the replication group

Lifecycle ignore_changes

log_delivery_configuration, notification_topic_arn, user_group_ids — configured outside the blueprint.
transit_encryption_mode — AWS picks preferred vs required and reports its own value back.
tags — preserves tags set on the group outside the blueprint.

engine_version is deliberately not ignored, so a version change applies. ElastiCache only upgrades forward.

Auth token

auth_token and auth_token_update_strategy are deliberately not ignored. An adopted group’s state holds no token, and the AWS provider sends the token from state on any update of the group: ignored, it would reach AWS empty and the apply would fail with Invalid AUTH token provided. So the first apply after an adoption sends valkey_password with ROTATE, immediately: the provider forces ApplyImmediately on that call, whatever apply_changes_now says. Nothing here checks valkey_password against the live token. Set it to the live one: a stale value is added as a second valid token. Rehearsed on Redis 7 only (2026-11-03, a 7.0 replication group with the live token): AWS accepted the call and the token kept working. Not run on Valkey. Changing valkey_password later rotates through Terraform: ROTATE adds the new token and keeps the old one valid. Revoke the old one with

aws elasticache modify-replication-group --replication-group-id <id> --auth-token <new> --auth-token-update-strategy SET --apply-immediately

. Before moving a service created on an earlier version to this one, make valkey_password equal the group’s live token. Earlier versions ignored auth_token, so a token rotated out-of-band left the old one in state, and the first apply on this version sends valkey_password with ROTATE.

Required AWS IAM permissions

The credentials used to deploy this blueprint must allow the actions below. EC2 read actions are needed so Terraform can look up the cluster VPC and workers security group when the network variables are left empty.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "elasticache:CreateReplicationGroup",
        "elasticache:DeleteReplicationGroup",
        "elasticache:ModifyReplicationGroup",
        "elasticache:ModifyReplicationGroupShardConfiguration",
        "elasticache:DescribeReplicationGroups",
        "elasticache:DescribeCacheClusters",
        "elasticache:DescribeCacheParameters",
        "elasticache:DescribeCacheParameterGroups",
        "elasticache:DescribeCacheSubnetGroups",
        "elasticache:DescribeEngineDefaultParameters",
        "elasticache:CreateSnapshot",
        "elasticache:DescribeSnapshots",
        "elasticache:AddTagsToResource",
        "elasticache:RemoveTagsFromResource",
        "elasticache:ListTagsForResource"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeVpcs",
        "ec2:DescribeSubnets",
        "ec2:DescribeSecurityGroups",
        "ec2:DescribeAvailabilityZones"
      ],
      "Resource": "*"
    }
  ]
}

Overview

Account & Organization

Clusters & Cloud

Source Control

Projects & Environments

Services

Deployment & CI/CD

Environment Variables & Secrets

Observability

Notifications

Networking & Advanced

Amazon ElastiCache for Valkey

Create it

Variables and outputs

Reference

Variables

Required

Credentials

Instance & topology

Security

Network

Maintenance & upgrades

Backups

Outputs

Lifecycle ignore_changes

Auth token

Required AWS IAM permissions

​Create it

​Variables and outputs

​Reference

​Variables

​Required

​Credentials

​Instance & topology

​Security

​Network

​Maintenance & upgrades

​Backups

​Outputs

​Lifecycle ignore_changes

​Auth token

​Required AWS IAM permissions

Create it

Variables and outputs

Reference

Variables

Required

Credentials

Instance & topology

Security

Network

Maintenance & upgrades

Backups

Outputs

Lifecycle ignore_changes

Auth token

Required AWS IAM permissions