Skip to main content

Cluster Configuration

These global settings define the default behavior for the entire cluster. Most can be overridden at the job or schedule level.

config.ClusterId("My-Cluster")
    .UsePostgresForMaster("...")
    .ClusterMode(ClusterMode.Active)
    .ClusterTransientThreshold(TimeSpan.FromMinutes(20))
    .ClusterDefaultJobTimeout(TimeSpan.FromMinutes(1))
    .ClusterDefaultMaxRetryCount(3)
    .ClusterMaxMessageByteSize(256 * 1024)
    .ClusterIanaTimeZoneId("America/Sao_Paulo")
    .SetAsDefault();

ClusterMode (Default: Active)​

Governs the operational state of the entire cluster.

  • Active — Standard operation. All scheduling and execution systems are enabled.
  • Passive — Maintenance mode. Jobs are accepted and persisted to the Master DB but never dispatched to workers.
  • Archived — Read-only. Scheduling throws an exception. The cluster is retained for historical data only.

TransientThreshold (Default: 10 minutes)​

The look-ahead window the Coordinator uses to onboard near-future jobs from the Master DB into Agent buckets.

  • Larger values reduce Master DB scan frequency — better for stable environments.
  • Smaller values reduce the window of orphaned work — better for dynamic environments like Kubernetes.
  • Maximum: 24 hours (enforced at startup).

DefaultJobTimeout (Default: 1 minute)​

Maximum time a single job is allowed to run before being forcefully terminated. Can be overridden per job with [JobMasterTimeout].

DefaultMaxOfRetryCount (Default: 3)​

How many times a failing job is retried before being moved to the Failed state. Can be overridden per job with [JobMasterMaxNumberOfRetries].

MaxMessageByteSize (Default: 128 KiB)​

Upper bound for serialized job payloads. Set this slightly below your transport provider's hard limit to account for metadata overhead. Pass -1 to disable the limit entirely (not recommended in constrained environments).

IanaTimeZoneId (Default: system local)​

The timezone used to interpret recurring schedules. In distributed clusters spanning multiple regions, set this explicitly (e.g., America/Sao_Paulo) to ensure consistent scheduling regardless of server location.