Note: This plugin is officially “up for adoption”. It would benefit from having a new maintainer who uses it “for the real job” and can therefore test things “for real” before launch instead of relying solely on unit testing.
Overview
This plugin allows containers to be dynamically provisioned as Jenkins nodes using Docker. It is a Jenkins Cloud plugin for Docker.
The goal of this docker plugin is to be able to use a Docker host to dynamically provision a docker container as a Jenkins agent node, let it run a single build, and then take that node down, without the build process (or Jenkins’ job definition) requiring any knowledge of docker.
The Jenkins administrator configures Jenkins with knowledge of one or more docker hosts (or
swarms), knowledge of one or more “templates” (which describe the tags/tags this template provides, the docker image, how to start it, etc.) and Jenkins can run docker containers to provide Jenkins nodes (agent) on which Jenkins can run builds.
See also
- Software License
- Support and Contribution Guide
- log
Change
Note: There is more than one docker plugin for Jenkins. While this can be confusing for end users, it is even more confusing when end users report errors in the wrong place. For example, if you are using Jenkins pipeline/workflow/Jenkinsfile compiles with code that includes terms like docker.withDockerRegistry or docker.image, etc., then you are using the docker-workflow plugin and should go to your repository instead.
Note: This plugin does not use the native docker client of the operating system; it uses docker-java. You do not need to install a docker client on Jenkins or its agents to use this plugin.
Note: This plugin does not provide a Docker daemon; it allows Jenkins to use a docker daemon. that is, once you have installed docker somewhere, this plugin will allow Jenkins to make use of it.
Configuration
A quick setup is:
Get a running Docker
- environment
- instructions to create a Docker image that can be used as a Jenkins agent or use one of the pre-built images, for example, jenkins/inbound-agent
follow the
Docker Environment Follow the installation steps on the Docker website. If your Jenkins instance is not on the same operating system as the Docker
installation
, you will need to open the Docker TCP port so that Jenkins can communicate with the Docker daemon. This can be achieved by editing the
Docker configuration file and configuration (e.g. The location of the Docker configuration file will depend on your system, but 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 one physical node to run containers, you can use Docker Swarm Standalone or you can define more than one docker “cloud”. The docker engine swarm mode API is not supported (currently; enhancement contributions would be welcome).
To use the standalone swarm
, follow the Docker swarm standalone instructions and configure Jenkins with the swarm API endpoint.
Jenkins Configuration
Docker plugin is a “Cloud” implementation. You’ll need to edit the Jenkins system configuration (Jenkins -> Manage -> system settings) and add a new cloud of type “Docker”.
Configure the Docker API URL (or standalone Swarm) with the required credentials. The test button allows you to check the connection.
Next, configure the agent templates, assigning them tags that you can use so that your jobs select the appropriate template, and set the Docker container to run with the container configuration you need.
Create
a Docker image
You need a Docker image that can be used to run the Jenkins agent runtime. Depending on the startup method you select, there are a few prerequisites for the Docker image to be used:
Boot through
the
- SSH sshd server and an installed JDK. You can use jenkins/ssh-agent as the basis for a custom image.
- an SSH key (based on the unique identity of the Jenkins instance) can be injected into the container at startup, you don’t need any set of credentials as long as you use standard OpenSSL SSHD.
For backward compatibility or non-standard sshd packaged in your Docker image, you also have the option to provide manually configured ssh credentials - Note: If Jenkins does not trust the SSH key of the docker container (usually the case), you will need to set the SSH host key verification method to “non-verifying”.
Start via JNLP
- an installed JDK. You can use jenkins/inbound-agent as the basis for a custom image.
- The Jenkins handler URL must be accessible from the container.
- The container will be automatically configured with the agent’s name and secret, so you don’t need any special container configuration.
Start attaching
- an installed JDK. You can use jenkins/agent as the basis for a custom image. To
create a
custom image and group your favorite tools, create a Dockerfile with the FROM to point to one of the jenkins/*-agent reference images, and install everything necessary for your own use, for example
,
Note about ENTRYPOINT
Avoid overriding the docker command, as SSH Launcher relies on it.
You can use an entry point to run some side service inside the build agent container before the agent runtime starts and establish a connection… but you MUST ensure that your entry point finally executes the past command:
Learn
more
You can learn more in the online help built into the Jenkins web UI. Most configurable fields have explanatory text. This, combined with the knowledge of docker itself, should answer most questions.
Configuration as code
Jenkins and the
docker-plugin can be configured using Groovy code and/or using the
JCasC plugin.
If you’re not sure which method to use, use JCasC
.
Groovy
script
For example, this configuration script could run automatically after Jenkins initialization or through the Jenkins script console. If executed, this script will configure the docker-plugin to look for a docker daemon running within the same operating system as the Jenkins driver (connecting to the Docker service via unix:///var/run/docker.sock) and with containers connecting to Jenkins using the “attach” method.
JCasC
plugin
Install the configuration-as-code plugin and follow suit.
