mirror of
https://github.com/SAP/jenkins-library.git
synced 2024-12-12 10:55:20 +02:00
dockerExecuteOnKubernetes: generate documentation (#487)
* fix whitespace * correct key order * add docs annotation * add key documentation * remove generated documentation * fix code climate finding
This commit is contained in:
Christopher Fenner
GitHub
parent
8b13164d74
commit
3f12015364
@ -72,7 +72,7 @@ class TemplateHelper {
|
||||
|
||||
parameters.keySet().toSorted().each {
|
||||
def props = parameters.get(it)
|
||||
t += "| `${it}` | ${props.GENERAL_CONFIG ? 'X' : ''} | ${props.STEP_CONFIG ? 'X' : ''} | ${props.STAGE_CONFIG ? 'X' : ''} |\n"
|
||||
t += "| `${it}` | ${props.GENERAL_CONFIG ? 'X' : ''} | ${props.STEP_CONFIG ? 'X' : ''} | ${props.STAGE_CONFIG ? 'X' : ''} |\n"
|
||||
}
|
||||
|
||||
t.trim()
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
## Description
|
||||
|
||||
Executes a closure inside a container in a kubernetes pod. Proxy environment variables defined on the Jenkins machine are also available in the container.
|
||||
Content here is generated from corresponnding step, see `vars`.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
@ -13,65 +13,11 @@ Executes a closure inside a container in a kubernetes pod. Proxy environment var
|
||||
|
||||
## Parameters
|
||||
|
||||
| parameter | mandatory | default | possible values |
|
||||
| ----------|-----------|---------|-----------------|
|
||||
|script|yes|||
|
||||
|containerCommand|no|||
|
||||
|containerCommands|no|||
|
||||
|containerEnvVars|no|||
|
||||
|containerPullImageFlags|no|true|boolean value: `true`, `false` |
|
||||
|containerMap|no|`[:]`||
|
||||
|containerName|no|||
|
||||
|containerPortMappings|no|||
|
||||
|containerShell|no|||
|
||||
|containerWorkspaces|no|||
|
||||
|dockerEnvVars|no|`[:]`||
|
||||
|dockerImage|yes|||
|
||||
|dockerPullImage|no|true|boolean value: `true`, `false` |
|
||||
|dockerWorkspace|no|`''`||
|
||||
|jenkinsKubernetes|no|`[jnlpAgent:s4sdk/jenkins-agent-k8s:latest]`||
|
||||
|stashExcludes|no|`[workspace:nohup.out]`||
|
||||
|stashIncludes|no|`[workspace:**/*.*]`||
|
||||
|
||||
* `script` defines the global script environment of the Jenkins file run. Typically `this` is passed to this parameter. This allows the function to access the [`commonPipelineEnvironment`](commonPipelineEnvironment.md) for storing the measured duration.
|
||||
* `containerCommand`: allows to specify start command for container created with dockerImage parameter to overwrite Piper default (`/usr/bin/tail -f /dev/null`).
|
||||
* `containerCommands` specifies start command for containers to overwrite Piper default (`/usr/bin/tail -f /dev/null`). If container's defaultstart command should be used provide empty string like: `['selenium/standalone-chrome': '']`.
|
||||
* `containerEnvVars` specifies environment variables per container. If not provided `dockerEnvVars` will be used.
|
||||
* `containerPullImageFlags` specifies the pullImage flag per container.
|
||||
* `containerMap` A map of docker image to the name of the container. The pod will be created with all the images from this map and they are labled based on the value field of each map entry.
|
||||
Example: `['maven:3.5-jdk-8-alpine': 'mavenExecute', 'selenium/standalone-chrome': 'selenium', 'famiko/jmeter-base': 'checkJMeter', 's4sdk/docker-cf-cli': 'cloudfoundry']`
|
||||
* `containerName`: optional configuration in combination with containerMap to define the container where the commands should be executed in
|
||||
* `containerPortMappings`: Map which defines per docker image the port mappings, like `containerPortMappings: ['selenium/standalone-chrome': [[name: 'selPort', containerPort: 4444, hostPort: 4444]]]`
|
||||
* `containerShell` allows to specify the shell to be executed for container with containerName
|
||||
* `containerWorkspaces` specifies workspace (=home directory of user) per container. If not provided `dockerWorkspace` will be used. If empty, home directory will not be set.
|
||||
* `dockerImage` Name of the docker image that should be used. If empty, Docker is not used.
|
||||
* `dockerEnvVars` Environment variables to set in the container, e.g. [http_proxy:'proxy:8080']
|
||||
* `dockerPullImage`: Set this to 'false' to bypass a docker image pull. Usefull during development process. Allows testing of images which are available in the local registry only.
|
||||
* `dockerWorkspace` Docker options to be set when starting the container. It can be a list or a string.
|
||||
Content here is generated from corresponnding step, see `vars`.
|
||||
|
||||
## 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||||
|
||||
|containerCommands||X|X|
|
||||
|containerEnvVars||X|X|
|
||||
|containerPullImageFlags||X|X|
|
||||
|containerMap||X|X|
|
||||
|containerName||X|X|
|
||||
|containerPortMappings||X|X|
|
||||
|containerWorkspaces||X|X|
|
||||
|dockerEnvVars||X|X|
|
||||
|dockerImage||X|X|
|
||||
|dockerPullImage||X|X|
|
||||
|dockerWorkspace||X|X|
|
||||
|jenkinsKubernetes|X|||
|
||||
|stashExcludes||X|X|
|
||||
|stashIncludes||X|X|
|
||||
Content here is generated from corresponnding step, see `vars`.
|
||||
|
||||
## Side effects
|
||||
|
||||
|
||||
@ -1,6 +1,7 @@
|
||||
import static com.sap.piper.Prerequisites.checkScript
|
||||
|
||||
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.SystemEnv
|
||||
@ -9,25 +10,77 @@ import hudson.AbortException
|
||||
|
||||
@Field def STEP_NAME = getClass().getName()
|
||||
@Field def PLUGIN_ID_KUBERNETES = 'kubernetes'
|
||||
|
||||
@Field Set GENERAL_CONFIG_KEYS = [
|
||||
'jenkinsKubernetes'
|
||||
]
|
||||
@Field Set STEP_CONFIG_KEYS = GENERAL_CONFIG_KEYS.plus([
|
||||
'containerCommand', // specify start command for container created with dockerImage parameter to overwrite Piper default (`/usr/bin/tail -f /dev/null`).
|
||||
'containerCommands', //specify start command for containers to overwrite Piper default (`/usr/bin/tail -f /dev/null`). If container's default start command should be used provide empty string like: `['selenium/standalone-chrome': '']`
|
||||
'containerEnvVars', //specify environment variables per container. If not provided dockerEnvVars will be used
|
||||
'containerPullImageFlags', // specifies the pullImage flag per container.
|
||||
'containerMap', //specify multiple images which then form a kubernetes pod, example: containerMap: ['maven:3.5-jdk-8-alpine': 'mavenexecute','selenium/standalone-chrome': 'selenium']
|
||||
'containerName', //optional configuration in combination with containerMap to define the container where the commands should be executed in
|
||||
'containerPortMappings', //map which defines per docker image the port mappings, like containerPortMappings: ['selenium/standalone-chrome': [[name: 'selPort', containerPort: 4444, hostPort: 4444]]]
|
||||
'containerShell', // allows to specify the shell to be executed for container with containerName
|
||||
'containerWorkspaces', //specify workspace (=home directory of user) per container. If not provided dockerWorkspace will be used. If empty, home directory will not be set.
|
||||
'dockerImage',
|
||||
'dockerPullImage',
|
||||
'dockerWorkspace',
|
||||
/**
|
||||
* Allows to specify start command for container created with dockerImage parameter to overwrite Piper default (`/usr/bin/tail -f /dev/null`).
|
||||
*/
|
||||
'containerCommand',
|
||||
/**
|
||||
* Specifies start command for containers to overwrite Piper default (`/usr/bin/tail -f /dev/null`).
|
||||
* If container's defaultstart command should be used provide empty string like: `['selenium/standalone-chrome': '']`.
|
||||
*/
|
||||
'containerCommands',
|
||||
/**
|
||||
* Specifies environment variables per container. If not provided `dockerEnvVars` will be used.
|
||||
*/
|
||||
'containerEnvVars',
|
||||
/**
|
||||
* A map of docker image to the name of the container. The pod will be created with all the images from this map and they are labled based on the value field of each map entry.
|
||||
* Example: `['maven:3.5-jdk-8-alpine': 'mavenExecute', 'selenium/standalone-chrome': 'selenium', 'famiko/jmeter-base': 'checkJMeter', 's4sdk/docker-cf-cli': 'cloudfoundry']`
|
||||
*/
|
||||
'containerMap',
|
||||
/**
|
||||
* Optional configuration in combination with containerMap to define the container where the commands should be executed in.
|
||||
*/
|
||||
'containerName',
|
||||
/**
|
||||
* Map which defines per docker image the port mappings, e.g. `containerPortMappings: ['selenium/standalone-chrome': [[name: 'selPort', containerPort: 4444, hostPort: 4444]]]`.
|
||||
*/
|
||||
'containerPortMappings',
|
||||
/**
|
||||
* Specifies the pullImage flag per container.
|
||||
*/
|
||||
'containerPullImageFlags',
|
||||
/**
|
||||
* Allows to specify the shell to be executed for container with containerName.
|
||||
*/
|
||||
'containerShell',
|
||||
/**
|
||||
* Specifies a dedicated user home directory per container which will be passed as value for environment variable `HOME`. If not provided `dockerWorkspace` will be used.
|
||||
*/
|
||||
'containerWorkspaces',
|
||||
/**
|
||||
* 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.
|
||||
*/
|
||||
'dockerImage',
|
||||
/**
|
||||
* Set this to 'false' to bypass a docker image pull.
|
||||
* Usefull during development process. Allows testing of images which are available in the local registry only.
|
||||
*/
|
||||
'dockerPullImage',
|
||||
/**
|
||||
* Specifies a dedicated user home directory for the container which will be passed as value for environment variable `HOME`.
|
||||
*/
|
||||
'dockerWorkspace',
|
||||
/**
|
||||
* Specific stashes that should be considered for the step execution.
|
||||
*/
|
||||
'stashContent',
|
||||
/**
|
||||
*
|
||||
*/
|
||||
'stashExcludes',
|
||||
/**
|
||||
*
|
||||
*/
|
||||
'stashIncludes'
|
||||
])
|
||||
@Field Set PARAMETER_KEYS = STEP_CONFIG_KEYS.minus([
|
||||
@ -35,6 +88,11 @@ import hudson.AbortException
|
||||
'stashExcludes'
|
||||
])
|
||||
|
||||
/**
|
||||
* Executes a closure inside a container in a kubernetes pod.
|
||||
* Proxy environment variables defined on the Jenkins machine are also available in the container.
|
||||
*/
|
||||
@GenerateDocumentation
|
||||
void call(Map parameters = [:], body) {
|
||||
handlePipelineStepErrors(stepName: STEP_NAME, stepParameters: parameters) {
|
||||
|
||||
@ -175,7 +233,7 @@ private List getContainerList(config) {
|
||||
return result
|
||||
}
|
||||
|
||||
/**
|
||||
/*
|
||||
* Returns a list of envVar object consisting of set
|
||||
* environment variables, params (Parametrized Build) and working directory.
|
||||
* (Kubernetes-Plugin only!)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user