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("...")
    .Mode(ClusterMode.Active)
    .TransientThreshold(TimeSpan.FromMinutes(20))
    .DefaultJobTimeout(TimeSpan.FromMinutes(1))
    .DefaultMaxRetryCount(3)
    .MaxMessageByteSize(256 * 1024)
    .IanaTimeZoneId("America/Sao_Paulo")
    .DataRetentionTtl(TimeSpan.FromDays(30))
    .DisablePriority(JobMasterPriority.VeryLow)
    .SetAsDefault();

Mode (Default: Active)​

Governs the operational state of the entire cluster.

  • Active — Standard operation. All scheduling and execution systems are enabled.
  • Migrating — Online migration mode. Held jobs and recurring schedules are continuously forwarded to a mandatory target Active cluster instead of being dispatched locally, while existing buckets drain out naturally. Set via MigrateTo(targetActiveClusterId) rather than Mode(...) directly — there's no way to enter Migrating without a target, since both are set together. See Migrating a Cluster.
  • 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].

DefaultMaxRetryCount (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.

DataRetentionTtl (Default: infinite)​

How long JobMaster keeps completed jobs, inactive recurring schedules, and cluster logs before purging them. Once the TTL elapses, records are removed in the next cleanup cycle.

config.DataRetentionTtl(TimeSpan.FromDays(30)); // purge after 30 days
  • Minimum when set: 10 minutes. Values between zero and 10 minutes are rejected at startup.
  • Zero or negative → equivalent to RetainDataForever().
  • Logs and job history are purged together to keep dashboards consistent (a failed job and its logs age out at the same time).
config.RetainDataForever(); // explicit no-purge (same as the default)

Instead of a hard delete, purged data can be moved to a dedicated archive cluster first — see Archiving.

DisablePriority​

Removes a priority level from this cluster entirely. Once disabled:

  • No execution bucket is created for that priority at startup.
  • Any job handler or static recurring schedule that resolves to the disabled priority throws at startup.
  • Scheduling a job at the disabled priority throws InvalidOperationException at the call site.
config.DisablePriority(JobMasterPriority.VeryLow);
config.DisablePriority(JobMasterPriority.Low);
warning

JobMasterPriority.Medium cannot be disabled — it is the default fallback for any handler that does not declare an explicit [JobMasterPriority] attribute.

You can also configure disabled priorities via JSON:

{
  "DisabledPriorities": ["VeryLow", "Low"]
}