Set up Redis service

Redis is an optional, backend cache solution that replaces the Zend Framework Zend_Cache_Backend_File, which Adobe Commerce uses by default.

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

Enable Redis

To enable Redis, update the following files:

Configure the service

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

cache:
  type: redis:<version>

For example, for a Commerce release and Cloud template that support Redis 7.2:

cache:
  type: redis:7.2

The example version is not universal. Actual default and supported service versions depend on your Adobe Commerce version, patch level, and current Cloud template. Verify the supported combination in System Requirements and the current project template.

Configure the service relationship

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

runtime:
  extensions:
    - redis

relationships:
  redis: "cache:redis"

The relationship key, redis, is the name used by the application to access the service. The value, cache:redis, consists of the service ID (cache) and service type (redis) defined in .magento/services.yaml.

Commit and deploy the changes

Add, commit, and push the configuration changes:

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

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

Verify the service relationship

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

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. Locate the redis relationship to identify the Redis connection details.

The following abbreviated example shows the redis 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"
      }
   ],
   "redis" : [
      {
         "host" : "redis.internal",
         "port" : 6379,
         "path" : null,
         "scheme" : "redis"
      }
   ]
}

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, use the following command to display only the Redis relationship:

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

For more information about service relationships, see Configure services.

Customize the Redis 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.

Using the Redis CLI

Assuming your Redis relationship is named redis, use the host and port returned by MAGENTO_CLOUD_RELATIONSHIPS to connect to Redis.

Connect to the environment with Redis installed and configured, and run the following command:

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

Example

redis-cli -h redis.internal -p 6379

Get the installed Redis version

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

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

redis-server -v

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

Troubleshooting Redis

See the following Adobe Commerce Support articles for help with troubleshooting Redis problems:

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 legacy Redis-oriented error code and message for the cache-clean step regardless of which service backs the cache relationship, so the wording does not indicate that Redis is installed.

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.