Before diving into specifics, it’s worth being precise about which machine this whole topic is actually about.

The controller as the coordinating brain

As covered elsewhere in the broader world of Jenkins, the controller is the central machine that schedules jobs, tracks build history, serves the web interface, and coordinates every agent in the fleet — while the actual heavy lifting of compiling and testing code happens out on separate agent machines. Controller sizing is specifically about ensuring this one central, coordinating machine has enough memory, processing power, and storage to keep doing its job smoothly as demand on it grows.

Why this is a distinct concern from agent capacity

It’s tempting to assume that adding more build agents automatically solves any capacity problem, but the controller itself bears a real, separate load — tracking every queued and running build, holding build history in memory, rendering the web dashboard for every user, and coordinating communication with every single connected agent. This load grows with the number of jobs, builds, and agents in the fleet, regardless of how much raw compute power the agents themselves have.

Neglecting this specific concern leads to a very particular, very disruptive kind of failure.

The problem of a single point of coordination becoming a bottleneck

Because every single pipeline in an organization depends on the same one controller to schedule and coordinate its work, an under-resourced controller doesn’t just slow down one team’s builds — it can slow down or even destabilize the entire organization’s ability to build and deploy software at once, since everyone shares that same central dependency.

The unique risk of a shared, unscaled dependency

Unlike an individual agent, which can simply be replaced or scaled out if it’s overwhelmed, a Jenkins controller traditionally runs as a single instance — meaning its capacity is a hard ceiling on the entire installation’s usable throughput until it’s deliberately resized, migrated to more capable hardware, or restructured into a different architecture entirely.

Capacity planning as a way to stay ahead of growth

Because organizations rarely stay the same size, deliberately planning controller capacity ahead of anticipated growth — rather than reacting only after performance visibly degrades — keeps the controller from ever becoming the invisible ceiling silently limiting how fast an entire engineering organization can actually deliver software.

Understanding exactly what consumes each type of resource is the foundation for sizing a controller correctly.

Memory: the controller’s working attention span

The controller keeps a great deal of active state in memory — details about every currently queued and running build, cached information about job configurations, and data supporting the web dashboards being actively viewed. As the number of jobs, concurrent builds, and active users grows, memory demand grows right alongside it.

CPU: the controller’s processing speed

Processing power is consumed by the constant background work of evaluating which jobs are ready to run, rendering web pages for every visitor, and running the logic contributed by every installed plugin — a controller with many active plugins and a busy scheduling workload needs meaningfully more processing capacity than a lightly used instance with only a handful of jobs.

Disk storage: the controller’s growing memory of the past

Unlike memory and processing power, which reflect current, active load, disk storage accumulates over time — every build’s console log, every archived artifact, and every job’s configuration history adds up, meaning storage needs tend to grow steadily even if the controller’s day-to-day active workload stays perfectly flat.

Understanding the internal mechanics behind resource consumption clarifies why certain usage patterns hit the controller harder than others.

The scheduling loop and its constant background cost

At the heart of the controller’s ongoing work is a continuous scheduling loop, constantly evaluating which queued jobs can now be matched to an available agent, as described in the earlier discussion of node labels — this loop runs continuously in the background, and its cost scales with how many jobs are simultaneously queued and how many agents exist to evaluate against.

sequenceDiagram
    participant Q as Build Queue
    participant C as Controller
    participant Mem as In-Memory State
    participant A as Agents
    Q->>C: New job queued
    C->>Mem: Track job state in memory
    C->>C: Evaluate scheduling against all agents
    C->>A: Assign job when a match is found
    A-->>C: Report build progress and completion
    C->>Mem: Update job state, eventually persist to disk
        

Plugin overhead as a hidden, cumulative cost

Every installed plugin can add its own background processing, its own memory usage, and its own contribution to page rendering time — a controller with dozens of active, feature-rich plugins genuinely needs more headroom than an otherwise identical controller running a lean, minimal plugin set, even with the exact same number of jobs.

How build history and logs accumulate in memory and on disk

Every completed build’s metadata and console log needs to be written to disk, and depending on configuration, a meaningful amount of recent build data may also be cached in memory to make the dashboard feel responsive — a job history that’s never trimmed can quietly grow this footprint over months and years, adding real, ongoing memory and disk pressure that’s easy to overlook.

Following a single build’s journey through the controller’s own resources shows exactly where load actually accumulates.

What flows through the controller versus what stays on the agent

The bulk of a build’s own heavy processing — compiling code, running tests — happens entirely on the agent, and only a comparatively small stream of status updates and console output flows back to the controller. However, at very high concurrency, even this comparatively modest per-build load adds up to something genuinely significant for the one central machine handling every build at once.

Different sources of load stress a controller in genuinely different ways, and recognizing which is dominant matters for sizing correctly.

Diagnosing which type of load is actually dominant

Because these load types stress different resources in different ways, correctly diagnosing which one is dominant in a given organization — a job-count-heavy instance versus a concurrency-heavy one versus a UI-traffic-heavy one — is essential before deciding whether the right fix is more memory, more processing power, or a different architectural approach entirely.

Rather than guessing, a structured approach to sizing produces far more reliable, defensible results.

Step one: establish a genuine current baseline

Before planning for future growth, it’s essential to understand the controller’s current actual resource usage under real, everyday load — not its theoretical maximum capability, but what it genuinely consumes during a typical busy day, providing the honest starting point every further projection builds from.

Why headroom matters more for a controller than for an ordinary agent

Because there’s only ever one controller coordinating the entire fleet, running it consistently near its resource limits leaves no margin at all for an unexpected spike — a single unusually busy release day, an unplanned surge in headcount — whereas an individual overloaded agent can simply be supplemented by adding another one alongside it.

Different approaches to sizing a controller each carry their own genuine advantages and costs.

The cost of under-sizing versus the cost of over-sizing

While over-sizing wastes some infrastructure budget, under-sizing a shared, single-instance controller risks a genuinely organization-wide productivity slowdown affecting every team simultaneously — for most organizations, this asymmetry means erring somewhat toward generous sizing is the more defensible default, provided it’s paired with genuine, ongoing monitoring rather than treated as a substitute for it.

Because the controller holds so much sensitive material, its capacity and availability also carry real security weight.

Availability as a security property, not just a performance one

An overloaded, unresponsive controller isn’t just inconvenient — it can prevent legitimate security processes, such as an urgent patch deployment or a critical incident-response pipeline, from running when they’re needed most, which is precisely why availability itself is sometimes treated as a genuine security concern, not merely an operational one.

Protecting the controller’s disk from sensitive data sprawl

Because build logs and archived artifacts accumulate on the controller’s disk over time, and because these can sometimes inadvertently contain sensitive information if not carefully managed, capacity planning intersects directly with data governance — retention policies that regularly prune old, unnecessary build data serve both a storage-capacity purpose and a security purpose at once.

Restricting who can change controller-level resource settings

Because certain controller-level settings — such as the number of executors running directly on the controller itself, a practice generally discouraged for security reasons — can affect both performance and security posture, changes to these settings deserve the same restricted access discussed for system configuration elsewhere in this guide.

Given how consequential controller health is for an entire organization, genuine ongoing monitoring is essential, not optional.

The core metrics worth watching continuously

A small set of well-chosen metrics gives an administrator early warning of a developing capacity problem long before it becomes a visible, organization-wide slowdown, provided they’re actually watched regularly rather than checked only after complaints start arriving.

graph TD
    A[Controller Metrics Collected] --> B[Memory Trend]
    A --> C[Queue Depth]
    A --> D[Disk Growth Rate]
    A --> E[Page Response Time]
    B --> F[Capacity Dashboard]
    C --> F
    D --> F
    E --> F
    F --> G[Team Plans Proactive Resize]
        

Alerting on trend, not just threshold

Beyond a simple fixed alert threshold, watching the trend line of memory and disk usage over weeks and months often provides earlier, more actionable warning than waiting for a single hard limit to be crossed — a steadily climbing trend gives an organization time to plan a deliberate resize, rather than reacting to a sudden crisis.

A handful of recurring design choices separate a well-managed controller from one perpetually on the edge of trouble.

Pattern: keep the controller lean, push work to agents

A well-managed setup deliberately minimizes work performed directly on the controller itself — running zero or minimal build executors there, and keeping installed plugins to genuinely necessary ones — reserving the controller’s own resources almost entirely for its core coordinating role.

Anti-pattern: treating the controller as just another build machine

Running actual build workloads directly on the controller, in addition to its coordinating duties, both wastes its scarce resources on work that could run elsewhere and, more seriously, exposes the controller itself to whatever risks that build workload carries — a genuinely risky mixing of two very different roles.

Pattern: proactive retention and cleanup policies

As discussed in Chapter 9, defining and enforcing a sensible retention policy for build history and artifacts keeps disk usage growth predictable and bounded, rather than allowing it to accumulate indefinitely until it becomes an urgent, disruptive problem.

These are the lessons most administrators learn only after their controller has already caused a genuinely disruptive slowdown.

Common mistake: sizing once and never revisiting it

A controller sized correctly for an organization of a hundred engineers can become badly undersized once that organization grows to five hundred, and treating the initial sizing decision as permanent, rather than something to periodically revisit, is one of the most common paths to an eventual, disruptive capacity crisis.

Common mistake: ignoring plugin sprawl as a capacity factor

It’s easy to focus purely on job and build counts when planning capacity, while overlooking how a gradually growing collection of installed plugins, each adding its own overhead, can meaningfully shift a controller’s genuine resource needs over time even if job volume itself has stayed roughly flat.

At a certain scale, sizing a single controller more generously stops being enough, and a different architectural approach becomes necessary.

Recognizing when vertical sizing has reached its limit

Simply giving a single controller more memory and processing power, a practice sometimes called vertical scaling, works well up to a point, but very large organizations eventually reach practical or cost-effective limits on how large a single machine can reasonably be made, signaling that a different approach is needed.

Splitting into multiple, separately managed controllers

A common approach beyond a single controller’s practical limits is dividing the organization’s pipelines across multiple, independently managed Jenkins controllers — for example, one per major business unit or region — trading some centralized simplicity for genuinely independent capacity that scales separately for each part of the organization.

Maintaining consistency across multiple controllers

When an organization does split into multiple controllers, applying the same configuration-as-code principles discussed elsewhere in this guide across all of them helps preserve a consistent security posture and consistent tooling, even though the pipelines themselves are no longer coordinated by one single, central instance.

Seeing how different kinds of organizations approach controller sizing makes the concept concrete.

A common thread across all four examples

In every case, the organization treats controller capacity as something requiring deliberate, ongoing attention rather than a one-time setup decision, recognizing that the controller’s health directly determines how smoothly every single team’s pipelines actually run.

Straightforward answers to the questions almost every newcomer to controller sizing asks.

Not necessarily — as explained in Chapter 2, general Jenkins slowness can just as easily stem from an overloaded controller, and adding more agents in that case can actually make things worse by giving the controller even more machines to coordinate.

Yes — as discussed in Chapter 6, simply having a very large number of configured jobs adds baseline memory and disk overhead from Jenkins tracking their configuration and history, independent of how often they actually run.

This is a recognized anti-pattern, discussed in Chapter 11 — running builds directly on the controller competes with its coordinating work and exposes it to unnecessary risk; adding a dedicated agent is the recommended approach instead.

There’s no single universal number, but as covered in Chapter 7 and Chapter 8, sizing meaningfully above projected minimum needs is generally worth the modest extra cost, given how disruptive an under-provisioned, single-instance controller can be.

As discussed in Chapter 13, this typically becomes worth considering once vertical sizing of a single controller reaches practical or cost-effective hardware limits, often at a very large organizational scale.

Yes — as explained in Chapter 4 and Chapter 12, each installed plugin can add its own memory usage and processing overhead, meaning a controller with many active plugins genuinely needs more resource headroom than a lean, minimal setup.

Controller sizing and capacity planning addresses a concern that’s easy to overlook precisely because it’s separate from the more visible world of build agents: the single, central machine coordinating an entire organization’s pipelines has its own real, finite limits on memory, processing power, and disk storage, driven by job counts, build concurrency, user traffic, and plugin overhead. Because every team depends on this same shared controller, an under-resourced instance doesn’t cause an isolated problem — it becomes an organization-wide bottleneck. Sizing it well requires establishing a genuine usage baseline, projecting future growth deliberately, building in real headroom, and reviewing that plan on an ongoing basis rather than treating it as a decision made once and forgotten. For organizations that eventually outgrow what a single, generously sized controller can reasonably provide, splitting into multiple independently managed controllers becomes the next natural step. Handled with this kind of ongoing discipline, the controller remains the quiet, dependable coordinating brain behind an entire organization’s delivery — rather than becoming the invisible ceiling silently limiting how fast that organization can actually move.