The following plugin provides functionality available through Pipeline-compatible steps. Read more about how to integrate steps into your Pipeline in the Steps section of the Pipeline Syntax page.

For a list of other such plugins, see the Pipeline Steps Reference page.

External Workspace Manager Plugin

View this plugin on the Plugins site

exws: Use external workspace

Based on the input parameter, it defines the local path to the workspace, and switches to it. The complete workspace path follows the pattern:

/nodeMountPoint/physicalPathOnDisk/$JOB_NAME/$BUILD_NUMBER

where
  • nodeMountPoint is defined either in the Node configuration, External Workspace section, or in the Jenkins global config, the External Workspace Template section. Firstly it searches for the disk definition in the Jenkins global config (the Template lookup is done based on the Node label parameter), then it fallbacks to searching in the Node configuration.
  • physicalPathOnDisk is defined in the Jenkins global config, the External Workspace Definitions section.
  • externalWorkspace

    The object returned by the exwsAllocate step.

    Basic usage:

        def extWorkspace = exwsAllocate diskPoolId: 'diskpool1'
    node ('linux') {
        exws (extWorkspace) {
            scm checkout
            sh 'mvn clean install -DskipTests'
        }
    }
    node ('test') {
        exws (extWorkspace) {
            sh 'mvn test'
        }
    }
    • Type: class org.jenkinsci.plugins.ewm.model.ExternalWorkspace

exwsAllocate: Allocate external workspace

Allocates a disk from the given Disk Pool Ref ID. By default, the disk with the most available space is selected. On that disk, it computes the workspace path based on the formula: physicalPathOnDisk/$JOB_NAME/$BUILD_NUMBER, where physicalPathOnDisk is defined in the Jenkins global config, External Workspace Definitions section.

If you provide the Upstream parameter, then the Disk Pool Ref ID parameter will be ignored. In this case, the step will allocate the same workspace as used by its upstream job. By default, it will select the workspace used by the last stable build from the upstream job.

  • diskPoolId : String
    The reference to the Disk Pool ID defined in the Jenkins global config.
  • path : String (optional)

    The workspace path on the Disk can be configured within the Build DSL. If the path parameter is provided, the exwsAllocate step will allocate this workspace path on the Disk. If it's not provided, the exwsAllocate step will fallback to using the Workspace path template parameter defined in the Jenkins global config, External Workspace Definitions section, if any.

    Basic Pipeline example:

        def customPath = "${env.JOB_NAME}/${PULL_REQUEST_NUMBER_PARAM}/${env.BUILD_NUMBER}"
    def extWorkspace = exwsAllocate diskPoolId: 'diskpool1', path: customPath
    ...

    Note: It's recommended to use ${ } for variable declaration, instead of standalone $ symbol, as shown in the examples.

  • selectedRun (optional)

    If you provide this parameter, the exwsAllocate step will allocate the first workspace used by the selected run.

    This is a RunWrapper object. You can get a reference by using the runSelector step from the Run Selector Plugin.

    Basic usage example:

        def run = selectRun 'upstream-project-name'
    def extWorkspace = exwsAllocate selectedRun: run
    ...
    • Type: class org.jenkinsci.plugins.workflow.support.steps.build.RunWrapper
  • strategy (optional)

    Provide Disk allocation strategy as step parameter. This will override the strategy defined in the Jenkins global config.

    Note: Some Disk allocation strategies may require additional information to be provided. For example, if you choose the fastest read/write speed strategy, then you must provide, for each disk, its read/write speeds. These values should be set in the Disk Information section, for each Disk entry from the Jenkins global config.

      Nested Choice of Objects
    • fastestReadSpeed
      • estimatedWorkspaceSize : long (optional)

        Optional parameter. It indicates the estimated size that the workspace may have. It has to be in MB.

        If provided, the Disk allocation strategy ensures that the selected disk has at least as much usable space left as the estimated workspace size.

        For example, let's suppose we want to select the disk with the highest read speed, but that has a minimum usable space of 100 MB. The Pipeline code for that is:

            def extWorkspace = exwsAllocate diskPoolId: 'diskpool1', strategy: fastestReadSpeed(estimatedWorkspaceSize: 100)
    // ...
    • fastestWriteSpeed
      • estimatedWorkspaceSize : long (optional)

        Optional parameter. It indicates the estimated size that the workspace may have. It has to be in MB.

        If provided, the Disk allocation strategy ensures that the selected disk has at least as much usable space left as the estimated workspace size.

        For example, let's suppose we want to select the disk with the highest read speed, but that has a minimum usable space of 100 MB. The Pipeline code for that is:

            def extWorkspace = exwsAllocate diskPoolId: 'diskpool1', strategy: fastestReadSpeed(estimatedWorkspaceSize: 100)
    // ...
    • mostUsableSpace
      • estimatedWorkspaceSize : long (optional)

        Optional parameter. It indicates the estimated size that the workspace may have. It has to be in MB.

        If provided, the Disk allocation strategy ensures that the selected disk has at least as much usable space left as the estimated workspace size.

        For example, let's suppose we want to select the disk with the highest read speed, but that has a minimum usable space of 100 MB. The Pipeline code for that is:

            def extWorkspace = exwsAllocate diskPoolId: 'diskpool1', strategy: fastestReadSpeed(estimatedWorkspaceSize: 100)
    // ...

Was this page helpful?

Please submit your feedback about this page through this quick form.

Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?

    


See existing feedback here.