2021-03-01 :: 8 min to read

§ How to create a custom Jenkins Pipeline DSL

// vars/backendPipeline.groovy
def call(Map params) 

backendPipeline([
        branch: "main",
        images: ["app": "DockerImageNameParam", "proxy": "ProxyDockerImageNameParam"], 
        deploy: ["path", "./"],
])

backendPipeline {
    branch "master"

    // module expected to build a docker image and 
    // inject it as a parameter during the deployment with the name
    module "app", export: "DockerImage"
    module "proxy", export: "ProxyDockerImage"

    stack("service") {
        // this is an optional parameter in case we don't need to deploy to both envs we have
        only "staging" // default: "staging" and "prod"

        // some parameters we have to specify manually depending on the env
        params("staging") {
            RemoteBucketParam = "lksd4nnl.s3.aws.com"
        }
        params("prod") {
            RemoteBucketParam = "lksd4nnl.s3.aws.com"
        }
    }
}

class BackendPipelineConfiguration {
    // default values better always to have explicit
    // that would allow to omit them in the dsl on use and make it more compact
    String branch = "master" 
    Map<String, StackConfiguration> stacks = [:]
    Map<String, String> modules = [:] // that would hold results of `module "app", export: "DockerImage"`
}

class StackConfiguration {
    List<String> envs = ["staging", "prod"] // `only "env"` would override this list entirely
    Map<String, Map<String, String>> params = [:] 
    
    Map<String, String> params(String env) {
        return this.params.get(env, [:])
    }
}

class BackendPipelineDSL {
    private final BackendPipelineConfiguration conf

    BackendPipelineDSL(BackendPipelineConfiguration conf) {
        this.conf = conf
    }

    // the simplest possible thing for the dsl - just a method assigning the value
    // args could have default values, so that calling 
    // method without args would still do something
    // keeping it configurable
    void branch(String branch) {
        this.conf.branch = branch
    }

    // this case is interesting, as it would be called as 
    // `module "app", export: "DockerImage"` - with both named and unnamed params
    // however, groovy moves named params to the first place as a map, 
    // so the method call above is actually 
    // module([export: "DockerImage"], "app")
    void module(Map<String, String> args, String name) {
        this.conf.modules[name] = args.export
    }

    // we could go as deep as we need to define more DSL levels with some namespace
    // so here it would be part `stack("service") { ... }` 
    // delegating to a StackConfigurationDSL with
    // StackConfiguration as an object to store result
    void stack(String name, Closure details = {}) { // default empty closure
        def stack = new StackConfiguration()
        details.resolveStrategy = Closure.DELEGATE_FIRST
        details.delegate = new StackConfigurationDSL(stack)
        details()
        this.conf.stacks[name] = stack
    }

    // this method is purely for tests
    static BackendPipelineConfiguration create(Closure body) { 
        def conf = new BackendPipelineConfiguration()
        body.resolveStrategy = Closure.DELEGATE_FIRST
        body.delegate = new BackendPipelineDSL(conf)
        body()
        return conf
    }
}


class StackConfigurationDSL {
    private final StackConfiguration conf

    StackConfigurationDSL(StackConfiguration conf) {
        this.conf = conf
    }

    // replaces the content entirely, as we need either 2 default 
    // envs or just one specific
    void only(String env) {
        this.conf.envs = [env]
    }

    // we don't have to create a full-featured object to store 
    // params if just a map is enough
    void params(String env, Closure body) {
        Map<String, Map<String, String>> params = [:]
        body.resolveStrategy = Closure.DELEGATE_FIRST
        body.delegate = params
        body()
        // don't forget to bring it back to an object we use later
        this.conf.params[env] = params
    }
}

println groovy.json.JsonOutput.prettyPrint(groovy.json.JsonOutput.toJson(BackendPipelineDSL.create {
  // here goes the actual DSL content...
}))

def call(body) {
    // evaluate the body block, and collect configuration into the object
    def conf = new BackendPipelineConfiguration()
    body.resolveStrategy = Closure.DELEGATE_FIRST
    body.delegate = new BackendPipelineDSL(conf)
    body()

    pipeline {
        // entire declarative pipeline... here you can access conf.branch, conf.modules...
    }
}

stages {
    stage("build") {
        stages {
            stage("java") {
                // ...
            }
        }
    }
}

stage('infrastructure') {
    when {
        expression { return conf.deploy == null } // or some other prop
        beforeAgent true // pay attention to this
    }
    agent any

    stages {
        // ...
    }
}

when {
    expression { return fileExists("build.gradle") }
}

// this variable would be available in other 
// stages after to read/write if placed before the `pipeline {`
def images = [:] 

// here goes pipeline { ...

stage("docker build & push") {
    steps {
        script {
            for (module in conf.modules) {
                // some custom step returning the result
                // pay attention to env.JOB_BASE_NAME and 
                // other global envs - they are quite useful to avoid unnecessary params
                images[module.value] = buildAndPush(env.JOB_NAME.split("/")[1] + "-" + module.key, module.key)
            }
        }
    }
}
stage('deploy') {
    steps {
        script {
            // iterate over the map and list from the config to 
            // create a stage via scripted pipeline
            for (stack in conf.stacks) {
                for (env in stack.value.envs) {
                    stage("${stack.key}:${env}") {
                        // some custom step from the vars/deploy.groovy file
                        // stack.value.params(env) is actually a method
                        deploy("${stack.key}-${env}", [ Env: env ] + images + stack.value.params(env)) 
                    }
                }
            }
        }
    }
}