Skip to content

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 - The credentials for the docker registry. If left empty, images are pulled anonymously.
  • 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.

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
dockerRegistryCredentialsId X
dockerRegistryUrl X
dockerVolumeBind X
dockerWorkspace X
script
sidecarEnvVars X
sidecarImage X
sidecarName X
sidecarOptions X
sidecarPullImage X
sidecarReadyCommand X
sidecarRegistryCredentialsId X
sidecarRegistryUrl X
sidecarVolumeBind X
sidecarWorkspace X
stashContent X
stashNoDefaultExcludes

Dependencies

The step depends on the following Jenkins plugins

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 dockerEcecute 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
    '''
}