Skip to content

Commit

Permalink
Update documetation
Browse files Browse the repository at this point in the history 
Docker swarm standalone is no longer developed.  The GitHub repository
has been archived.  Remove mentions of swarm mode, other than to note
that Docker Engine Swarm is not supported.

Link to the changelog on the plugins site since it is much more complete
than the changelog stored in the repository.
  • Loading branch information
@MarkEWaite
MarkEWaite committed Jan 26, 2025
1 parent d842f06 commit 8605acf
Showing 1 changed file with 56 additions and 72 deletions.
128 changes: 56 additions & 72 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,88 +1,79 @@
# Docker plugin for Jenkins

Note: This plugin is officially ["up for adoption"](https://www.jenkins.io/doc/developer/plugin-governance/adopt-a-plugin/#faq).
It would benefit from having a new maintainer who uses it "for real work"
and is thus able to test things "for real" before release
instead of relying purely on the unit tests.

## Overview

This plugin allows containers to be dynamically provisioned as Jenkins nodes using Docker.
This plugin allows containers to be dynamically provisioned as Jenkins agents using Docker.
It is a Jenkins Cloud plugin for Docker.

The aim of this docker plugin is to be able to use a
[Docker](https://docs.docker.com/)
host to dynamically provision a docker container as a Jenkins agent node,
let that run a single build,
then tear-down that node,
without the build process (or Jenkins job definition)
requiring any awareness of docker.
This plugin allows a [Docker](https://docs.docker.com/) host to dynamically provision a container as a Jenkins agent node,
lets that run a single build,
then removes that node,
without the build process or Jenkins job definition
requiring any awareness 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 labels/tags that this template provides,
the docker image,
Docker hosts,
one or more "templates"
that describe
the labels/tags provided by the template,
the Docker image,
how to start it,
etc)
and Jenkins can then run docker containers to provide Jenkins (agent) Nodes on which Jenkins can run builds.
and Jenkins can creates agents on-demand using those Docker containers.

## See also
* [Software licence](LICENSE)
* [Changelog](https://plugins.jenkins.io/docker-plugin/releases/) and [archive](https://github.com/jenkinsci/docker-plugin/blob/docker-plugin-1.3.0/CHANGELOG.md)
* Support and [contribution guide](CONTRIBUTING.md)
* [Changelog](CHANGELOG.md)
* [Software license](LICENSE)

----

**Note:** There is _more than one docker plugin_ for Jenkins.
**Note:** There is _more than one Docker plugin_ for Jenkins.
While this can be confusing for end-users, it's even more confusing when end users report bugs in the wrong place.
e.g. if you are using Jenkins
[pipeline / workflow / Jenkinsfile](https://jenkins.io/doc/book/pipeline/docker/)
For example, if you are using Jenkins
[Pipeline](https://jenkins.io/doc/book/pipeline/docker/)
builds with code including terms like
`docker.withDockerRegistry`
or
`docker.image`
etc then you're using the
then you're using the
[`docker-workflow`](https://plugins.jenkins.io/docker-workflow)
plugin and should go to its repository instead of this one.

----

**Note:** This plugin does not use the OS's native docker client;
**Note:** This plugin does not use the OS's native Docker client;
it uses [docker-java](https://github.com/docker-java/docker-java).
You do not need to install a docker client on Jenkins or on your agents to use this plugin.
You do not need to install a Docker client on Jenkins or on your agents to use this plugin.

----

**Note:** This plugin does not _provide_ a Docker daemon; it allows Jenkins to _use_ a docker daemon.
i.e. Once you've installed docker somewhere, this plugin will allow Jenkins to make use of it.
**Note:** This plugin does not _provide_ a Docker daemon; it allows Jenkins to _use_ a Docker daemon.
i.e. Once you've installed Docker somewhere, this plugin will allow Jenkins to make use of it.

----

## Setup

A quick setup is :

1. get a docker environment running
1. follow the instructions for creating a docker image that can be used
1. get a Docker environment running
1. follow the instructions for creating a Docker image that can be used
as a Jenkins Agent
_or_ use one of the pre-built images
e.g. [jenkins/inbound-agent](https://hub.docker.com/r/jenkins/inbound-agent/)
like the [jenkins/inbound-agent](https://hub.docker.com/r/jenkins/inbound-agent/)

### Docker Environment

Follow the installation steps on [the docker website](https://docs.docker.com/).
Follow the installation steps on [the Docker website](https://docs.docker.com/).

If your Jenkins instance is not on the same OS as the docker install,
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 config file and setting (for example)
If your Jenkins instance is not on the same OS as the Docker install,
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 config file and setting (for example)

```sh
DOCKER_OPTS="-H tcp://0.0.0.0:2376 -H unix:///var/run/docker.sock"
```

The docker configuration file location will depend your system, but it
The Docker configuration file location will depend your system, but it
is likely to be
`/etc/init/docker.conf`
,
Expand All @@ -92,15 +83,9 @@ or

### Multiple Docker Hosts

If you want to use more than just one physical node to run containers,
you can use
[Docker Swarm Standalone](https://github.com/docker/swarm)
or you can define more than one docker "cloud".
The docker engine swarm mode API is not supported
(at present; enhancement contributions would be welcomed).

To use the standalone swarm,
follow docker swarm standalone instructions and configure Jenkins with the swarm's API endpoint.
If you want to use more than just one physical node to run containers, you can define multiple Docker clouds.
The [Docker engine swarm mode API](https://docs.docker.com/engine/swarm/) is not supported.
Enhancement contributions would be welcomed.

### Jenkins Configuration

Expand All @@ -111,30 +96,32 @@ and add a new Cloud of type "Docker".

![](docs/images/add-new-docker-cloud.png)

Configure Docker (or Swarm standalone) API URL with required credentials.
Configure Docker API URL with required credentials.
The test button lets you check the connection.

Then configure Agent templates,
assigning them labels that you can use so your jobs select the appropriate template,
and set the docker container to be run with whatever container settings you require.
and set the Docker container to be run with whatever container settings you require.

### Running self-made local Docker images

By default the Jenkins Docker plugin will try to download ('pull') the latest version of the image. This will fail with custom images that are not on Docker Hub. You will see logs like:
By default the Jenkins Docker plugin will download ('pull') the latest version of the image.
This will fail with custom images that are not on Docker Hub.
You will see logs like:

> com.nirima.jenkins.plugins.docker.DockerTemplate pullImage
> Pulling image '..'. This may take awhile...
> com.github.dockerjava.api.exception.NotFoundException: Status 404: {"message":"pull access denied for .., repository does not exist or may require 'docker login': denied: requested access to the resource is denied"}
On the _Docker Agent template_ set **Pull strategy** to **Never pull**, Name, Docker Image, Remote File System Root, and checkbox Enabled.
On the _Docker Agent template_ set the **Pull strategy** to **Never pull**, Name, Docker Image, Remote File System Root, and checkbox Enabled.

If you have docker only on your local Jenkins machine, set on _Docker Cloud details_ the textbox **Docker Host URI** to `unix:///var/run/docker.sock`, and checkbox Enabled.
If you have Docker only on your local Jenkins machine, configure the **Docker Host URI** to `unix:///var/run/docker.sock`.

### Creating a docker image
### 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
You need a Docker image that can be used to run Jenkins agent.
Depending on the launch method you select, there are some prerequisites
for the Docker image to be used:

## Launch via SSH
Expand All @@ -143,16 +130,16 @@ for the Docker image to be used:
You can use
[jenkins/ssh-agent](https://hub.docker.com/r/jenkins/ssh-agent/)
as a basis for a custom image.
- a SSH key (based on the unique Jenkins instance identity) can be
- an SSH key (based on the unique Jenkins instance identity) can be
injected in container on startup, you don't need any credential set
as long as you use standard openssl sshd.
![](docs/images/connect-with-ssh.png)
When using the `jenkins/ssh-agent` Docker image, ensure that the user
is set to `jenkins`.
For backward compatibility *or* non-standard sshd packaged in your
docker image, you also have option to provide manually configured
Docker image, you also have option to provide manually configured
ssh credentials
- **Note:** If the docker container's host SSH key is not trusted by
- **Note:** If the Docker container's host SSH key is not trusted by
Jenkins (usually the case) then you'll need to set the SSH host key
verification method to "non-verifying".

Expand Down Expand Up @@ -187,7 +174,7 @@ COPY your-favorite-tool-here

## Note on ENTRYPOINT

Avoid overriding the docker command, as the SSH Launcher relies on it.
Avoid overriding the Docker command, as the 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 connection
... but you MUST ensure your entrypoint eventually runs the passed command:
Expand All @@ -198,25 +185,23 @@ You _can_ use an Entrypoint to run some side service inside your build agent con

More information can be obtained from the online help built into the Jenkins web UI.
Most configurable fields have explanatory text.
This,
combined with knowledge of [docker itself](https://docs.docker.com/),
should answer most questions.
This, combined with knowledge of [Docker itself](https://docs.docker.com/), should answer most questions.

## Configuration as code

Jenkins and the docker-plugin can be configured using Groovy code
and/or using the [JCasC plugin](https://plugins.jenkins.io/configuration-as-code/).
Jenkins and the Docker plugin can be configured as code using the [configuration as code plugin](https://plugins.jenkins.io/configuration-as-code/).
It can also be configured from the Groovy script

If you're unsure which method to use, use JCasC.
If you're unsure which method to use, use the configuration as code plugin.

### JCasC plugin
### Configuration as Code plugin

Install the [configuration-as-code plugin](https://plugins.jenkins.io/configuration-as-code/) and follow [its example](https://github.com/jenkinsci/configuration-as-code-plugin/tree/master/demos/docker).

As another alternative, a Docker daemon can listen to requests from remote hosts by following the [Docker documentation](https://docs.docker.com/config/daemon/remote-access/).
As another alternative, a Docker daemon can listen to requests from remote hosts by following the [Docker documentation](https://docs.docker.com/engine/daemon/remote-access/).
The following configuration as code example creates a cloud named "my-docker-cloud" that uses the docker daemon at port 2375 on dockerhost.example.com to run up to 3 containerized agents at a time.
Agents run the [Jenkins Alpine inbound agent container image](https://hub.docker.com/r/jenkins/inbound-agent) with Java 21.
Thay use an inbound connection and run as the user ID 1000 with the home directory "/home/jenkins/agent".
They use an inbound connection and run as the user ID 1000 with the home directory "/home/jenkins/agent".

```yaml
jenkins:
Expand Down Expand Up @@ -249,11 +234,10 @@ jenkins:
For example, this
[configuration script](docs/attachments/docker-plugin-configuration-script.groovy)
could be run automatically upon
could be run automatically during
[Jenkins post-initialization](https://www.jenkins.io/doc/book/managing/groovy-hook-scripts/)
or through the
[Jenkins script console](https://www.jenkins.io/doc/book/managing/script-console/).
If run,
this script will configure the docker-plugin to look for a docker daemon running within the same OS as the Jenkins controller
This script configures the plugin to look for a Docker daemon running within the same OS as the Jenkins controller
(connecting to Docker service through `unix:///var/run/docker.sock`)
and with the containers connecting to Jenkins using the "attach" method.

0 comments on commit 8605acf

Please sign in to comment.