dockerExecute

Description

Executes a closure inside a docker container with the specified docker image. The workspace is mounted into the docker image. Proxy environment variables defined on the Jenkins machine are also available in the Docker container.

Parameters

name	mandatory	default	possible values
additionalPodProperties	no
containerCommand	no
containerPortMappings	no
containerShell	no
dockerEnvVars	no
dockerImage	no
dockerName	no
dockerOptions	no
dockerPullImage	no	true
dockerRegistryCredentialsId	no
dockerRegistryUrl	no
dockerVolumeBind	no
dockerWorkspace	no
script	yes
sidecarEnvVars	no
sidecarImage	no
sidecarName	no
sidecarOptions	no
sidecarPullImage	no	true
sidecarReadyCommand	no
sidecarRegistryCredentialsId	no
sidecarRegistryUrl	no
sidecarVolumeBind	no
sidecarWorkspace	no
stashContent	no	[]
stashNoDefaultExcludes	no		true, false

• additionalPodProperties - Kubernetes only: Allows to specify additional pod properties. For more details see step dockerExecuteOnKubernetes
• containerCommand - Kubernetes only: Allows to specify start command for container created with dockerImage parameter to overwrite Piper default (/usr/bin/tail -f /dev/null).
• containerPortMappings - Map which defines per docker image the port mappings, e.g. containerPortMappings: ['selenium/standalone-chrome': [[name: 'selPort', containerPort: 4444, hostPort: 4444]]].
• containerShell - Kubernetes only: Allows to specify the shell to be used for execution of commands.
• dockerEnvVars - Environment variables to set in the container, e.g. [http_proxy: 'proxy:8080'].
• dockerImage - Name of the docker image that should be used. Configure with empty value to execute the command directly on the Jenkins system (not using a container). Omit to use the default image (cf. default_pipeline_environment.yml) Overwrite to use custom Docker image.
• dockerName - Kubernetes only: Name of the container launching dockerImage. SideCar only: Name of the container in local network.
• dockerOptions - Docker only: Docker options to be set when starting the container (List or String).
• dockerPullImage - Set this to 'false' to bypass a docker image pull. Useful during development process. Allows testing of images which are available in the local registry only.
• dockerRegistryCredentialsId - Non Kubernetes only: The credentials for the docker registry of type username/password as we rely on docker jenkins plugin. If left empty, images are pulled anonymously. For Kubernetes cases, pass secret name of type kubernetes.io/dockerconfigjson via additionalPodProperties parameter (The secret should already be created and present in the environment)
• dockerRegistryUrl - The registry used for pulling the docker image, if left empty the default registry as defined by the docker-commons-plugin will be used.
• dockerVolumeBind - Docker only: Volumes that should be mounted into the container.
• dockerWorkspace - Kubernetes only: Specifies a dedicated user home directory for the container which will be passed as value for environment variable HOME.
• script - The common script environment of the Jenkinsfile running. Typically the reference to the script calling the pipeline step is provided with the this parameter, as in script: this. This allows the function to access the commonPipelineEnvironment for retrieving, e.g. configuration parameters.
• sidecarEnvVars - as dockerEnvVars for the sidecar container
• sidecarImage - as dockerImage for the sidecar container
• sidecarName - as dockerName for the sidecar container
• sidecarOptions - as dockerOptions for the sidecar container
• sidecarPullImage - Set this to 'false' to bypass a docker image pull. Useful during development process. Allows testing of images which are available in the local registry only.
• sidecarReadyCommand - Command executed inside the container which returns exit code 0 when the container is ready to be used.
• sidecarRegistryCredentialsId - Same as dockerRegistryCredentialsId, but for the sidecar. If left empty dockerRegistryCredentialsId is used instead.
• sidecarRegistryUrl - Same as dockerRegistryUrl, but for the sidecar. If left empty, dockerRegistryUrl is used instead.
• sidecarVolumeBind - as dockerVolumeBind for the sidecar container
• sidecarWorkspace - as dockerWorkspace for the sidecar container
• stashContent - Specific stashes that should be considered for the step execution.
• stashNoDefaultExcludes - In the Kubernetes case the workspace is only available to the respective Jenkins slave but not to the containers running inside the pod.
  This flag controls whether the stashing does not use the default exclude patterns in addition to the patterns provided in stashExcludes.

Kubernetes support

If the Jenkins is setup on a Kubernetes cluster, then you can execute the closure inside a container of a pod by setting an environment variable ON_K8S to true. However, it will ignore containerPortMappings, dockerOptions and dockerVolumeBind values. dockerExecute step will internally invoke dockerExecuteOnKubernetes step and execute the closure inside a pod.

Step configuration

We recommend to define values of step parameters via config.yml file.

In following sections of the config.yml the configuration is possible:

parameter	general	step/stage
additionalPodProperties		X
containerCommand		X
containerPortMappings		X
containerShell		X
dockerEnvVars		X
dockerImage		X
dockerName		X
dockerOptions		X
dockerPullImage	X	X
dockerRegistryCredentialsId		X
dockerRegistryUrl		X
dockerVolumeBind		X
dockerWorkspace		X
script
sidecarEnvVars		X
sidecarImage		X
sidecarName		X
sidecarOptions		X
sidecarPullImage	X	X
sidecarReadyCommand		X
sidecarRegistryCredentialsId		X
sidecarRegistryUrl		X
sidecarVolumeBind		X
sidecarWorkspace		X
stashContent		X
stashNoDefaultExcludes

Dependencies

The step depends on the following Jenkins plugins

• docker
• kubernetes
• pipeline-utility-steps
• workflow-basic-steps
• workflow-cps-global-lib
• workflow-durable-task-step

The kubernetes plugin is only used if running in a kubernetes environment. Transitive dependencies are omitted.

The list might be incomplete.

Consider using the ppiper/jenkins-master docker image. This images comes with preinstalled plugins.

Side effects

none

Exceptions

none

Pulling images in an non-anonymous way

Credentials are stored by default unencrypted on disk

When accessing a docker registry with credentials for pulling images your credentials for access the docker registry are stored in plain text on disk for a short amount of time. There will be a corresponding log message with level "warning" in the job log. In order to avoid having the credentials written to disk, you should configure a password helper. The log message mentioned previously contains a link to a page explaining how a password helper can be configured. Having the credentials written to disk is not recommended. In addition, we don't recommend using personalised accounts for CI but rather dedicated "technical" users.

Example 1: Run closure inside a docker container

dockerExecute(dockerImage: 'maven:3.5-jdk-7'){
    sh "mvn clean install"
}

Example 2: Run closure inside a container in a kubernetes pod

# set environment variable
export ON_K8S=true"

dockerExecute(script: this, dockerImage: 'maven:3.5-jdk-7'){
    sh "mvn clean install"
}

In the above example, the dockerExecute step will internally invoke dockerExecuteOnKubernetes step and execute the closure inside a pod.

Example 3: Run closure inside a container which is attached to a sidecar container (as for example used in seleniumExecuteTests

dockerExecute(
        script: script,
        containerPortMappings: [containerPortMappings:'selenium/standalone-chrome':[containerPort: 4444, hostPort: 4444]],
        dockerImage: 'node:8-stretch',
        dockerName: 'node',
        dockerWorkspace: '/home/node',
        sidecarImage: 'selenium/standalone-chrome',
        sidecarName: 'selenium',
) {
    git url: 'https://github.com/XXXXX/WebDriverIOTest.git'
    sh '''npm install
          node index.js
    '''
}