Runner Fleets, Autoscaling, Docker Machine Migration, Kubernetes Runners, Ephemeral Workers, and Capacity Planning: Configuration, Design Choices, and Tradeoffs

1. Fleet design is a multi-objective control problem

There is no universally “best” executor or autoscaling policy. A pool that minimizes cost can violate feedback SLOs. A pool that reuses workers aggressively can weaken isolation. A fleet split into many specialized pools can improve least privilege but reduce utilization and increase operational overhead. The design must state which objective is primary for each trust/workload class.

Evidence still begins with CI_PIPELINE_SOURCE, CI_COMMIT_SHA, pipeline/job ID and requested tags, then follows the job through manager version/config, executor, worker identity, queue/provisioning timing and teardown.

2. Warm idle capacity versus cold-start cost

Warm workers spend money while idle but reduce queue latency during bursts. Cold-only fleets save idle cost but turn VM or node provisioning into user-visible delay. Measure the distribution of queue duration and machine/pod creation time; then define an idle policy by time window and workload criticality rather than copying a fixed number from another organization.

3. Single-use ephemeral versus worker reuse

For Fleeting-backed workers, max_use_count = 1 and capacity_per_instance = 1 make each instance a single-job lifecycle. That reduces cross-job residue and simplifies “trust reset” reasoning, at the cost of more provisioning and image/bootstrap work. Reuse raises utilization and lowers startup overhead, but increases the amount of cleanup you must trust.

4. Kubernetes versus VM autoscaling

Do not compare them only by raw startup time. Include skill ownership, failure domains, network policy, image provenance, cache topology and incident containment.

5. Centralized fleet versus specialized pools

A centralized pool improves utilization and operational consistency, but only when jobs have compatible trust and platform requirements. Specialized pools can isolate protected release jobs, Windows/macOS builds, GPU/device workloads, untrusted forks, high-memory builds or regulated workloads. Tags and runner protection are routing controls—not proof that the underlying worker boundary is secure.

6. Tags are capacity partition keys

unit_test:
  tags: [linux, untrusted]
  script: ./ci/test.sh

release_sign:
  tags: [linux, release-protected]
  rules:
    - if: '$CI_COMMIT_TAG'
  script: ./ci/sign.sh

These jobs should not merely have different labels; their eligible runners, credentials, network access and worker lifecycles should match the trust classification. Chapter 31 expands this into a full threat model.

7. Hard bounds versus adaptive targets

Hard controls such as max_instances, provider quota, concurrent and limit cap damage/cost. Soft controls such as idle policies target responsiveness. Treat “0 = unlimited” defaults carefully: current max_instances default is 0/unlimited, which is unsuitable as an unexamined production cost policy.

8. Job polling is capacity too

A fleet can have idle workers yet underperform because managers do not request jobs fast enough. request_concurrency defaults to 1. Current Runner guidance recommends increasing it for high-volume runners when long-poll bottlenecks are observed; adaptive request concurrency can tune within the configured ceiling. Record request metrics before changing the value.

9. High availability without shared-controller conflict

GitLab recommends at least two runner managers for fault tolerance in an autoscaled service model. That does not mean two Docker Autoscaler managers may control the same autoscaling group. Give managers the same logical job tags if needed, but separate provider autoscaling resources and bookkeeping ownership.

10. Upgrade strategy: canary, drain, observe, expand

1. Inventory manager and helper versions; record current config hashes.
2. Create or select a canary pool with a small percentage of representative jobs.
3. Validate configuration; Runner 19.3 adds a config lint command.
4. Pause/drain the canary manager where required and upgrade to a pinned version.
5. Run synthetic plus representative workload; compare queue, duration, errors, artifacts/cache and worker teardown.
6. Expand incrementally. Keep the prior package/image/chart and config as rollback material.

11. Docker Machine migration mapping

12. Decision table: choose the fleet deliberately

13. A simple cost envelope

For a VM pool, define a conservative hourly upper bound before rollout:

\[ C_{max/hour} = N_{max} \times C_{instance/hour} + C_{storage/network/cache} \]

This is intentionally simple; reserved/spot pricing, egress, cache/object storage and node sharing complicate the real number. The important control is that N_ is explicit and observable.

14. Tier and offering boundary

Runner executors, autoscaling, monitoring and the Kubernetes executor documented here are available across Free, Premium and Ultimate offerings. Cloud VM groups, Kubernetes clusters and provider credentials themselves are external infrastructure with their own cost and authorization. The core chapter never requires them.

Knowledge check

Official references and version notes

Documentation verification date: 2026-09-12. Current stable GitLab Runner patch verified for this chapter is 19.3.2 (tagged 2026-09-10). The Docker Machine executor was deprecated in GitLab 17.5 and is scheduled for removal as a supported feature in GitLab 20.0 (May 2027); GitLab directs users toward the Instance or Docker Autoscaler executors. Docker Autoscaler is GA and, together with the Instance executor, uses Taskscaler/Fleeting. A Docker Autoscaler configuration must have its own dedicated provider autoscaling resource and must not share that resource with another manager or another [[runners]] entry. The mandatory exercises in this chapter are local simulations and require no cloud account, runner registration token, privileged executor, or managed Kubernetes cluster. GitLab Runner 19.3.2 is the chapter baseline. Pin production upgrades to an explicitly tested patch and verify release notes rather than treating “latest” as a fleet policy.

• Executors — official reference.
• GitLab Runner autoscaling — official reference.
• Docker Autoscaler executor — official reference.
• Instance executor — official reference.
• Fleeting — official reference.
• Plan and operate a runner fleet — official reference.
• Advanced Runner configuration — official reference.
• Monitor GitLab Runner usage — official reference.
• Kubernetes executor — official reference.
• GitLab Runner Helm chart — official reference.
• Docker Machine executor — official reference.
• GitLab deprecations and removals — official reference.
• Runner troubleshooting — official reference.
• GitLab Runner changelog — official reference.
• GitLab Runner tags — official reference.

Current assumptions used in this chapter: Version-sensitive YAML, Runner/executor behavior, APIs, security features, policy controls, tiers, and deprecations must be verified against the exact GitLab, GitLab Runner, tool, and external-system versions used in production. Preserve the exact project/ref/SHA, compiled configuration, pipeline/job IDs, runner/tool versions, and external target evidence used for reproducible work.