Skip to content

How It Works

Provisioning flow

Jenkins requests label
  -> plugin finds the best matching label mapping
  -> plugin finds assigned hosts for that label
  -> plugin checks cooldown and semaphore capacity
  -> plugin provisions a VM through Jeballto
  -> plugin enables SSH and Jenkins SSH Build Agents launches the agent
  -> build runs
  -> plugin force-deletes the VM

Routing logic

The plugin first resolves the label to a global LabelAssignment. It then gathers every JeballtoAgentTemplate that is assigned to that label.

That split is what makes one image reusable across many hosts.

If multiple global mappings match, the highest-priority mapping wins and determines the OCI image. After that, the plugin tries matching templates in their configured order, skipping templates that are in cooldown or already at capacity.

Capacity control

Each template has an in-memory semaphore:

  • acquiring a permit allows provisioning
  • releasing a permit happens after the VM is deleted
  • this keeps Jenkins from starting a replacement VM before cleanup actually finishes

Circuit breaker

After three consecutive failures, the template enters a two-minute cooldown. That protects Jenkins from repeatedly trying a broken host or broken image configuration.

Image pull deduplication

Concurrent provisions for the same image wait on one shared pull path instead of all pulling the same image independently.

Missing images can take up to 120 minutes to pull. The overall provisioning budget is 150 minutes, with a 130 minute image pull lock to let one pull finish before other provisions continue.

Agent launch

The plugin delegates SSH startup to Jenkins SSH Build Agents. In node logs, the agent launch details use the [SSH] prefix.

Cleanup and orphan handling

Normal termination:

  • build ends
  • plugin disables SSH if possible
  • plugin force-deletes the VM
  • semaphore permit is released

Background cleanup:

  • scans for VMs that are old enough to be considered orphaned
  • only deletes VMs whose names match known templates
  • releases permits when orphan cleanup resolves stuck capacity

Restart behavior

Because semaphores and cooldown state are in memory:

  • Jenkins restart resets semaphores
  • Jenkins restart clears cooldown state
  • orphan cleanup is responsible for reconciling any drift after restart

Important code areas

  • src/main/java/io/jenkins/plugins/jeballto/JeballtoCloud.java
  • src/main/java/io/jenkins/plugins/jeballto/JeballtoAgentTemplate.java
  • src/main/java/io/jenkins/plugins/jeballto/JeballtoLauncher.java
  • src/main/java/io/jenkins/plugins/jeballto/OrphanedVmCleanup.java
  • src/main/java/io/jenkins/plugins/jeballto/provisioning/VmProvisioner.java