Merged
Size
L
Change Breakdown
Feature80%
Config10%
Testing10%
#27527feat(core): Add Redis storage backend for instance registry (no-changelog)

Distributed n8n deployments can now track instances via Redis

Distributed n8n deployments can now track instances via Redis

A new Redis-backed storage backend replaces memory-only storage in the instance registry, enabling distributed n8n clusters to share instance registration data reliably.

Distributed n8n deployments previously lacked a shared storage mechanism for instance tracking. The existing memory-based storage worked only for single-instance setups—each node maintained its own separate registry, invisible to other instances. This made coordinated multi-instance deployments impossible.

The instance registry now supports a Redis storage backend alongside the existing memory option. Distributed deployments can store instance registrations, heartbeats, and state information in Redis, where all cluster members can read and write the same data. The implementation uses Lua scripts for atomic multi-key operations—registering an instance, reading all active registrations, cleaning up stale entries, and unregistering instances all happen atomically to prevent race conditions across nodes.

This matters for anyone running n8n across multiple servers or in a containerized environment. Load balancers and other coordination tools can now discover active n8n instances by querying the shared registry. The five-minute state TTL enables leadership handoff—if a primary instance fails, others can see which instances were last active before the failure.

The changes live in the @n8n CLI package, specifically within the instance-registry module and its storage layer.

View Original GitHub Description

Summary

Add Redis-backed storage for the instance registry module, enabling distributed n8n deployments to track instances via Redis.

  • Define 4 Lua scripts (REGISTER, READ_ALL, CLEANUP, UNREGISTER) as TypeScript constants for atomic multi-key Redis operations using {instance:} hash tags for cluster slot co-location
  • Implement RedisInstanceStorage with dedicated Redis client, Zod validation, non-blocking error handling, and 5s command timeout
  • Add unit tests (25 cases) covering all methods, error paths, and schema validation
  • Add 'instance-registry' log scope and 'registry(n8n)' Redis client type

Related Linear tickets, Github issues, and Community forum posts

Review / Merge checklist

  • PR title and summary are descriptive. (conventions)
  • Docs updated or follow-up ticket created.
  • Tests included.
  • PR Labeled with Backport to Beta, Backport to Stable, or Backport to v1 (if the PR is an urgent fix that needs to be backported)
© 2026 · via Gitpulse