diff --git a/documentation/docs/steps/dockerExecute.md b/documentation/docs/steps/dockerExecute.md index e06f42609..5b4eaa1e9 100644 --- a/documentation/docs/steps/dockerExecute.md +++ b/documentation/docs/steps/dockerExecute.md @@ -2,47 +2,11 @@ ## 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. +Content here is generated from corresponnding step, see `vars`. ## Parameters -| parameter | mandatory | default | possible values | -| ----------|-----------|---------|-----------------| -|script|yes||| -|containerCommand|no||| -|containerPortMappings|no||| -|containerShell|no||| -|dockerEnvVars|no|`[:]`|| -|dockerImage|no|`''`|| -|dockerName|no||| -|dockerOptions|no|`''`|| -|dockerVolumeBind|no|`[:]`|| -|dockerWorkspace|no||| -|jenkinsKubernetes|no|`[jnlpAgent:s4sdk/jenkins-agent-k8s:latest]`|| -|sidecarEnvVars|no||| -|sidecarImage|no||| -|sidecarName|no||| -|sidecarOptions|no||| -|sidecarVolumeBind|no||| -|sidecarWorkspace|no||| -* `script` defines the global script environment of the Jenkinsfile run. Typically `this` is passed to this parameter. This allows the function to access the [`commonPipelineEnvironment`](commonPipelineEnvironment.md) for storing the measured duration. -* `containerCommand`: only used in case exeuction environment is Kubernetes, 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, like `containerPortMappings: ['selenium/standalone-chrome': [[name: 'selPort', containerPort: 4444, hostPort: 4444]]]` -* `containerShell`: only used in case exeuction environment is Kubernetes, 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. If empty, Docker is not used and the command is executed directly on the Jenkins system. -* `dockerName`: Kubernetes case: Name of the container launching `dockerImage`, SideCar: Name of the container in local network -* `dockerOptions` Docker options to be set when starting the container. It can be a list or a string. -* `dockerVolumeBind` Volumes that should be mounted into the container. -* `dockerWorkspace`: only relevant for Kubernetes case: specifies a dedicated user home directory for the container which will be passed as value for environment variable `HOME` -* `sidecarEnvVars` defines environment variables for the sidecar container, similar to `dockerEnvVars` -* `sidecarImage`: Name of the docker image of the sidecar container. Do not provide this value if no sidecar container is required. -* `sidecarName`: as `dockerName` for the sidecar container -* `sidecarOptions`: as `dockerOptions` for the sidecar container -* `sidecarVolumeBind`: as `dockerVolumeBind` for the sidecar container -* `sidecarWorkspace`: as `dockerWorkspace` for the sidecar container +Content here is generated from corresponnding step, see `vars`. ## Kubernetes support @@ -50,27 +14,7 @@ If the Jenkins is setup on a Kubernetes cluster, then you can execute the closur ## Step configuration -We recommend to define values of step parameters via [config.yml file](../configuration.md). - -In following sections the configuration is possible: - -| parameter | general | step | stage | -| ----------|-----------|---------|-----------------| -|script|||| -|containerPortMappings||X|X| -|dockerEnvVars||X|X| -|dockerImage||X|X| -|dockerName||X|X| -|dockerOptions||X|X| -|dockerVolumeBind||X|X| -|dockerWorkspace||X|X| -|jenkinsKubernetes|X||| -|sidecarEnvVars||X|X| -|sidecarImage||X|X| -|sidecarName||X|X| -|sidecarOptions||X|X| -|sidecarVolumeBind||X|X| -|sidecarWorkspace||X|X| +Content here is generated from corresponnding step, see `vars`. ## Side effects diff --git a/vars/dockerExecute.groovy b/vars/dockerExecute.groovy index b74283db6..41eca5570 100644 --- a/vars/dockerExecute.groovy +++ b/vars/dockerExecute.groovy @@ -3,6 +3,7 @@ import static com.sap.piper.Prerequisites.checkScript import com.cloudbees.groovy.cps.NonCPS import com.sap.piper.ConfigurationHelper +import com.sap.piper.GenerateDocumentation import com.sap.piper.JenkinsUtils import com.sap.piper.Utils import com.sap.piper.k8s.ContainerMap @@ -13,28 +14,91 @@ import groovy.transform.Field @Field def PLUGIN_ID_DOCKER_WORKFLOW = 'docker-workflow' @Field Set GENERAL_CONFIG_KEYS = [ + /** + * + */ 'jenkinsKubernetes' ] @Field Set STEP_CONFIG_KEYS = GENERAL_CONFIG_KEYS.plus([ - 'containerPortMappings', + /** + * Kubernetes only: + * Allows to specify start command for container created with dockerImage parameter to overwrite Piper default (`/usr/bin/tail -f /dev/null`). + */ 'containerCommand', + /** + * Map which defines per docker image the port mappings, e.g. `containerPortMappings: ['selenium/standalone-chrome': [[name: 'selPort', containerPort: 4444, hostPort: 4444]]]`. + */ + 'containerPortMappings', + /** + * Kubernetes only: + * Allows to specify the shell to be used for execution of commands. + */ 'containerShell', + /** + * Environment variables to set in the container, e.g. [http_proxy: 'proxy:8080']. + */ 'dockerEnvVars', + /** + * Name of the docker image that should be used. If empty, Docker is not used and the command is executed directly on the Jenkins system. + */ 'dockerImage', + /** + * Kubernetes only: + * Name of the container launching `dockerImage`. + * SideCar only: + * Name of the container in local network. + */ 'dockerName', + /** + * Docker options to be set when starting the container (List or String). + */ 'dockerOptions', - 'dockerWorkspace', + /** + * Volumes that should be mounted into the container. + */ 'dockerVolumeBind', + /** + * Kubernetes only: + * Specifies a dedicated user home directory for the container which will be passed as value for environment variable `HOME`. + */ + 'dockerWorkspace', + /** + * as `dockerEnvVars` for the sidecar container + */ 'sidecarEnvVars', + /** + * as `dockerImage` for the sidecar container + */ 'sidecarImage', + /** + * as `dockerName` for the sidecar container + */ 'sidecarName', + /** + * as `dockerOptions` for the sidecar container + */ 'sidecarOptions', - 'sidecarWorkspace', + /** + * as `dockerVolumeBind` for the sidecar container + */ 'sidecarVolumeBind', + /** + * as `dockerWorkspace` for the sidecar container + */ + 'sidecarWorkspace', + /** + * Specific stashes that should be considered for the step execution. + */ 'stashContent' ]) @Field Set PARAMETER_KEYS = STEP_CONFIG_KEYS +/** + * 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. + */ +@GenerateDocumentation void call(Map parameters = [:], body) { handlePipelineStepErrors(stepName: STEP_NAME, stepParameters: parameters) {