Set up Valkey service

Valkey is an optional backend cache solution for Adobe Commerce on cloud infrastructure. Valkey is required when you override the default cache configuration on Adobe Commerce 2.4.9 and later, or on patch releases later than 2.4.5-p16, 2.4.6-p14, 2.4.7-p9, and 2.4.8-p4.

Use the following instructions for service setup on Pro Integration environments and Starter environments, including the master branch.

Configure Valkey

To replace Redis with Valkey, update the following files:

Configure the service

In .magento/services.yaml, replace the Redis service definition with a Valkey service definition. Replace <version> with a Valkey version supported by your Adobe Commerce version and current Cloud template.

cache:
  type: valkey:<version>

Example

cache:
  type: valkey:8.0

The example version is not universal. Actual default and supported service versions depend on your Adobe Commerce version and current Cloud template. Use the version specified by the current project template. See Configure services for more information.

Do not assume that cache and session data persist when you change the type value from redis:<version> to valkey:<version>, even when you keep the same service ID. Treat the migration as creating a fresh cache: existing cache and session data is not guaranteed to be preserved, and users are logged out after the migration completes.

Configure the service relationship

In .magento.app.yaml, configure the relationship between the application and the Valkey service:

relationships:
  valkey: "cache:valkey"

The relationship key, valkey, is the name used by the application to access the service. The value, cache:valkey, references the service ID and service type defined in .magento/services.yaml.

runtime:
     extensions:
       - redis

Commit and deploy the changes

Add, commit, and push the configuration changes:

git add .magento/services.yaml .magento.app.yaml
git commit -m "Enable Valkey service"
git push origin <branch-name>

After the deployment completes, verify that the Valkey service relationship is available.

Customize the Valkey configuration

For cache, session, L2, and replica-connection recommendations, see Best practices for Valkey and Redis service configuration in the Implementation Playbook Best Practices Guide.

Verify the service relationship

To display the decoded MAGENTO_CLOUD_RELATIONSHIPS object, run the following command from an application container after deploying the configuration:

Use SSH to connect to the remote Cloud environment, then run:

echo "$MAGENTO_CLOUD_RELATIONSHIPS" | base64 -d | json_pp

The command displays all configured service relationships. To identify the Valkey connection details, locate the valkey relationship.

Example output

The following abbreviated example shows the valkey relationship. It is not a universal schema.

{
   "database" : [
      {
         "host" : "database.internal",
         "port" : 3306,
         "path" : "main",
         "scheme" : "mysql"
      }
   ],
   "opensearch" : [
      {
         "host" : "opensearch.internal",
         "port" : 9200,
         "path" : null,
         "scheme" : "http"
      }
   ],
   "valkey" : [
      {
         "host" : "valkey.internal",
         "port" : 6379,
         "path" : null,
         "scheme" : "valkey"
      }
   ]
}

The output varies by environment and service configuration. Do not hard-code hostnames, ports, IP addresses, cluster names, service versions, usernames, or passwords from this example. Use the values returned by MAGENTO_CLOUD_RELATIONSHIPS in the target environment.

If jq is available, display only the Valkey relationship:

printf '%s' "$MAGENTO_CLOUD_RELATIONSHIPS" \
  | base64 -d \
  | jq '{valkey: .valkey}'

For more information about service relationships, see Configure services.

Using the Valkey CLI

Assuming your Valkey relationship is named valkey, use the host and port returned by MAGENTO_CLOUD_RELATIONSHIPS to connect to Valkey:

valkey-cli -h <host> -p <port>

Example

valkey-cli -h valkey.internal -p 6379

Get the installed Valkey version

valkey-cli -h <host> -p <port> info | grep version

valkey_version:<installed-version>
gcc_version:<gcc-version>

valkey-server -v

Valkey server v=<installed-version> ...

Troubleshooting Valkey

Cache-clean errors reference Redis on a Valkey-configured cache

A pre-deploy cache-clean failure can display error code [107] (clean-redis-cache) and a Connection to Redis message even when the cache service is configured as Valkey. ece-tools uses this error code and message for the cache-clean step regardless of whether the backing cache service is Redis or Valkey.

If the underlying error is a DNS failure, such as Name or service not known for the relationship host, the deploy step ran before the service relationship was available, or the relationship name in .magento.app.yaml does not match the service ID in .magento/services.yaml. See Verify the service relationship.