Unable to use the Docker Pipeline plugin with RHEL 8 and 9

2 minute readKnowledge base

Issue

When trying to use the Docker Pipeline plugin on RHEL 8 or 9, it fails with errors such as:

ERROR: The docker version is less than v1.7. Pipeline functions requiring 'docker exec' (e.g. 'docker.inside') or SELinux labeling will not work.
Finished: FAILURE

Note: Error message from JENKINS-63233: Unable to use it with podman-docker

Environment

Resolution

Read the following Knowledge Base article to learn about the change from docker to podman: Is the docker package available for Red Hat Enterprise Linux 8 and 9?

The recommended resolution to this problem is not utilize the Docker Pipeline plugin on RHEL 8 or 9, and instead directly invoke the desired podman commands from a Pipeline sh step.

Workaround 1: Install Docker CE

If you do not want to refactor your Pipelines, a workaround, although not supported, would be to install the docker-ce packages for CentOS:

Then when running a Pipeline with a step such as:

   docker.image('maven:3.8.6-openjdk-8').inside {
     sh 'mvn --version'
   }

You will see that the plugin works again:

[Pipeline] withEnv
[Pipeline] {
[Pipeline] sh
+ docker pull maven:3.8.6-openjdk-8
...
[Pipeline] withDockerContainer
...
$ docker top ac24f17815df08510c3fe3230b46853f0a79b79c88e850d498371bb5a0c7de41 -eo pid,comm
[Pipeline] {
[Pipeline] sh
+ mvn --version
Apache Maven 3.8.6 (84538c9988a25aec085021c365c560670ad80f63)
Maven home: /usr/share/maven
Java version: 1.8.0_342, vendor: Oracle Corporation, runtime: /usr/local/openjdk-8/jre
Default locale: en, platform encoding: UTF-8
OS name: "linux", version: "4.18.0-477.13.1.el8_8.x86_64", arch: "amd64", family: "unix"
[Pipeline] }
$ docker stop --time=1 ac24f17815df08510c3fe3230b46853f0a79b79c88e850d498371bb5a0c7de41
$ docker rm -f --volumes ac24f17815df08510c3fe3230b46853f0a79b79c88e850d498371bb5a0c7de41
[Pipeline] // withDockerContainer
[Pipeline] }
[Pipeline] // script
[Pipeline] }
[Pipeline] // stage
[Pipeline] }
[Pipeline] // node
[Pipeline] End of Pipeline
Finished: SUCCESS

Workaround 1: Tested product/plugin versions

Workaround 2: Emulate Docker CLI with Podman

This workaround will still be using Podman to run the containers, but will be emulating Docker CLI with a shell script, similar to Emulating Docker CLI with Podman.

We will create a modified docker script to remove the user argument -u UID:GID that the Docker Pipeline plugin adds here, so when calling Podman it can run as the user Podman decides the container should run as, as per simplytim.io/using-podman-with-docker-plugin-in-jenkins/ Using Podman with Docker Plugin in Jenkins.

Create a /usr/local/bin/docker script with the content:

#!/usr/bin/bash
[ -e /etc/containers/nodocker ] || \
echo "Emulate Docker CLI using podman. Create /etc/containers/nodocker to quiet msg." >&2

declare -a finalopts
finalopts=()

USERCHECK=0
for o in "$@"; do
  if [[ "$o" = "-u" && $USERCHECK = 0 ]] ; then
    USERCHECK=1
    continue
  fi
  if [[ $USERCHECK = 1 ]] ; then
    USERCHECK=0
    continue
  fi

  finalopts+=("$o")
done

exec podman "${finalopts[@]}"
▼

Then make the script executable, and optionally touch the nodocker file to clear the warning message:

chmod +x /usr/local/bin/docker
touch /etc/containers/nodocker
▼

With these steps, your Pipelines and your controller don’t require changes for your jobs to continue working well with Podman.

Here’s a demo using this workaround:

docker.image('docker.io/maven:3.8.6-openjdk-8').inside {
  sh 'mvn --version'
}
▼

When run, this build is successful:

successful build using Docker CLI emulation

Related reading https://www.redhat.com/sysadmin/rootless-podman

Workaround 2: Tested product/plugin versions

This article is part of our Knowledge Base and is provided for guidance-based purposes only. The solutions or workarounds described here are not officially supported by CloudBees and may not be applicable in all environments. Use at your own discretion, and test changes in a safe environment before applying them to production systems.