session.store.type: cluster) provides distributed session storage across multiple Orchestrator nodes using peer-to-peer clustering. Sessions are replicated across the cluster, enabling any node to serve any user’s request without sticky sessions.
Console terminology: In the Maverics Console, Orchestrator instances and
configuration delivery are managed through Deployments. When working directly
with YAML, configuration is managed as files delivered via the
-config flag or
MAVERICS_CONFIG environment variable.Prerequisite: Cluster sessions require a configured cluster. See the Clusters reference page for setup instructions including discovery, encryption, and data plane configuration.
Overview
When using the cluster session store, the Orchestrator shares session data across all nodes in the cluster using gossip-based membership and data-plane replication. Unlike local sessions, cluster sessions allow any node to handle any user’s request because session data is replicated cluster-wide. A cluster must be defined in the configuration before cluster sessions can be used.Use Cases
- Multi-node development and testing — test distributed session behavior without setting up external infrastructure like Redis
- Self-contained deployments — deployments that need shared sessions without depending on an external session store
Configuration
- Console UI
- Configuration
Console UI documentation is coming soon. This section will walk you
through configuring this component using the Maverics Console’s visual
interface, including step-by-step screenshots and field descriptions.
Configuration Reference
Cluster Store Fields
| Key | Type | Required | Description |
|---|---|---|---|
session.store.type | string | Yes | Must be "cluster" for cluster session storage |
session.store.cluster.name | string | Yes | Cluster name — must match a defined cluster in clusters[] |
Cookie and lifetime settings from the Local Sessions page also apply to cluster sessions. See the Local Sessions page for the full cookie settings, session lifetime, and deprecated fields reference tables.
Additional Fields
The following fields from the local sessions configuration reference also apply to cluster sessions:| Key | Type | Required | Description |
|---|---|---|---|
session.lifetime.maxTimeout | duration | No | Maximum session lifetime (duration string, e.g., 24h, 3600s) |
session.lifetime.idleTimeout | duration | No | Idle timeout — session expires after this period of inactivity (duration string) |
session.cookie.name | string | No | Session cookie name (default: maverics_session) |
session.cookie.domain | string | No | Cookie domain scope |
session.cookie.disableSecure | bool | No | Allow the session cookie over unencrypted HTTP (default: false) |
session.cookie.disableHTTPOnly | bool | No | Allow client-side script access to the session cookie (default: false) |
Troubleshooting
- Cluster sessions not working — cluster sessions require the
experimental.clustersfeature flag and a valid cluster definition. Verify that your cluster is configured and that thesession.store.cluster.namematches a defined cluster. - Sessions not shared across nodes — ensure all nodes are members of the same cluster and that the data plane is configured correctly. Check Orchestrator logs for cluster membership and replication errors.
- Cookie domain issues — if sessions are lost when navigating between subdomains, set
session.cookie.domainto the parent domain (e.g.,.example.com).