class PipelineRunner extends java.lang.Object
Provides an interface to common pipeline build/run/deploy functions.
You must provide the Jenkins workflow script sandbox object that will be
used to declare Jenkins pipeline steps.
// With just the Jenkins context
def pipeline = new PipelineRunner(this)
// Or with a map of additional settings
def pipeline = new PipelineRunner(this, configPath: "dist/pipeline", registry: "foo.registry")
Modifiers | Name | Description |
---|---|---|
class |
PipelineRunner.RunResult |
State of a run container returned by run. |
Type | Name and description |
---|---|
java.lang.Object |
allowedCredentials A map of allowed credentials Ids and their binding for this pipeline ([credentialId: credentialbinding]) |
java.lang.Object |
allowedTriggerJobs A list of allowed trigger jobs for this pipeline |
java.lang.Object |
blubberConfig Relative path to Blubber config file. |
java.lang.Object |
buildkitAllowedFrontends Allowed BuildKit frontend image names. |
java.lang.Object |
buildkitFrontend Image ref of the buildkit frontend to use during builds. |
java.lang.Object |
chartRepository Default helm chart registry for helm charts |
java.lang.Object |
configPath Directory in which pipeline configuration is stored. |
java.lang.Object |
deleteTempFiles Delete temporary files after use. |
java.lang.Object |
helmConfig Relative path to Helm config file. |
java.lang.Object |
httpProxy HTTP proxy to provide to pipeline configurations. |
java.lang.Object |
kubeConfig Absolute path to a Kubernetes config file to specify when executing `helm` or other k8s related commands. |
java.lang.Object |
namespace Namespace used for Helm/Kubernetes deployments. |
java.lang.Object |
pullPolicy Docker pull policy when deploying. |
java.lang.Object |
registry Default Docker registry host used when qualifying public image URLs. |
java.lang.Object |
registryCredential Jenkins credential used to authenticate against the configured registry. |
java.lang.Object |
registryInternal Alternative Docker registry host used only when registering images. |
java.lang.Object |
registryPushMethod Method of pushing remote images to the configured registry. |
java.lang.Object |
repository Default Docker registry repository used for tagging and registering images. |
java.lang.Object |
runWrapper A closure used to process all run step commands just prior to execution, typically enforcing the shell interpreter and shell behavior. |
java.lang.Object |
timeout Timeout for deployment using Helm. |
java.lang.Object |
workflowScript Jenkins Pipeline Workflow context. |
Constructor and description |
---|
PipelineRunner
(java.util.Map settings = [:], java.lang.Object workflowScript) Constructor with Jenkins workflow script context and settings. |
Type Params | Return Type | Name and description |
---|---|---|
|
java.lang.String |
assignLocalName(java.lang.Object imageID) Assigns to the given image a random name that can be used as a reference for other applications in the same pipeline where an ID is not suitable, such as use as a base image in the build of a subsequent stage. |
|
java.lang.String |
build(java.lang.String variant, java.util.Map labels = [:], java.net.URI context = URI.create(".", java.util.List excludes = null, java.lang.String imagePullPolicy = "always") Builds the given image variant and returns an ID for the resulting image. |
|
void |
commitAndPush(java.util.Map options = [:]) |
|
java.lang.String |
copyFilesFrom(java.lang.String container, java.lang.String source, java.lang.String destination, java.lang.Object archive = false) Copies files from the filesystem of the given stopped container into the working directory. |
|
java.lang.String |
deploy(java.lang.String imageName, java.lang.String imageTag, java.util.Map overrides = [:]) Deploys the given registered image using the configured Helm chart and returns the name of the release. |
|
java.lang.String |
deployWithChart(java.lang.String chart, java.lang.String chartVersion, java.lang.String imageName, java.lang.String imageTag, java.lang.Object helmTimeout = timeout, java.util.Map overrides = [:]) Deploys the given registered image using the given Helm chart and returns the name of the release. |
|
java.lang.String |
getConfigFile(java.lang.String filePath, boolean absolute = false) Returns a path under configPath to the given config file. |
|
java.lang.String |
getTempFile(java.lang.String baseName, boolean absolute = false) Returns a path under configPath to a temp file with the given base name. |
|
boolean |
hasAllowedFrontend(java.lang.String cfg) Tests the given config string and returns whether the BuildKit frontend referenced in the syntax line is allowed to be used over ours. |
|
java.lang.Boolean |
isDirectory(java.lang.String path) Whether the given path is a directory or not. |
|
void |
kubeCmd(java.lang.String cmd) Execute a helm command |
|
void |
purgeRelease(java.lang.String release) Deletes and purges the given Helm release. |
|
void |
purgeReleases(java.util.List releases) Deletes and purges the given Helm release. |
|
java.lang.String |
qualifyRegistryPath(java.lang.String name, java.lang.String registryName = "") Fully qualifies an image name to a public registry path. |
|
java.lang.String |
registerAs(java.lang.String imageID, java.lang.String name, java.lang.String tag) Name and push an image specified by the given image ID to the WMF Docker registry. |
|
void |
removeContainers(java.util.List containers) Removes the given containers, forcefully stopping them if they're still running. |
|
void |
removeImage(java.lang.String imageID) Removes the given image from the local cache. |
|
void |
removeImages(java.util.List imageIDs) Removes the given images from the local cache. |
|
void |
reportImageToGerrit(java.lang.Object imageName, java.lang.Object imageTags = []) Submits a comment to Gerrit with the build result and links to published images. |
|
PipelineRunner.RunResult |
run(java.util.Map args) |
|
PipelineRunner.RunResult |
run(java.lang.String imageID, java.util.List arguments = [], java.util.Map envVars = [:], java.util.List creds = [], java.lang.Integer outputLines = 0, java.lang.Boolean removeContainer = false) Runs a container using the image specified by the given ID. |
|
void |
testRelease(java.lang.String release) Runs end-to-end tests for the given release via `helm test`. |
|
void |
triggerJob(java.util.Map options) Trigger a downstream job on the local Jenkins server |
|
void |
updateChart(java.lang.Object chart, java.lang.Object version, java.lang.Object environments) |
|
void |
updateCharts(java.util.List promote, java.util.List reviewers) |
|
java.lang.Object |
withBlubberConfig(java.lang.Object bc, groovy.lang.Closure c) Temporarily overrides the blubberConfig with the given config which can either be a path to a new config file or an object containing valid inline Blubber configuration. |
|
void |
withDocker(java.util.Map config, groovy.lang.Closure c) Evaluates the given closure, passing it a docker command that uses the given Docker configuration. |
|
java.lang.String |
withOutput(java.lang.String cmd, java.lang.Integer lines = -1, groovy.lang.Closure c) Rewrites the given command with a stdout redirect to `tee` to both capture its output to a file and maintain its output to the console. |
|
void |
withTempDirectory(groovy.lang.Closure c) Creates a temporary directory, calls the given closure with the directory as an argument, and ensures the directory is removed. |
|
java.lang.Object |
withTempFile(java.lang.String prefix, groovy.lang.Closure c) Generates a path to a new temporary file under the pipeline directory, calls the given closure using the new path, and cleans up by deleting the temporary file. |
Methods inherited from class | Name |
---|---|
class java.lang.Object |
java.lang.Object#wait(long), java.lang.Object#wait(long, int), java.lang.Object#wait(), java.lang.Object#equals(java.lang.Object), java.lang.Object#toString(), java.lang.Object#hashCode(), java.lang.Object#getClass(), java.lang.Object#notify(), java.lang.Object#notifyAll() |
A map of allowed credentials Ids and their binding for this pipeline ([credentialId: credentialbinding])
A list of allowed trigger jobs for this pipeline
Relative path to Blubber config file.
Allowed BuildKit frontend image names. The image names listed here are allowed to be used instead of the default buildkitFrontend, via a syntax line. (Any version of these images is allowed.)
Image ref of the buildkit frontend to use during builds. The image name used here must also be listed in buildkitAllowedFrontends.
Default helm chart registry for helm charts
Directory in which pipeline configuration is stored.
Delete temporary files after use.
Relative path to Helm config file.
HTTP proxy to provide to pipeline configurations.
Absolute path to a Kubernetes config file to specify when executing `helm` or other k8s related commands. By default, none will be specified.
Namespace used for Helm/Kubernetes deployments.
Docker pull policy when deploying.
Default Docker registry host used when qualifying public image URLs.
Jenkins credential used to authenticate against the configured registry. Only used when registryPushMethod is set to "docker-push".
Alternative Docker registry host used only when registering images.
Method of pushing remote images to the configured registry. Either "wmf-pusher" to use the "docker-pusher" wrapper script which uses hardcoded and protected credentials or "docker-push" which uses the standard Docker CLI but requires a registryCredential to be set.
Default Docker registry repository used for tagging and registering images.
A closure used to process all run step commands just prior to execution, typically enforcing the shell interpreter and shell behavior.
Timeout for deployment using Helm.
Jenkins Pipeline Workflow context.
Constructor with Jenkins workflow script context and settings.
settings
- Property map.workflowScript
- Jenkins workflow script sandbox object.Assigns to the given image a random name that can be used as a reference for other applications in the same pipeline where an ID is not suitable, such as use as a base image in the build of a subsequent stage.
imageID
- ID of image to name.Builds the given image variant and returns an ID for the resulting image.
variant
- Image variant name that should be built.labels
- Additional name/value labels to add to the image metadata.context
- Build context given to `docker build`. Default is "."
(current directory).excludes
- Files/directories to exclude from build context. This
will be used to overwrite any existing .dockerignore prior to the build.imagePullPolicy
- If "always", pass --pull to docker build.Copies files from the filesystem of the given stopped container into the working directory.
container
- Container ID or name.source
- Source path relative to the container's root (/) directory.destination
- Destination path relative to the working directory.archive
- Archive destination path as a Jenkins artifact. If
destination
is a directory, it will be archived as a tar.gz
file.archive
is false
)Deploys the given registered image using the configured Helm chart and returns the name of the release.
imageName
- Name of the registered image to deploy.imageTag
- Tag of the registered image to use.overrides
- Additional Helm value overrides to set.Deploys the given registered image using the given Helm chart and returns the name of the release.
chart
- Chart URL.chartVersion
- the version of the chart.imageName
- Name of the registered image to deploy.imageTag
- Tag of the registered image to use.timeout
- Timeout length in secondsoverrides
- Additional Helm value overrides to set.Returns a path under configPath to the given config file.
filePath
- Relative file path.absolute
- Return the absolute path.Returns a path under configPath to a temp file with the given base name.
baseName
- File base name.absolute
- Return the absolute path.Tests the given config string and returns whether the BuildKit frontend referenced in the syntax line is allowed to be used over ours.
Whether the given path is a directory or not. If no file or directory exists at the given path, false is returned.
path
- File/directory path.Execute a helm command
Deletes and purges the given Helm release.
release
- Previously deployed release name.Deletes and purges the given Helm release.
release
- Previously deployed release name.Fully qualifies an image name to a public registry path.
name
- Image name.registryName
- Alternative registry. Defaults to registry. Name and push an image specified by the given image ID to the WMF Docker
registry.
By default, the repo name is enforced as "docker-registry.wikimedia.org",
and the remote path prefix is enforced as "/wikimedia/". These can be
changed by setting registry and repository. The method
and credential used to push to the registry can be configured by setting
registryPushMethod and registryCredential.
// Pushes built image to docker-registry.wikimedia.org/wikimedia/mathoid:build-123
def image = pipeline.build("production")
pipeline.registerAs(image, "mathoid", "build-123")
imageID
- Image ID.name
- Remote name to use for the image.tag
- Remote tag to use for the image.Removes the given containers, forcefully stopping them if they're still running.
containers
- List of container IDs/names.Removes the given image from the local cache. All tags are removed from the image as well.
imageID
- ID of the image to remove.Removes the given images from the local cache.
imageIDs
- IDs of images to remove.Submits a comment to Gerrit with the build result and links to published images.
imageName
- Fully qualified name of published image.imageTags
- Image tags.Runs a container using the image specified by the given ID.
imageID
- Image ID.arguments
- Entry-point arguments.envVars
- Environment variables to set.creds
- Credentials to expose to the running container process.outputLines
- Return the last n lines of the container's output.removeContainer
- If true, remove the container after the process existsoutputLines
of the container's output
and container name.Runs end-to-end tests for the given release via `helm test`.
release
- Previously deployed release name.Trigger a downstream job on the local Jenkins server
options
- for the build stepTemporarily overrides the blubberConfig with the given config which can either be a path to a new config file or an object containing valid inline Blubber configuration.
Evaluates the given closure, passing it a docker command that uses the given Docker configuration.
Rewrites the given command with a stdout redirect to `tee` to both capture its output to a file and maintain its output to the console. The rewritten command is passed to the given closure for execution and the output-file contents are returned following deletion of the temporary file.
Creates a temporary directory, calls the given closure with the directory as an argument, and ensures the directory is removed.
Generates a path to a new temporary file under the pipeline directory, calls the given closure using the new path, and cleans up by deleting the temporary file.
Groovy Documentation