ADR: hints process directive for executor-specific scheduling hints

[robsyme]

Summary

Architecture Decision Record proposing a new hints process directive with namespaced keys as a generic extension point for executor-specific scheduling hints.

First use case: AWS Batch consumable resources for license-seat-aware scheduling.

Options Evaluated

1. Dedicated consumableResources directive — too narrow, each executor feature would need its own directive
2. Overload resourceLabels — conflates metadata tags with scheduling behavior; resourceLabels uses replacement semantics in config overrides, so a sysadmin's cost-tracking labels would be wiped out if a user sets consumable resources (and vice versa)
3. New hints directive (recommended) — generic, extensible, namespaced keys, executors consume what they understand

Proposed Syntax

process runDragen {
    hints 'consumable-resource:my-dragen-license': 1
}

Ref: #5917, #6957

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for nextflow-docs-staging ready!

Name	Link
🔨 Latest commit	07feada
🔍 Latest deploy log	https://app.netlify.com/projects/nextflow-docs-staging/deploys/69dec0cec279ef0008111b8d
😎 Deploy Preview	https://deploy-preview-6960--nextflow-docs-staging.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[adamrtalbot]

See also Kubernetes Node Selectors and Node Affinity which perform a similar function: https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/

Indeed, the exisitng nodeLabel method could be ported to this directive.

[adamrtalbot]

Other related tickets I know of:

1. Ability to dedicate accelerator directive (GPU) over range #5570 (on-prem)
2. Support reservation when provisioning VM/ accelerators on Google Batch #4262 (GCP)

This may provide useful context in terms of use cases.

[bentsherman]

Related: WDL requirements and hints

[adamrtalbot]

#5850

[bentsherman]

Another use case: scheduling priority for AWS Batch: #6998

[pditommaso]

Thanks @robsyme for the thorough ADR. The hints directive is the right direction — we're all aligned on that. Here's a refined proposal for the naming, syntax, and validation semantics.

Key format: camelCase with optional dot-scoped categories

Keys use camelCase and support an optional dot-separated scope to group related hints into logical categories:

process runDragen {
    hints consumableResource: 'my-dragen-license'
    hints 'scheduling.priority': 10
    hints 'scheduling.provisioningModel': 'spot'
}

// nextflow.config
process {
    withName: 'runDragen' {
        hints = [
            consumableResource: 'my-dragen-license',
            'scheduling.provisioningModel': 'spot'
        ]
    }
}

This keeps simple hints flat (consumableResource) while letting related hints cluster under a shared scope (scheduling.priority, scheduling.provisioningModel) — readable without imposing structure where it's not needed.

Optional executor prefix for targeting

When a hint is specific to a given executor or platform, it can be prefixed with an executor/vendor namespace using slash notation:

hints 'aws/consumableResource': 'my-dragen-license'
hints 'seqera/scheduling.provisioningModel': 'spot'
hints 'k8s/scheduling.nodeSelector': 'gpu=true'

Full key format: [executor/][scope.]hintName

Unprefixed hints are "universal" — any executor that understands them can consume them. Prefixed hints are only consumed by the matching executor. This gives pipeline authors a way to be explicit when portability matters and specific when it doesn't.

Value parsing

Hint values are always strings or integers at the Nextflow level. Interpretation and parsing of values is delegated to the implementing executor. A value could be a simple literal:

hints 'scheduling.provisioningModel': 'spot'

Or it could use = as a conventional key-value separator when the executor needs structured content:

hints 'k8s/scheduling.nodeSelector': 'gpu=true'

This keeps the core directive simple (a Map<String, Object>) while giving executors the flexibility to define richer value semantics without burdening the Nextflow config parser.

Validation

Instead of silently ignoring unknown hints (as the current ADR proposes), we should validate against known hints to catch typos and misconfiguration:

• Unprefixed hints: Nextflow checks against a registry of known hint keys. An unknown key (e.g. scheduling.provisioningModle) produces a warning suggesting the closest match — similar to how we handle unknown directives today.
• Prefixed hints (e.g. aws/consumableResource): The target executor performs a strict check — an unrecognized key is an error, since the user explicitly declared the executor scope and a typo or unsupported hint should not pass silently.

This two-tier approach balances portability (a pipeline using unprefixed hints can run on executors that don't support them, with a warning) against correctness (a pipeline using executor-prefixed hints gets fast failure if the hint is wrong).

Accumulation vs. replacement semantics

Config overrides use replacement by default, consistent with how other map-type directives (resourceLabels, ext) work:

// This replaces all hints from the process definition
process {
    withName: 'runDragen' {
        hints = ['scheduling.provisioningModel': 'spot']
    }
}

For hints that support accumulation (i.e. adding to rather than replacing), use the + prefix on the key name:

// This adds a consumable resource while preserving existing hints
process {
    withName: 'runDragen' {
        hints = ['+consumableResource': 'another-license']
    }
}

Not all hints support accumulation — it only makes sense for hints that are inherently multi-valued (like consumableResource, where a process might need multiple license types). Scalar hints like scheduling.provisioningModel are single-valued by nature — using + on them should produce an error.

Initial hint catalog

For the first implementation, I'd suggest supporting at least:

Hint key	Value type	Accumulation	Executors	Use case
consumableResource	String or Map<String,Integer>	Yes	AWS Batch	License-seat-aware scheduling (#5917)
scheduling.provisioningModel	String ('spot', 'standard')	No	AWS Batch, Google Batch, Azure Batch	Spot/preemptible instance selection (#4262, #5850)
scheduling.priority	Integer	No	AWS Batch	Job scheduling priority (#6998)

As @adamrtalbot noted, K8s node selectors/affinity (#5570) are a natural future candidate (e.g. scheduling.nodeSelector).

Summary of changes vs. current ADR

Aspect	Current ADR	This proposal
Key format	Colon-separated (consumable-resource:name)	camelCase with optional dot scope (scheduling.provisioningModel)
Executor scoping	Implicit (executor picks what it knows)	Explicit optional prefix (aws/hint)
Unknown hints	Silently ignored	Warning (unprefixed) or error (prefixed)
Config override	Accumulation by default	Replacement by default, + prefix for accumulation