Resource class fallbacks across CircleCI cloud and self-hosted runners
V

Vijay Pandian
The problem
Today each job names exactly one resource class. When that class is out of capacity, degraded, or its provider has an incident, jobs sit in the queue even while other capacity is healthy. The only workaround is editing
resource_class
in every affected repo mid-incident, then reverting it all afterwards.- Cloud and self-hosted capacity can't back each other up. A runner only takes jobs that name its class.
- When a runner fleet scales too slowly for a spike, or its cluster goes down, those jobs just wait.
- Platform teams can't plan for this in CircleCI or set it once for the whole org.
The idea
- Having the ability to list fallback resource classes on a job, tried in order, each opening after a set wait, so the job starts wherever room opens first.
- Fallbacks could be CircleCI cloud classes or your own runner classes, so both act as one pool.
- Having the ability to set this once for the whole org, in the UI, API, or Terraform, so every job asking for a class follows its rule with no config change, even in repos nobody has touched in months.
Example: job-level fallbacks in config.yml
*Proposed syntax only. The
placement
key doesn't exist today.*- build: a Docker job that asks foracme/k8s-build, a self-hosted container runner class, with noplacementkey. An org rule can still give it fallbacks, as in the Terraform example.
- test: a Docker job that asks formedium. If it hasn't started after 2m, it can also start onacme/k8s-small, a self-hosted container runner, and 2m after that onlarge, one size up on CircleCI cloud.
- deploy: a machine job onubuntu-2404:currentthat asks forarm.xlarge.gen2withplacement: pinned, so it never moves.
Having the ability to define fallbacks would be really valuable.
docker:
- image: cimg/node:lts
resource_class: medium.gen2
placement:
fallback_after: 2m
fallback:
- acme/k8s-small
- large.gen1
Example: org policy and project scope in Terraform
Having an org-wide placement policy would be nice!
An org-wide placement policy:
resource "circleci_placement_policy" "acme" {
organization_id = var.circleci_org_id
}
A rule for one requested class, limited to two projects: their
acme/k8s-build
jobs can also start on Docker large
on CircleCI cloud after 5 minutes. Other projects, such as ones that must stay on your own hardware, keep today's behavior.resource "circleci_placement_rule" "builds" {
policy_id = circleci_placement_policy.acme.id
resource_class = "acme/k8s-build"
project_ids = [circleci_project.api.id, circleci_project.web.id]
fallback {
executor = "docker"
resource_class = "large"
after = "5m"
}
}
Guardrails
- Jobs only move to existing classes that run them the same way, such as a Docker job to a container runner, which uses the same image.
- placement: pinnedkeeps a job on its class, whatever the org policy says.
- A job's own fallback list wins over the org rule, within limits the org sets.
- No placementkey and no org rule means exactly today's behavior.
- Every move is recorded on the job and in the API, with the reason.
Who this helps
- Anyone who would rather run a size up, or on their own runners, than wait out an incident.
- Both Cloud-first teams with a small runner fleet as a backstop, and self-hosted-first teams with CircleCI cloud as a safety net.
- Platform teams that want their Black Friday or disaster recovery plan for CI set up ahead of time.
- Teams whose AI coding agents start pipelines in bursts.