DOCSEARCHbyAlgolia
Submit Docs

Jenkins Docker Plugin

repository·master·Indexed 19 days ago

https://github.com/jenkinsci/docker-plugin

Enables dynamic provisioning of Jenkins agents using Docker containers. This plugin implements a Jenkins 'Cloud' that connects to an existing Docker daemon via docker-java to spin up containers based on defined templates and tear them down after builds complete. It supports multiple launch methods including SSH, JNLP (Inbound), and Attached, and can be configured via the Jenkins UI or Configuration as Code (YAML).

Tokens
2.2K
Snippets
5
Records
11
Agent score
68%

What's inside docker-plugin

  1. Prerequisites for Docker Agent Launch Methods

    master

    Depending on how you want the agent to connect to Jenkins, your Docker image must meet specific requirements:

    Launch via SSH

    • Requires an sshd server and a JDK installed in the image.
    • Base Image Suggestion: jenkins/ssh-agent.
    • Credentials: You can use standard OpenSSL sshd (Jenkins injects an SSH key on startup) or provide manually configured SSH credentials.
    • User: If using jenkins/ssh-agent, ensure the user is set to jenkins.
    • Verification: If the container's host SSH key is not trusted, set the SSH host key verification method to non-verifying in Jenkins.

    Launch via JNLP (Inbound)

    • Requires a JDK installed in the image.
    • Base Image Suggestion: jenkins/inbound-agent.
    • Connectivity: The Jenkins controller URL must be reachable from within the container.
    • Configuration: The container is automatically configured with the agent's name and secret.

    Launch Attached

    • Requires a JDK installed in the image.
    • Base Image Suggestion: jenkins/agent.

  2. Important: Docker ENTRYPOINT requirements

    master

    When creating custom images, avoid overriding the Docker ENTRYPOINT command, as the SSH Launcher relies on it.

    If you must use an ENTRYPOINT to run sidecar services before the agent starts, you MUST ensure the entrypoint eventually executes the passed command using exec "$". This ensures the agent runtime can start correctly.

    exec "$"

  3. How the Docker plugin works

    master

    The Docker plugin is a Jenkins 'Cloud' implementation that allows Jenkins to dynamically provision containers as agent nodes.

    Key Workflow:

    1. An administrator configures Docker hosts and one or more Agent templates in Jenkins.
    2. Templates define specific Docker images, labels/tags, and container settings.
    3. When a job requires a specific label, Jenkins uses the Docker host to spin up a container based on the matching template.
    4. The container runs the build, and once the build is complete, Jenkins automatically removes the node.

    Important Distinctions:

    • Not a Docker provider: This plugin does not provide a Docker daemon; it connects to an existing Docker daemon (local or remote).
    • No Docker client required: The plugin uses docker-java to communicate with the Docker API, so you do not need to install the Docker CLI on the Jenkins controller or agents.
    • Different from docker-workflow: If you are using Pipeline steps like docker.image or docker.withDockerRegistry, you are using the docker-workflow plugin, not this one.

  4. Configure Docker Cloud in Jenkins

    master

    The plugin is configured as a 'Cloud' type within Jenkins.

    1. Navigate to Jenkins -> Manage -> System configuration.
    2. Add a new Cloud of type Docker.
    3. Configure Docker API URL: Provide the URI for your Docker daemon and any required credentials.
    4. Test Connection: Use the provided test button to verify Jenkins can reach the Docker API.
    5. Configure Agent Templates:
      • Assign labels to templates so jobs can target them.
      • Define the Docker image to use.
      • Set container settings as required.

  5. Set up a Docker environment for Jenkins

    master

    To use this plugin, you must have a Docker daemon running.

    Local Docker (Same OS as Jenkins)

    If Docker is running on the same machine as your Jenkins controller, configure the Docker Host URI to: unix:///var/run/docker.sock

    Remote Docker (Different OS)

    If Jenkins is on a different OS than the Docker daemon, you must configure the Docker daemon to listen on a TCP port.

    Example configuration for the Docker daemon (e.g., in /etc/default/docker or /etc/init/docker.conf):

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

    Note: Ensure the TCP port is open in your firewall to allow Jenkins to communicate with the daemon.

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

  6. Use local Docker images (Never Pull strategy)

    master

    By default, the plugin attempts to pull the image from Docker Hub. If you are using custom images that exist only on your local Docker host, the pull will fail with a NotFoundException (404).

    To use local images:

    1. Go to your Docker Agent template configuration.
    2. Set the Pull strategy to Never pull.
    3. Ensure the Docker Image name matches your local image.
    4. Ensure the Docker Host URI is correctly pointing to your local socket (unix:///var/run/docker.sock) if applicable.

  7. Configure Docker Cloud via Configuration as Code (YAML)

    master

    You can define your Docker Cloud using the configuration-as-code plugin. Below is an example configuration for a cloud named my-docker-cloud that connects to a remote daemon at tcp://dockerhost.example.com:2375, limits concurrency to 3 agents, and uses the jenkins/inbound-agent:latest-alpine-jdk21 image with JNLP connection.

    jenkins:
  clouds:
  - docker:
      containerCap: 3
      dockerApi:
        dockerHost:
          uri: "tcp://dockerhost.example.com:2375"
      name: "my-docker-cloud"
      templates:
      - connector:
          jnlp:
            jenkinsUrl: "https://jenkins.example.com/"
            user: "1000"
        dockerTemplateBase:
          image: "jenkins/inbound-agent:latest-alpine-jdk21"
        labelString: "alpine jdk21 alpine-jdk21"
        mode: EXCLUSIVE
        name: "alpine-jdk21"
        pullTimeout: 171
        remoteFs: "/home/jenkins/agent"
    jenkins:
  clouds:
  - docker:
      containerCap: 3
      dockerApi:
        dockerHost:
          uri: "tcp://dockerhost.example.com:2375"
      name: "my-docker-cloud"
      templates:
      - connector:
          jnlp:
            jenkinsUrl: "https://jenkins.example.com/"
            user: "1000"
        dockerTemplateBase:
          image: "jenkins/inbound-agent:latest-alpine-jdk21"
        labelString: "alpine jdk21 alpine-jdk21"
        mode: EXCLUSIVE
        name: "alpine-jdk21"
        pullTimeout: 171
        remoteFs: "/home/jenkins/agent"

  8. Create a custom Docker agent image

    master

    To bundle specific tools into your Jenkins agent, create a Dockerfile using one of the official Jenkins agent images as a base.

    FROM jenkins/inbound-agent
RUN apt-get update && apt-get install XXX
COPY your-favorite-tool-here
    FROM jenkins/inbound-agent
RUN apt-get update && apt-get install XXX
COPY your-favorite-tool-here

  9. Configure Docker client connection parameters

    master

    When configuring a connection to a Docker host via the plugin, the following parameters define the client behavior:

    • dockerUri: The URI of the Docker daemon (e.g., tcp://remote-host:2375 or a Unix socket path).
    • credentialsId: The Jenkins Credentials ID used to authenticate with the Docker host.
    • readTimeoutInMsOrNull: The timeout in milliseconds for reading data from the Docker daemon. If null, the default system timeout is used.
    • connectTimeoutInMsOrNull: The timeout in milliseconds for establishing a connection to the Docker daemon. If null, the default system timeout is used.

  10. Configure Docker node provisioning parameters

    master

    When using the Docker pipeline step (implemented via DockerNodeStepExecution), the following parameters are used to provision the agent:

    • image: The Docker image to use for the node.
    • dockerHost: The URL of the Docker daemon (e.g., tcp://remote-host:2375).
    • credentialsId: The ID of the Jenkins credentials to use for connecting to the Docker host.
    • remoteFs: The remote file system path on the Docker container.
    • connector: A DockerComputerConnector implementation (defaults to DockerComputerAttachConnector).

    If neither dockerHost nor credentialsId is provided, the plugin attempts to use the default DockerAPI from the configured DockerCloud in Jenkins.

  11. Access the DockerTransientNode via Pipeline context

    master

    The Docker plugin provides a dynamic context that allows you to access the DockerTransientNode directly within a Jenkins Pipeline block. This is useful when you need to interact with the specific properties or lifecycle of the transient Docker agent being used by the current step.

    To use this, ensure you are within a Docker-based pipeline step. The ProvideDockerTransientNode extension makes the node available in the step context.

    // Note: This is a conceptual representation of how the dynamic context is used in a Pipeline
// The exact syntax depends on the Pipeline DSL implementation provided by the plugin
dockerNode(image: 'my-image') {
    // Inside this block, the DockerTransientNode is available in the context
    def node = dockerNode
    echo "Running on node: ${node.getNodeName()}"
}