AWX in Action

Capacity, Forks, and the Math Behind Scheduling

Each instance has a calculated capacity, expressed in forks. To adjust how AWX calculates this, go to Instances, open the instance, and use the Capacity Adjustment slider. The slider doesn't set a fixed fork count; it controls how AWX blends the two capacity algorithms (memory-based vs CPU-based) for this instance. Since instances can belong to multiple groups, changing one instance's capacity affects every group it's part of.

Here's how the capacity system actually works:

AWX measures capacity in forks, not in jobs. A fork is one parallel connection to a managed host. AWX calculates an instance's total capacity using one of two algorithms:

• mem_capacity (default): about 1 fork per 100MB of memory, after reserving 2GB for AWX's own services.
• cpu_capacity: 4 forks per CPU core.

A background process called the Task Manager runs periodically. For each pending job, it computes the job's impact (roughly forks + 1 to account for the Ansible parent process), then finds an eligible instance with enough remaining capacity to absorb it. Remaining capacity is the instance's total capacity minus the impact of jobs currently running on it. AWX does not introspect actual memory or CPU usage on the host. It's bookkeeping, not real-time resource pressure. Running free or top on an execution node won't tell you why a job is queued.

Increasing fork counts generally speeds up jobs by adding parallelism, but it also raises memory usage on the execution node (each worker stays resident) and increases simultaneous load on the managed targets. The right value depends on the playbook and the targets, not on a single tuning knob.

One special case: if a job's impact exceeds every eligible instance's capacity, AWX will still schedule it on the instance with the highest capacity. Without this rule, oversized jobs would stay pending forever.

There are two modes you can use to set the capacity of an instance (in other words, the number of forks):

Memory capacity mode (mem_capacity): This is the default. AWX calculates capacity based on memory alone, allowing CPU to be overcommitted. This mode maximizes the number of forks when your jobs spend most of their time waiting on managed nodes (SSH connections, remote package installs, remote service restarts) rather than doing heavy local work on the execution node itself.

The algorithm used to calculate the number of forks in memory capacity mode is:

forks = (total_memory - memory_reserved) / memory_per_fork

Where:

• total_memory is the total memory available on the instance.
• memory_reserved is fixed at 2 GB, reserved for AWX's own services.
• memory_per_fork