DOCSEARCHbyAlgolia
Submit Docs

Jenkins Agent Docker Images

repository·master·Indexed 43 days ago

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

Official Docker images for Jenkins agents, providing the `jenkins/agent` base image for controller-initiated connections and the `jenkins/inbound-agent` image for agents establishing inbound connections via TCP or WebSockets. Supports multiple OS flavors (Alpine, Debian, RHEL, Windows Server Core) and JDK versions.

Tokens
3.4K
Snippets
16
Records
24
Agent score
56%

What's inside Jenkins Agents

  1. Overview of Jenkins Agent Docker images

    master

    This repository provides Docker image definitions for two types of Jenkins agents:

    1. agent: A base image containing the JDK and the Jenkins agent executable (agent.jar). This is typically used when the Jenkins controller initiates a connection to the agent (e.g., via SSH).
    2. inbound-agent: An image built on top of agent specifically designed for agents that establish an inbound connection to the Jenkins controller using TCP or WebSockets.

  3. Use the `jenkins/inbound-agent` image for inbound connections

    master
    The jenkins/inbound-agent image is based on the agent image. Use this image when your Jenkins agents need to establish an inbound connection to the Jenkins controller via TCP or WebSockets.

  5. Configure Agent Work Directories

    master

    Starting from Remoting 3.8, you can use the -workDir flag to enable Work directories. This provides default logging and changes the JAR Caching behavior. When using work directories, ensure you mount a volume to the directory specified in the -workDir argument.

    Linux Example:

    • Mount volume to: /home/jenkins/agent
    • Command flag: -workDir /home/jenkins/agent

    Windows Example:

    • Mount volume to: C:/Users/jenkins/Work
    • Command flag: -workDir C:/Users/jenkins/Work
    # Linux with Work Directory
docker run -i --rm --name agent1 --init -v agent1-workdir:/home/jenkins/agent jenkins/agent java -jar /usr/share/jenkins/agent.jar -workDir /home/jenkins/agent

  6. Build and test images on Windows using `make.ps1`

    master

    On Windows, use the .uild.ps1 PowerShell script to manage builds and tests.

    Building

    Run .uild.ps1 to build images corresponding to the "windows" target in docker-bake.hcl.

    Note: The script generates a build-windows_<AGENT_TYPE>_<WINDOWS_FLAVOR>_<WINDOWS_VERSION>.yaml docker-compose file on its first run. You can modify this file directly and rerun the script, or use .uild.ps1 -OverwriteDockerComposeFile to regenerate it from the bake file.

    Testing

    • Run all tests: .uild.ps1 test
    • Debug tests (shows commands and stderr): .uild.ps1 test -TestsDebug 'debug'
    • Verbose tests (shows stdout): .uild.ps1 test -TestsDebug 'verbose'
    • Dry run (prints commands without executing): .uild.ps1 test -DryRun

    Filtering builds/tests

    You can limit the scope using these parameters:

    • -ImageType: Specify Windows flavors (nanoserver, windowsservercore) and versions (ltsc2022, ltsc2025). Example: .uild.ps1 -ImageType 'nanoserver-ltsc2022'
    • -AgentType: Specify agent or inbound-agent. Example: .uild.ps1 -AgentType 'agent'
    # Example: Build only nanoserver ltsc2022 images
.\make.ps1 -ImageType 'nanoserver-ltsc2022'

  7. Run the Jenkins Agent via Launch command

    master

    You can use the jenkins/agent image to launch an agent using the Launch method of Launch agent via execution of command on the controller. This requires running the agent.jar executable inside the container.

    Linux Requirements:

    • Set Remote root directory in Jenkins to /home/jenkins/agent.
    • Use the command: java -jar /usr/share/jenkins/agent.jar.

    Windows Containers Requirements:

    • Set Remote root directory in Jenkins to C:\Users\jenkins\Agent.
    • Use the command: java -jar C:/ProgramData/Jenkins/agent.jar.
    # Linux example
docker run -i --rm --name agent --init jenkins/agent java -jar /usr/share/jenkins/agent.jar

  8. Run the inbound-agent Docker container on Linux

    master

    To run the inbound agent on a Linux host, use the jenkins/inbound-agent image. It is highly recommended to use the --init flag to ensure correct subprocess handling (zombie reaping).

    Replace <secret> and <agent name> with the values obtained from the Jenkins controller setup.

    docker run --init jenkins/inbound-agent -url http://jenkins-server:port <secret> <agent name>

  9. Setup an inbound Jenkins agent on the controller

    master

    Before running the container, you must register the agent in the Jenkins controller to obtain a connection secret.

    1. Navigate to Manage Jenkins > Nodes.
    2. Select New Node.
    3. Enter a name (e.g., agent1) and select Permanent Agent.
    4. Configure the node settings (remote root directory, labels, executors, etc.).
    5. Crucial: Set the Launch method to Launch agent by connecting it to the controller.
    6. Save the node. The node will appear as 'offline'.
    7. Click on the node to view its details and locate the secret value. This secret is required to authenticate the container.

  10. Configure Timezones for the Jenkins Agent

    master

    By default, the image uses the Etc/UTC timezone. You can change this using one of three methods:

    1. Environment Variable: Set the TZ POSIX environment variable (e.g., TZ=Asia/Shanghai).
    2. Volume Mounts: Mount the host's /etc/localtime and /etc/timezone files as read-only (ro).
    3. Dockerfile (Custom Image): If building a custom image based on jenkins/agent, set the TZ env var and reconfigure tzdata.

    Example using Environment Variable:

    docker run --rm --tty --interactive --env TZ=Asia/Shanghai --entrypoint=date jenkins/agent
    # Example: Setting timezone via TZ environment variable
docker run --rm --tty --interactive --env TZ=Asia/Shanghai --entrypoint=date jenkins/agent

  11. Run the inbound-agent Docker container on Windows

    master

    For Windows environments, use the specific Windows Server Core image. Note that command-line parameters use capitalized flags (e.g., -Url, -Secret, -Name).

    docker run jenkins/inbound-agent:windowsservercore-ltsc2022 -Url http://jenkins-server:port -Secret <secret> -Name <agent name>

  12. Configure Windows Jenkins Java Opts

    master

    When using JENKINS_JAVA_OPTS or the -JenkinsJavaOpts parameter on Windows, the values follow PowerShell command parsing semantics. If a parameter contains characters used in PowerShell expressions, it must be quoted.

    Examples:

    • To pass -XX:+PrintCommandLineFlags --show-version, use: "-XX:+PrintCommandLineFlags" --show-version
    • To pass a property with a space like -Dsome.property=some value, use: "-Dsome.property='some value'"