We would like to announce the availability of official Windows agent images for Docker. These images allow provisioning Jenkins agents with Windows OS on Docker and Kubernetes.
New images
All official Docker images for agents now provide nanoserver-1809 and windowsservercore-1809 tags which include Windows images and, at the moment, Java 8 (these are like the latest tag).
We also provide tags with explicit Java selection, e.g. jdk8-windowsservercore-1809 or jdk11-nanoserver-1809.
Version tags are also available, e.g. jenkins/agent:4.3-4-jdk8-nanoserver-1809.
jenkins/agent is a basic agent which bundles the agent.jar for agent ⇐ ⇒ master communication. This is most useful as a base image for other images. Windows images are available starting from version 4.3-4
jenkins/inbound-agent is an agent that is based on the jenkins/agent image above. It provides a wrapper script written in PowerShell to help specify the parameters to agent.jar. Windows images are available starting from version 4.3-4
jenkins/ssh-agent is an image which has OpenSSH installed and should be used with the SSH Build Agents Plugin. Windows images are available starting from version 2.1.0
Using Windows Docker images
To use the new images, you will need a proper Docker or Kubernetes environment which supports running Windows containers. For Windows desktop users, the easiest way is to use Docker for Windows. Windows support in Kubernetes is documented here.
jenkins/agent
The jenkins/agent image is a simple agent with the JDK and the agent.jar (Jenkins Remoting library).
There are two main use cases for this image:
As a base image for other Docker images (e.g.,
FROM jenkins/agent:jdk8-nanoserver-1809in your Dockerfile). The jenkins/inbound-agent is based on this image.This image may also be used to launch an agent using the Launch method of Launch agent via execution of command on the master. This allows the master to launch the agent inside the docker container automatically.
To run the agent for the second use case, you would specify the following command on the Jenkins master after setting Remote root directory to C:\Users\jenkins\agent:
docker run -i --rm --name agent --init jenkins/agent:jdk8-windowsservercore-1809 java -jar C:/ProgramData/Jenkins/agent.jar
jenkins/inbound-agent
The inbound-agent Docker image tries to provide a higher level interaction with the agent.jar executable. It provides a PowerShell wrapper script around agent.jar and it is specified as the entrypoint so that you just need to pass in some command line arguments to run the agent. A pull request has been opened which documents these command line parameters and environment variables.
Example:
docker run jenkins/inbound-agent:windowsservercore-1809 ` -Url http://jenkins-server:port ` -WorkDir=C:/Users/jenkins/Agent ` -Secret <SECRET> ` -Name <AGENTNAME>
Example using environment variables:
docker run -e "JENKINS_URL=http://jenkins-server:port" -e "JENKINS_AGENT_NAME=AGENTNAME" ` jenkins/inbound-agent:windowsservercore-1809 ` -WorkDir=C:/Users/jenkins/Agent ` -Secret <SECRET> ` -Name <AGENTNAME>
The -Url, -Name and -Secret parameters are required, but can be specified as either command line parameters or environment variables. |
jenkins/ssh-agent
As mentioned above the jenkins/ssh-agent docker image is based on SSH communication with the master, rather than the remoting TCP or WebSocket protocols. The image sets up a jenkins user and the OpenSSH server so that the master can connect to the agent via SSH. The image expects an SSH public key as a parameter and puts that key into the authorized_keys file for the jenkins user. The private key should be specified in the agent configuration on the master to allow the master to connect.
Example:
docker run jenkins/ssh-agent:jdk8-windowsservercore-1809 "<public key>"
You can also pass the public key as an environment variable when using docker run.
Example:
docker run -e "JENKINS_AGENT_SSH_PUBKEY=<public key>" jenkins/ssh-agent:jdk8-windowsservercore-1809
You will then be able to connect this agent using the SSH Build Agents Plugin as "jenkins" with the matching private key.
What’s next?
We are considering providing versions based on Windows Server 2019 build 1909 so that Jenkins users can run these images on GKE clusters (see this issue).
We are also looking into providing multiarch manifests which would allow Windows images to be part of the latest tag.
There is also an open pull-request to create a Windows based Docker image for a Jenkins master. There hasn’t been a lot of requests for this, but to make the offerings complete for Windows users, the pull request was created.
For plans unrelated to Windows, please see the Docker images for agents: New names and What’s next blogpost.