Jenkins Docker Plugin

External

• https://wiki.jenkins.io/display/JENKINS/Docker+Commons+Plugin
• https://plugins.jenkins.io/docker-commons
• https://wiki.jenkins.io/display/JENKINS/Docker+Plugin
• https://plugins.jenkins.io/docker-plugin

Internal

• Jenkins Concepts

Overview

ID: docker-commons

ID: docker-plugin

Concepts

Docker Agent

Jenkins can interact with agents executing as containers within a Docker instance. The agent containers must be based on one of the following base images:

jenkins/ssh-slave

https://hub.docker.com/r/jenkins/ssh-slave/

The image comes with sshd and a JDK. The Jenkins master will use ssh to connect into the agent's sshd. A SSH key based on unique Jenkins master instance identity can be injected in container on startup, obviating the need for password.

jenkins/jnlp-slave

https://hub.docker.com/r/jenkins/jnlp-slave/

The image comes with JDK. Jenkins master URL has to be reachable from the agent's container. The container will be configured automatically with the agent's name and secret. No special configuration of the container is needed.

jenkins/slave

https://hub.docker.com/r/jenkins/slave/

An "attached" agent.

Installation

Plugin Installation

Manually from the UI or:

/usr/local/bin/install-plugins.sh docker-plugin

After the plugin is installed, a new configuration category shows up: Manage Jenkins -> Configure System -> Cloud.

Jenkins Server Configuration

Jenkins -> Manage Jenkins -> Configure System -> Cloud -> Add a new cloud -> Docker

Name

docker

The name should be something suggestive that indicates what docker server is actually used.

Docker Host URI

It is the URI to the Docker Host. May be left blank to use the default value defined by DOCKER_HOST environment variable. A typical value is unix:///var/run/docker.sock or tcp://127.0.0.1:2376.

Using Unix-domain Sockets for Jenkins Running as a Container

Note that if Jenkins itself runs as a Docker container on the same Docker server to be used for agent provisioning, and wants to use a Unix-doman socket for access, it won't access by default to unix:///var/run/docker.sock of the Docker host. Access can be enabled by starting the Jenkins container as follows:

docker run ... --mount type=bind,source=/var/run/docker.sock,target=/var/run/docker.sock ... <jenkins-image>

This command maps the Docker-host level /var/run/docker.sock into the container, and sets appropriate permissions on the container-level /var/run/docker.sock so Jenkins can access it.

For concepts behind bind mounts, see Docker Bind Mounts. Also, the Docker host-level user mapped to the Jenkins process must be added to the "docker" group, so it has access to the Unix socket. For more details see Non-root Management Access for Docker.

Server credentials

Test Connection

Useful for debugging. A successful connection to the Docker server should return something like:

Version = 18.03.0-ce, API Version = 1.37

Enabled

Must be specifically enabled. Not by default.

Docker Hostname or IP address

It is required when access to the Docker server is done via Unix-domain sockets, and Jenkins sits on a different host in the internal or external network. If network access, instead of Unix-domain sockets, is used, the value is not required, as it is obtained from the host part of the Docker Host URI.

Note that the UI has a "Test Connection".

Docker Agent Template: associates a label with a Docker image, which must be available on an accessible registry.

Configuration

The agent images need to be created and accessible to the Jenkins server.