Gitpulse
Merged
Size
L
Change Breakdown
Feature80%
Maintenance15%
Config5%
#27731feat(core): Add instance registry service (no-changelog)

Instance Registry lets distributed n8n processes track each other

Instance Registry lets distributed n8n processes track each other
AF
afitzek
·Apr 14, 2026

Cluster operators can now see all registered n8n instances, their status, and version information through a new settings page — the foundation for multi-instance orchestration and leader election.

n8n deployments running multiple processes now have a way to discover and track each other. The new Instance Registry Service generates a unique identifier for each process on startup, registers it with a storage backend, and maintains a heartbeat every 30 seconds. In distributed mode, Redis becomes the shared registry; single-instance deployments use in-memory storage.

When an instance shuts down, it cleanly unregisters itself. The leader instance additionally runs a reconciliation cycle to remove stale members that failed to unregister properly — these cleanups happen in batches of 1000 to avoid Lua stack overflow in large clusters.

Administrators can view all registered instances at /settings/instance-registry, seeing each instance's key, host, type, role, version, and last-seen timestamp. The endpoint requires the orchestration:read scope and is gated behind the INSTANCE_REGISTRY feature flag.

This capability is part of a larger initiative to enable reliable distributed workflows, where the registry will support the proxy service and reconciliation cycle for execution routing.

View Original GitHub Description

Summary

Add the core InstanceRegistryService for the instance registry module, enabling n8n processes to register themselves, maintain heartbeats, and clean up on shutdown.

  • Backend selection: Automatically selects Redis storage in distributed mode (isMultiMain or queue mode) or in-memory storage for single-instance deployments, using lazy imports to avoid loading Redis dependencies when unnecessary
  • Instance lifecycle: Generates a unique UUID instance key on startup, registers with the storage backend, and runs a 30-second heartbeat interval that refreshes lastSeen while preserving registeredAt
  • Graceful shutdown: Stops the heartbeat timer and unregisters from storage via @OnShutdown() on the module, with error-resilient cleanup that never blocks shutdown
  • Public API: Exposes getAllInstances(), getLocalInstance(), getLastKnownState(), saveLastKnownState(), and storageBackend for use by the proxy service and reconciliation cycle
  • Redis storage stub: Adds a placeholder RedisInstanceStorage that will be replaced by #27527
  • Log scope: Registers instance-registry in the logging config
  • Tests: 20 unit tests covering backend selection, UUID format, registration, heartbeat resilience, shutdown safety, and all public API methods
  • REST Controller (GET /instance-registry): Exposes cluster info (registered instances + version mismatch detection) behind orchestration:read scope.
  • Settings UI page: New "Instance Registry" entry under Admin Settings that displays the raw cluster info JSON, accessible via /settings/instance-registry.
  • REST API client: Frontend API helper for fetching cluster info.

Here is a preview of the settings page:

<img width="1587" height="687" alt="image" src="https://github.com/user-attachments/assets/66e9b0ea-cd5c-402e-8461-1b36a9efb42c" />

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)
  • I have seen this code, I have run this code, and I take responsibility for this code.
© 2026 · via Gitpulse