RFC: Range-based capability matching for amount requirements

[oehmends]

• Pull Request: feat: RFC for range-based capability matching for amount requirements #135
• Discussion Thread(s):
  • Related AWS Support case: Fleet compatibility check matches step requirements against fleet minimum vCPU instead of maximum, forcing users to maintain separate fleets per resource tier.

Description

The OpenJD specification defines the data model for step amount requirements (<AmountRequirement> with min/max) and worker capabilities, but does not define how scheduling systems should match requirements against hosts or fleets that advertise a range of capabilities (e.g., vCPU min–max).

This gap has led to implementations that match only against the lower bound of a capability range. For example, a fleet configured with vCPU range 64–128 is rejected for a step requiring 96 vCPUs, because the check compares 96 against the fleet minimum (64) rather than the fleet maximum (128).

This forces users into one of two bad workarounds:

1. Fleet proliferation — Create separate fleets for each vCPU/memory tier (64, 96, 128), each requiring its own service quotas, monitoring, and configuration.
2. Over-provisioning — Set the fleet minimum to the highest value any job might need, wasting resources on smaller jobs.

Both defeat the purpose of flexible fleet sizing and increase operational overhead.

This RFC proposes normative language defining that a fleet with capability range [C_min, C_max] should be considered compatible with a step requirement if there exists any value in the fleet's range that satisfies the requirement. In practice: the fleet's maximum determines whether it can meet the step's minimum requirement.

Roles

Role	User
Proposed By	@oehmends
Author(s)	@oehmends

Workflow

• Tracking issue created (label: rfc/proposed)
• RFC pull request submitted and ready for discussion (label: rfc/exploring)
• Last call for comments (labels: rfc/exploring and rfc/final-comments)
• Accepted and merged RFC pull request (label: rfc/accepted-future)
• Green-light for inclusion in a draft specification, and the author is creating and iterating on pull requests (label: rfc/accepted-draft)
• Pull requests are merged in to a draft specification (label: rfc/accepted-staged)
• Officially published in a non-draft revision of the specification (label: rfc/released)

Please close this tracking issue when the proposal enters the Released stage of the process.

Open Points

• Should the spec define matching semantics only for amount capabilities, or also extend to attribute capabilities with range-like semantics?
• Should the spec mandate a specific instance selection strategy (e.g., smallest sufficient), or leave that as an implementation detail?

---

The author is responsible to progress the RFC according to this checklist, and
apply the relevant labels to this issue.

[mwiebe]

Hi @oehmends thanks for creating this and starting the discussion!

Open Job Description currently has no requirements on fleets, only on hosts. It specifies matching purely at a host level, and lets implementers choose how they map that onto fleets. I double-checked this by scanning the repo that includes all the RFCs and wiki spec documents:

$ git grep -i fleet
rfcs/0001-task-chunking.md:large, each chunk takes long to process and cannot be load balanced across a larger fleet

Open Job Description on Hosts

The part of the template spec about how tasks can be matched with hosts is in the <HostRequirements> section, where it says "This entity is used by the template author to describe the requirements on Worker host and/or render manager's available capabilities that must be satisfied for the Task(s) of the Step to be scheduled to the host."

A host has a single value for capabilities, it has a specific amount of RAM, count of vCPUs, etc. This means that, given a host, it's a binary yes/no question whether the task can be run on that host. Does the host satisfy every item in hostRequirements? Then the task can run there.

Generalizing to Fleets

Now we need to generalize this per-host filter to fleets. There are more than one way it can generalize, I will present two examples.

One kind of fleet is descriptive: we take a collection of hosts, and the fleet ranges are the min/max of all its hosts. Even in this simple case, the behavior isn't intuitive before you get into the details. Let's say you have two hosts in a fleet: one with 16 CPUs and 8GB RAM, and another with 2 CPUs and 64GB of RAM. The fleet has ranges 2-16 CPUs and 8-64 GB RAM. So, should a scheduler assign a job requests both 16 CPUs and 64GB RAM to this fleet? If it does, there will be no host available to run the job, and the job could sit in a "waiting" or similar status indefinitely.

Deadline Cloud is using Auto scaling groups (ASGs) as the basis for its service-managed fleets. In an ASG, you configure ranges of acceptable host properties, or lists of instance types. When you need a host, you increase the target capacity of the ASG. What this means is that it's always possible that new hosts it gives you are at the minimum values for every requirement. Let's say the fleet starts with 0 workers, and you submit a job with one task that requires the maximum values for the fleet capabilities. With some dice-rolling, the ASG provides a minimum-spec worker, and now the fleet has enough capacity to handle all available work. But, that worker is not able to run the job.

Impact on the Spec

I think the behavior you're suggesting fleets is a great design decision for a particular system, but the above two examples are also good and wouldn't be compliant if we required that in Open Job Description. Therefore I'd rather not add something about fleets to the specification, but focus the spec on increasing expressive features about job structure. Fleets should be the implementer's choice - given the primitives they have to work with, how do they map the host-level binary decision to range-based fleet decisions?

For Deadline Cloud, this is a feature request for something that does work the way you suggest, and as part of the Deadline Cloud team, I'm happy to chat more about options in that context.

Thanks,
Mark

p.s. Our idea for the "Discussion Threads" in the template was to link to informal discussion in https://github.com/OpenJobDescription/openjd-specifications/discussions. Happy to engage here, but I find the more formal structure gets in the way of exploring ideas when you're starting.

[oehmends]

Hi @mwiebe, thanks for the detailed response — really appreciate you taking the time to walk through the host-level vs fleet-level distinction.

Your examples make the ambiguity clear. The descriptive fleet case (16 CPU/8GB + 2 CPU/64GB) is a great illustration of why naive range overlap does not work when capabilities are multi-dimensional and not all combinations exist. And the ASG point about min-spec instances being rolled is a real operational concern I had not fully considered.

If my understanding is correct, the spec intentionally stays at the host level (binary: does this host satisfy the step?) and leaves fleet-level decisions — like how to map a range-based fleet config to that binary check — entirely to the implementer. That makes sense as a spec boundary.

Where it gets painful on the Deadline Cloud side is the operational reality: if I want to offer my users 64, 128, and 192 vCPU options, I currently need three separate fleets with fixed min values, each with its own service quotas. A single fleet with a range would be the natural solution, but the current matching logic prevents that. The workaround works, but it scales poorly — especially when you factor in memory as a second dimension.

I would love to continue this as a Deadline Cloud feature discussion. From my perspective, the ideal behavior would be: when Deadline Cloud knows it can provision an instance that satisfies the step (because the ASG config allows it), it should consider the fleet compatible and provision accordingly — rather than conservatively matching against the fleet minimum. The ASG already has the instance type list and knows what it can deliver.

Happy to move this to Discussions or wherever makes sense. And happy to close the RFC/PR if the consensus is that this belongs purely on the Deadline Cloud side. Thanks again, Mark.