View Docker on the plugin site for more information.
Docker plugin allows to use a docker host to dynamically provision build agents, run a single build, then tear-down agent.
Optionally, the container can be committed, so that (for example) manual QA could be performed by the container being imported into a local docker provider, and run from there.
A quick setup is :
- get a docker environment running
- follow the instructions for creating a docker image that can be used as a Jenkins Agent
Follow the installation steps on docker.io.
If your host needs to allow connections from a jenkins instance hosted on a different machine, you will need to open up the TCP port. This can be achieved by editing the docker config file and setting (for example)
The docker configuration file location will depend your system, but it is likely to be /etc/init/docker.conf, /etc/default/docker or /etc/default/docker.io)
Multiple Docker Hosts
If you want to use more than just a physical node to run containers, you can rely on Docker Swarm Standalone - docker engine swarm mode isn't yet supported.
Follow docker swarm standalone instruction and configure docker swarm API endpoint in Jenkins.
Docker plugin is a "Cloud" implementation. You'll need to edit Jenkins system configuration (Jenkins > Manage > System configuraiton) and add a new Cloud of type "Docker".
Configure Docker (or Swarm standalone) API URL with required credentials. A test button let you connection with API is well set.
Then configure Agent templates, assigning them labels you can use for your jobs to select the adequate template, and docker container to run
Creating a docker image
You need a docker image that can be used to run Jenkins agent runtime. Depending on the launch method you select, there's some prerequisites for the Docker image to be used :
Launch via SSH
- sshd server and a JDK installed. You can just use jenkins/ssh-slave as a basis for a custom image.
- a SSH key (based on unique Jenkins master instance identity) can be injected in container on startup, you don't need any credential set as long as you use standard openssl sshd.
For backward compatibility or non-standard sshd packaged in your docker image, you also have option to provide manually configured ssh credentials
Launch via JNLP
- a JDK installed. You can just use jenkins/jnlp-slave as a basis for a custom image.
- Jenkins master URL has to be reachable from container.
- container will be configured automatically with agent's name and secret, so you don't need any special configuration of the container
- a JDK installed. You can just use jenkins/slave as a basis for a custom image.
- Please note this mode is experimental at time writing.
To create a custom image and bundle your favorite tools, just create a Dockerfile with FROM to point to one of the jenkins/*-slave reference image, and install everything needed for your own usage
Note on ENTRYPOINT
Avoid overriding the docker command, as SSH Launcher relies on it.
You can use an Entrypoint to run some side service inside your build agent container before the agent runtime starts and establish a connexion. Just ensure your entrypoint eventually run the passed command :
Configure plugin via Groovy script
Either automatically upon Jenkins post-initialization or through Jenkins script console. Example running locally, connecting to Docker service through unix///var/run/docker.sock and launching attached: