原文地址：https://wiki.jenkins.io/display/JENKINS/Docker+Plugin
Plugin Information
|
Plugin ID |
docker-plugin |
Changes |
|
|---|---|---|---|
|
Latest Release |
0.16.2 (archives) |
Source Code |
GitHub |
|
Usage |
|
Installations |
2016-Aug 4517 |
Background
The aim of the docker plugin is to be able to use a docker host to dynamically provision a slave, run a single build, then tear-down that slave.
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.
Setup
A quick setup is :
- get a docker environment running
- follow the instructions for creating a system that has an ssh server installed, and a JDK
- create a user (e.g: jenkins) that you can log in with
- store that image with a known ID (e.g: jenkins) so that it appears in the output of "docker images" command
Docker Environment
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)
DOCKER_OPTS="-H tcp://0.0.0.0:4243 -H unix:///var/run/docker.sock" |
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)
Creating a docker image
Shortcut : Pulling a Docker image
You can pull a ready-made jenkins slave! (Use at your own risk.)
docker pull evarga/jenkins-slave |
You need a docker image that has, as a minimum, an ssh server installed. You probably want a JDK, and you will also want a 'jenkins' user that can log in. Example session to do this:
root@Quordlepleen:/etc/init# docker pull ubuntu Pulling repository ubuntu ... root@Quordlepleen:/etc/init# docker run -i -t ubuntu /bin/bash root@cff9f1f868b0:/# apt-get update root@cff9f1f868b0:/# apt-get install openssh-server root@cff9f1f868b0:/# mkdir /var/run/sshd root@cff9f1f868b0:/# apt-get install openjdk-6-jdk root@cff9f1f868b0:/# adduser jenkins Adding user `jenkins' ... Adding new group `jenkins' (1000) ... Adding new user `jenkins' (1000) with group `jenkins' ... Creating home directory `/home/jenkins' ... Copying files from `/etc/skel' ... Enter new UNIX password: Retype new UNIX password: passwd: password updated successfully Changing the user information for jenkins Enter the new value, or press ENTER for the default Full Name []: Jenkins Room Number []: Work Phone []: Home Phone []: Other []: Is the information correct? [Y/n] Y root@cff9f1f868b0:/# /usr/sbin/sshd root@cff9f1f868b0:/# exit
Once the container has been created, you need to commit it with a name to be used later, e.g: jenkins-1
root@Quordlepleen:/etc/init# docker ps -a CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES cff9f1f868b0 ubuntu:12.04 /bin/bash 7 minutes ago Exit 0 goofy_mccarthy root@Quordlepleen:/etc/init# docker commit cff9f1f868b0 jenkins-1 9ebe455d911904ce0939b41758af6b3159b91ccb0aa36e7bc911d96c8cc30e64 root@Quordlepleen:/etc/init# docker images REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE jenkins-1 latest 9ebe455d9119 3 minutes ago 422.1 MB ubuntu saucy 43461fe97ba1 5 days ago 144.6 MB ubuntu raring 5e94ff221e91 5 days ago 133.6 MB ubuntu quantal 3e47bae8d07a 5 days ago 127.6 MB ubuntu lucid 04180f9bd8a6 5 days ago 139.6 MB ubuntu precise 1e548c932d40 5 days ago 125.9 MB ubuntu 12.04 8dbd9e392a96 9 months ago 128 MB ubuntu latest 8dbd9e392a96 9 months ago 128 MB ubuntu 12.10 b750fe79269d 10 months ago 175.3 MB cff9f1f868b0 ubuntu:12.04 /bin/bash 7 minutes ago Exit 0 goofy_mccarthy
You may wish to periodically update your build image -- e.g: if you are using maven, then it would be advantageous to update your local maven repository with released artifacts, to prevent having to download them again (and thus speeding up your builds).
Tips
It is very easy to update your jenkins image in docker -
root@krikkit:~# docker run -i -t jenkins-1 /bin/bash # HACK ON IMAGE root@d0ba389c07c5:/home/jenkins# exit # Save new image root@krikkit:~# docker commit d0ba389c07c5 jenkins-2
By default, the docker plugin will execute /usr/sbin/sshd -D, therefore it is not recommended that you set the ENTRYPOINT unless you plan to pass extra arguments from Jenkins
Configuration
Docker appears in the 'Cloud' section of the Jenkins configuration, select "Docker" from the "Add a new cloud" drop down menu.
The docker cloud configuration has the following options:
|
Name |
Choose a name for this Docker cloud provider |
|
Docker URL |
The URL to use to access your Docker server API (e.g: http://172.16.42.43:4243) |
|
Connection Timeout |
|
|
Read Timeout |
|
|
(Global) Container Cap |
The maximum number of containers that may be allowed to be running on the Docker server at a time, 0 disables provisioning of instances altogether. |
|
Local Container Cap |
The maximum number of container that this Jenkins instance may be allowed to be running on the Docker server at a time, 0 disables provisioning of instances altogether. |
Images:
Click the Add button to add a new image.
The docker cloud configuration has the following options:
|
ID |
The tagged name of the image that you wish docker to run (e.g "docker run -i -t <id> /bin/bash) |
|
Labels |
Labels to give these nodes (for limiting your builds) |
|
Credentials |
The SSH credentials to connect to the instance with |
|
Remote Filing System Root |
Root directory within your image for the Jenkins user to use |
|
Remote FS Root Mapping |
Enables the ability to browse workspaces of jobs being built using docker containers. Specify the location on the Jenkins master where the job workspaces will be and map them from the images using volumes, network shares, etc. |
|
Instance Cap |
Max number of instances of this image to run on the docker host (Note: instances not created by this plugin are also counted! see also JENKINS-36919), or 0 for unlimited |
|
DNS |
Set the DNS servers to use within your images |
|
Port bindings |
hostport:containerport |
|
Bind all declared ports |
|
|
Hostname |
|
|
Idle termination time |
The time in minutes after which an idle container will be dismantled (in the sense of a timeout) |
|
JavaPath |
The location within your image of the java executable for running the Jenkins slave |
|
JVM Options |
|
|
Docker Command |
The command to run for this image, defaults to "/usr/sbin/sshd -D" |
|
LXC Conf Options |
|
|
Volumes |
A space separated list of host volume mounts, e.g. /host/path:/container/path:ro |
|
Volumes From |
|
|
Run container privileged |
|
|
Prefix Start Slave Command |
|
|
Suffix Start Slave Command |
Job Configuration
|
Commit on successful build |
When a job completes, the docker slave instance is committed with tag based on the job name and build number |
|
Additional tag to add |
|
|
Push on successful build |
|
|
Clean local images |
Container Cap and Instance Capacity
Container cap and instance capacity both limits the number of containers this plugin requests to be running on the Docker server at a time. They serve a different purpose, but are very similar in general. Thus, their difference may be hard to understand.
- The container cap is an "overall limit", which restricts the number of containers which may be running -- irrespectively which image is being used.
- The instance capacity is limiting the number of containers for a given image only.
Here's an example, which should make it clearer:
Let us assume that
- the container cap is set to 10,
- the instance capacity of image A is set to 6, and
- the instance capacity of image B is set to 5.
Let 5 containers of image A and 5 containers of image B be running on the Docker server. Even though there is still one slot free of capacity for image A, no new container will be provision: The container cap for the Docker Host is already reached.
Let us assume that the container cap is changed to 12. Now, another container can be provisioned for image A, as the instance capacity is not reached yet. However, that does not hold true for image B, as the instance capacity is set to 5 and already 5 containers are running.
How Container Cap and Instance Capacity is determined
Note that both container cap and instance capacity is determined by listing the containers running on the Docker server. It is a common misunderstanding that this value equals to the number of slaves attached to the Jenkins instance! However, keep in mind that there may be containers running, which are not associated to the current Jenkins instance (because they have been started from another's machine, or they got decoupled but not cleaned up properly yet, ...)
Triton and Container Cap / Instance Capacity
If your Docker server is running Triton, be aware of the fact that -
in contrast to the Docker reference implementation - containers are
private to the user you are using to log on.
This implies the effect that the container cap and the instance capacity
is calculate relative to the user only and is not applied globally
(which can be a good or a bad thing, depending on your use case).
Known Issues
If you have trouble selecting "Docker" from the clouds list, then you need to update your credentials plugin.
Changelog
See https://github.com/jenkinsci/docker-plugin/blob/master/CHANGELOG.md