Deviqon Labs
News13 Oct 2025

Laravel/OctoberCMS and Redis Cluster Integration

A step-by-step technical guide to correctly configuring Laravel 12 with a Redis Cluster on Kubernetes, addressing common misconfigurations that cause silent fallbacks and authentication failures.

RR
Robert RotterDeviqon Labs
Share
Laravel/OctoberCMS and Redis Cluster Integration

Redis Cluster Integration with Laravel 12 / OctoberCMS v3 (phpredis driver)


Running Redis Cluster on Kubernetes with Laravel 12 / October CMS v3 isn’t straightforward. Several subtle misconfigurations make it silently fall back to single-node mode or fail authentication. Below is the final working configuration, followed by the gotchas and optional advanced settings that solve every related error.

Final Working Configuration

Environment Variables (.env)

1REDIS_CLIENT : "phpredis" (default value)
2REDIS_PORT : "6379" (default value)
3CACHE_DRIVER : "redis"
4SESSION_DRIVER : "redis"
5SESSION_CONNECTION : "session"
6REDIS_CLUSTER_SERVERS : "redis-cluster-0.redis-cluster-headless.redis.svc.cluster.local:6379,redis-cluster-1.redis-cluster-headless.redis.svc.cluster.local:6379,..."
7REDIS_PASSWORD : "your password"
8REDIS_CACHE_DB: "1"
9REDIS_SESSION_DB: "2"

Database Configuration (config/database.php)

1'redis' => [
2 'client' => env('REDIS_CLIENT', 'phpredis'),
3 'options' => [
4 'cluster' => env('REDIS_CLUSTER', 'redis'),
5 'prefix' => env('REDIS_PREFIX', Str::slug(env('APP_NAME', 'laravel'), '_').'_database_'),
6 'password' => env('REDIS_PASSWORD')
7 ],
8 'clusters' => [
9 'default' => array_map(function ($server) {
10 [$host, $port] = explode(':', $server);
11 return [
12 'host' => $host,
13 'password' => env('REDIS_PASSWORD'),
14 'port' => $port
15 ];
16 }, explode(',', env('REDIS_CLUSTER_SERVERS', '127.0.0.1:6379'))),
17 ],
18]

How to verify

1php artisan tinker
2>>> config('database.redis.options.cluster')
3=> "redis"
4>>> Redis::connection()->client()->info()['cluster_enabled']
5=> "1"

If cluster_enabled returns 1, cluster mode is active.

Things to look out for

“cluster = redis” + phpredis and don't try using REDIS_HOST

Laravel switches to Redis cluster (in config/database.php) only when :

1'client' => 'phpredis',
2'options' => ['cluster' => 'redis']

If either is missing (or cached), Laravel falls back to 127.0.0.1:6379.

Additionally: Don’t try setting REDIS_HOST to a single cluster service or point to a node via headless service (e.g. redis-cluster.redis.svc.cluster.local). phpredis cluster discovery won’t work that way, it must receive the full node list through the clusters array.

Fix: Always define cluster nodes via your own REDIS_CLUSTER_SERVERS and make sure you clear configs:

1php artisan config:clear && php artisan cache:clear

"clusters" block must be defined

Laravel expects (in config/database.php) all cluster nodes under :

1'redis.clusters.default/cache/session'

Each node requires a host + port (typically your Redis StatefulSet DNS entries).

remove "default" and "cache" single-node blocks

If default or cache arrays exist under redis, Laravel ignores the cluster configuration and connects to 127.0.0.1.

Fix: Delete them entirely, only clusters should remain.

the undocumented final fix, "password" in options

Even when cluster nodes and credentials were correct, phpredis failed during cluster discovery with:

1RedisClusterException: Couldn't map cluster keyspace using any provided seed

This happens because phpredis ignores per-node passwords when creating a Redis cluster instance. Laravel never passes a global password, so authentication fails before the keyspace map can be fetched.

Fix:

Add the password at the top level in options, applied to all cluster connections:

1'redis' => [
2 …
3 'options' => [
4 …
5 'password' => env('REDIS_PASSWORD'),
6 …
7 ],

Reference: phpredis #1533 undocumented in Laravel or OctoberCMS.

separate cache and session

1REDIS_CACHE_DB: "1"
2REDIS_SESSION_DB: "2"

Use different redis index (db) to separate CACHE and SESSION and allow one to be flushed without the other.

bonus / optional settings

For production deployments, you can further tune Redis Cluster connectivity and performance:

1'redis' => [
2 'client' => env('REDIS_CLIENT', 'phpredis'),
3 'options' => [
4 'cluster' => env('REDIS_CLUSTER', 'redis'),
5 'prefix' => env('REDIS_PREFIX', Str::slug(env('APP_NAME', 'laravel'), '_').'_database_'),
6 'password' => env('REDIS_PASSWORD'),
7 'replication' => true,
8 'persistent' => true,
9 ],
10 'clusters' => [
11 'default' => array_map(function ($server) {
12 [$host, $port] = explode(':', $server);
13 return [
14 'host' => $host,
15 'password' => env('REDIS_PASSWORD'),
16 'port' => $port,
17 'persistent' => true,
18 'scheme' => env('REDIS_SCHEME', 'tcp'),
19 'database' => env('REDIS_CACHE_DB', 0),
20 'read_write_timeout' => 30,
21 ];
22 }, explode(',', env('REDIS_CLUSTER_SERVERS', '127.0.0.1:6379'))),
23
24 'cache' => array_map(function ($server) {
25 [$host, $port] = explode(':', $server);
26 return [
27 'host' => $host,
28 'password' => env('REDIS_PASSWORD'),
29 'port' => $port,
30 'persistent' => true,
31 'scheme' => env('REDIS_SCHEME', 'tcp'),
32 'database' => env('REDIS_CACHE_DB', 0),
33 'read_write_timeout' => 30,
34 ];
35 }, explode(',', env('REDIS_CLUSTER_SERVERS', '127.0.0.1:6379'))),
36
37 'session' => array_map(function ($server) {
38 [$host, $port] = explode(':', $server);
39 return [
40 'host' => $host,
41 'password' => env('REDIS_PASSWORD'),
42 'port' => $port,
43 'persistent' => true,
44 'scheme' => env('REDIS_SCHEME', 'tcp'),
45 'database' => env('REDIS_SESSION_DB', 0),
46 'read_write_timeout' => 30,
47 ];
48 }, explode(',', env('REDIS_CLUSTER_SERVERS', '127.0.0.1:6379'))),
49 ],
50]

These options improve socket reuse, reduce connection overhead, and enable replica reads for large cluster deployments.

results

After applying these fixes, OctoberCMS v3 / Laravel 12 connected cleanly to a 6-node Redis Cluster, distributed cache operations correctly, and eliminated all:

1Connection refused
2RedisClusterException: Couldn't map cluster keyspace using any provided seed
3MOVED

By implementing this global password directive and adhering to the checklist, you ensure your infrastructure operates as designed. If your project faces a unique architectural challenge, our senior specialists are ready to help.

Contact us to discuss your project.