A One-Shot Executor is a Slave created for a specific Build in Jenkins Queue. It is launched as the Build start, and destroyed as the Build Complete. Think as a 1:1 lifecycle between your Build and the Slave to run it.
A classic (or Cloud) Jenkins slave has it standalone lifecycle and do accept task from the build queue. Especially, even when using a Cloud slave, which can create a fresh new slave for a Build, Slave will still precede the Build, and survive it. Cloud API can be tweaked to ensure slave will be created asap and destroyed after use for a Build, but
When relying on Docker containers, and the actual container image to host the build is defined by the Job or Build parameters, the slave launch can fail. A Cloud Slave would try to provision a slave repeatedly as an infinite loop to match the Queue Task executor request, until someone wonder why the build never started, investigate, and find a typo in job configuration.
So, what about One-Shot ?
A OneShot executor is an executor dedicated to a Builld.
Reversing the Slave/Build relation and forwarding Slave's log into build log, we can report the container bootstrap process. User will see in log the image is pulled from registry, container is started, may fail and report errors. In such circumstances, this is not Jenkins fault, but an actual failure caused by the Build's configuration. So getting this in the Build log, and reporting to the user by build failure notification will let him know something is wrong without delay.
One-Shot Executor is an infrastructure plugin, it does not provide new Slaves by itself, but just the API for a Slave provider to implement this new approach and only focus on running a Slave according to the Job configuration / Build parameters.
Implementation currently uses terrible hacks, but is working well. We use it as a proof of concept and a way to demonstrate need for new hooks in jenkins-core, so a future release could use cleaner APIs and not rely on some Jenkins internal implementation details.
This plugin has been extracted from docker-slaves, we created for Docker Hack Day 2015 (we won the 3rd prize!), and which is an experiment sandbox for us. So this specific piece of code was created by extracting stable components to let them become mature and usable by others.