Jenkins实践指南-05-Jenkins pipeline 语法01

3. Jenkins pipeline 语法

3.1 pipeline 组成

    Jenkins pipeline 是基于Groovy语言实现的一种DSL(领域特定语言),用于描述整条流水线是如何进行的。流水线的主要内容包括源码拉取构建打包部署测试生成报告等步骤。

    从源码管理仓库到生成测试报告这些过程中,可以根据需要分成若干阶段,而每个阶段仅处理一件事情,而每个阶段也可以通过多个步骤来完成,因此我们可以基于这些阶段和步骤些进行抽象,形成工程化的pipeline,因此一个基本的pipeline示例如下所示:

pipeline{
 agent any
 stages{
   stage("Sample stage"){
     steps {
       echo "Hi,Surpass.Welcome visit my blog:https://www.cnblogs.com/surpassme/"
     }
   }
 }
}

    以上示例详细解释如下所示:

  • pipeline:代表整条流水线,包含整条流水线的逻辑
  • agent:指定流水线的运行位置

流水线的中每个阶段都必须在某个地方(例如物理机、虚拟机或容器)运行,因此可能通过指定 agent部分来指定具体在哪里运行。

  • stages:流水线中多个stage的容器。该部分至少包含一个stage
  • stage:表示阶段,代表流水线的阶段,每个阶段必须有名称
  • steps:表示阶段中的一个或多个具体步骤的容器

1.steps至少包含一个步骤
2.在一个stage中仅有一个steps

    以上每一个部分都是必需的,否则Jenkins都会报错

官方参考文档:https://www.jenkins.io/doc/pipeline/steps/

3.2 pipeline 支持的命令

    基本的pipeline结构是无法满足日常现实多变的需求。因此,Jenkins pipeline可以通过各种指令来扩展丰富自己。以下为Jenkins pipeline支持的命令。

3.2.1 environment

    environment主要用于设置环境变量。可以定义在stagepipeline部分。环境变量可以分为:Jenkins内置变量自定义环境变量

3.2.1.1 Jenkins 内置环境变量

    在执行pipeline时,可以通过env命令来获取Jenkins的全部内置环境变量,其主要使用方法如下所示:

pipeline {
    agent any
    stages{
        stage("PrintEnviroment"){
            steps{
                // method A
                echo "Running ${env.BUILD_ID} on ${env.JENKINS_URL}"
                // method B
                echo "Running $env.BUILD_ID on $env.JENKINS_URL"
                // method C
                echo "Running ${BUILD_ID} on ${JENKINS_URL}"
            }
        }
    }
}

默认情况下,env中的所有环境变量都可以直接在pipeline中使用。因此上面三种方法都可以使用,但不推荐第三种方法,因为在出现变量名冲突时,排查问题非常难。

    如果需要查看env所有可用的环境变量,可以通过以下方式进行访问。http://jenkins-master-address/pipeline-syntax/globals。示例如下所示:

http://192.168.188.133:9090/pipeline-syntax/globals

    Jenkins 内置环境变量如下所示:

0301 Jenkins内置环境变量.png

    以下为日常经常使用到的内置环境变量简介。如下所示:

  • BRANCH_NAME

    多分支piple 项目支持。可根据不同的分支执行不同的语句。例如当分支为release时,部署到生产环境,分支为test时,部署至测试环境。

  • BUILD_NUMBER

    构建号,同一个项目中,持续累加的数字。

  • BUILD_URL

    当前构建的URL地址,点击该URL,可以快速跳转至构建页面

  • WORKSPACE

    构建的工作空间,为绝对路径

    在调试pipeline时,也可以在pipeline 的开始阶段使用以下代码片断,打印所有env的环境变量,来进行排查问题。如下所示:

sh "printenv"

3.2.1.2 自定义环境变量

    当内置环境变量无法满足要求时,我们也可以定义自己的环境变量。这个时候就需要使用environment命令来自定义环境变量。示例如下所示:

pipeline {
    agent any
    environment{
        NAME="Surpass"
        AGE="28"
    }
    stages{
        stage("PrintGolbalEnviroment"){
            steps{
               echo "Global Enviroment is name is ${env.NAME} age is ${env.AGE}"
            }
        }
        stage("PrintLocalEnviroment"){
            environment{
                CITY="Shanghai"
                FROM="Wuhan"
            }
            steps{
                echo "Global Enviroment is name is ${env.NAME} age is ${env.AGE}"
                echo "Local Enviroment is city is ${env.CITY} from is  ${env.FROM}"
            }
        }
    }
}

    environment 可以在pipeline中定义,属于全局环境变量,代表整个pipeline均可以使用该环境变量。也可以在stage中定义,属于局部环境变量,仅限于该阶段内部有效,外部无法使用。

    除了以上几中自定义环境变量,还可以通过script来定义全局变量,示例如下所示:

pipeline {
    agent any
    environment{
        NAME="Surpass"
        AGE="28"
    }
    stages{
        stage("Set environment by script"){
            steps{
              script{
                  env.SURPASS_NAME="Surpass"
                  env.SURPASS_AGE=28
                }
            }
        }

        stage("PrintGolbalEnvironment"){
            steps{
               echo "Global Enviroment is name is ${env.NAME} age is ${env.AGE}"
            }
        }
        stage("PrintLocalEnvironment"){
            environment{
                CITY="Shanghai"
                FROM="Wuhan"
            }
            steps{
                echo "Global Enviroment is name is ${env.NAME} age is ${env.AGE}"
                echo "Local Enviroment is city is ${env.CITY} from is  ${env.FROM}"
            }
        }
        stage("PrintSetEnvironment"){
            steps{
                echo "print global env by script ${env.SURPASS_NAME}"
                echo "print global env by script ${env.SURPASS_AGE}"
            }
        }
    }
}

    在自定义环境变量,需要注意的地方如下所示:

  • 1.环境变量是不能跨pipeline进行访问的,即不同的pipeline间不能共享环境变量
  • 2.如果用户自定义的环境变量与env环境变量重名,则被重命名的环境将被覆盖

3.2.1.3 自定义全局环境变量

    env中的环境变量都是内置的,用户自定义的环境变量是与具体的pipeline相关的。如果需要定义全局并且跨pipeline自定义环境变量,可以这样设置。

Manage Jenkins->Configure System-> Global properties,勾选 Environment variables,添加对应的环境变量即可。

0302 自定义全局环境变量.png

    以上自定义的全局环境变量,会被加入env环境变量列表中,后续使用时可以使用${env.SURPASS_NAME}${env.SURPASS_AGE}来获取。

3.2.2 tools

    可定义在pipeline或stage部分。在运行时,会自动下载并安装指定的工具和加入PATH变量中。但在agent none时,会失效

基于在线自动安装,受限于网络不可达、网络速度、网络策略等因素,一般还是建议,还是提前下载到本地,然后在Jenkins进行配置好之后,在pipeline中直接使用即可。

3.2.2.1 Go 语言环境搭建

    其操作步骤如下所示:

  • 1.下载golang SDK本地

  • 2.在Jenkins 中安装go插件

  • 3.在Jenkins中进行配置

Manage Jenkins->Configure System-> Global Tool Configuration->GO

0303 添加go tools.png
  • 4.编写pipeline 脚本
pipeline{
    agent any
    tools {
        go "go-1.19"
    }
    stages{
        stage("tools demo"){
            steps{
                sh "go version"
                sh "go env"
            }
        }
    }
}

    运行结果如下所示:

0304 tools 运行结果.png

3.2.2.2 Python 语言环境搭建

    Python 环境很容易产生版本冲突和第三方库冲突等问题,因此Python通过会进行工程级别的环境隔离。在Jenkins中,我们可以使用插件Pyenv Pipeline Plugin(https://plugins.jenkins.io/pyenv-pipeline/)来解决此类问题。其操作步骤如下所示:

  • 1.在Jenkins中安装Python/pip/virtualenv
  • 2.安装插件Pyenv Pipeline Plugin
  • 3.编写pipeline 脚本
pipeline{
    agent any
    stages{
        stage("python virtual env demo"){
            steps{
                withPythonEnv("/usr/local/bin/python3") {
                    // Uses the specific python3.5 executable located in /usr/bin
                    sh "python3 --version"
                    sh "python3 -c \"print('hello,Surpass')\""
                }
            }
        }
    }
}

    运行结果如下所示:

0305 pyenv demo.png

3.2.2.3 利用作用域实现多版本编译

    在实际项目中,同一份源码可能会存在多个版本的编译构建等。tools 除了支持pipeline域也支持stage域。示例如下所示:

pipeline{
    agent any
    stages{
        stage("build with go 1.19"){
            tools {
                go "go-1.15"
            }
            steps{
                echo "use go 1.15 build"
            }
        }
        stage("build with go 1.19"){
            tools {
                go "go-1.19"
            }
            steps{
                echo "use go 1.19 build"
            }
        }
    }
}

3.2.3 input

    input 命令可以实现pipeline中的交互操作。利用input命令,我们可以一些简单的场景。

  • 实现简易的审核流程

在部署环境前,由相应负责人员进行确认

  • 排查定位问题

因为pipeline在遇到input命令时,会暂停执行。因此,我们可以利用这个特性,使运行某个阶段前,暂停执行pipeline

3.2.3.1 常用参数

    input 命令的常用参数如下所示:

  • message

    该参数为必选参数,input命令的消息提示框消息。

  • id

    该参数为可选参数, input命令标识符,默认为stage的名称

  • submitter

    该参数为可选参数,类型为字符串类型,可以进行操作的用户ID或用户组名称,使用,分隔,在,左右不允许有空格。可以用来做权限控制。

  • submitterParameter

    该参数为可选参数,类型为字符串类型,保存input命令的实际操作者的用户名的变量名

  • ok

    该参数为可选参数,自定义确定按钮的文本

  • parameters

    该参数为可选参数,提供参数列表供input命令使用。

3.2.3.2 简易用法

    比如我们现在实现第一种简易的审核流程。示例脚本如下所示:

pipeline{
    agent any
    stages{
        stage("input simple use"){
            steps{
                input message:"Confirm or Cancle ?"
            }
        }
    }
}

    当执行到input simple use阶段时,pipeline会暂停,当鼠标移动到该阶段虚线视图上时,会出现一个浮层 ,以供选择。示意图如下所示:

0306 input简易用法.gif

3.2.3.3 复杂用法

    示例脚本如下所示:

pipeline{
    agent any
    environment {
        DEPLOY_ENV=""
    }
    stages{
        stage("choose deploy nodes"){
            steps{
                script{
                  DEPLOY_ENV=input(
                      message: "准备部署到哪个节点?",
                      parameters:[choice(
                            name:'chooseNode',
                            choices:["node-1","node-2","node-3"],
                            description:"选择部署节点") 
                            ],
                      ok:"确定",
                      submitter:"admin,Surpass",
                      submitterParameter:"approvers"
                      )
                }
            }
        }
        stage("deply"){
            steps{
                echo "操作人员:${DEPLOY_ENV['approvers']}"
                echo "部署节点:${DEPLOY_ENV['chooseNode']}"
            }
        }
    }
}

因为input返回的值需要跨阶段,因此需要将input的返回值定义为全局变量。

    input 命令返回值类型取决于返回的值个数,详情如下所示:

  • 仅返回一个值,返回值类型就是这个值的类型
  • 返回多个值,则返回值类型为Map类型

    运行结果如下所示:

0307 inpu复杂用法.gif

3.2.4 options

    用于配置pipeline本身的选项,可以定义在pipelinestage中。常用的配置项如下所示:

  • buildDiscarder

    用于配置保存最近历史构建记录的数量。示例如下所示:

options{
      buildDiscarder(logRotator(numToKeepStr:'5'))
    }

此选项只能在pipeline下的 options 中使用

  • checkoutToSubdirectory

    Jenkins 从版本控制库中拉取源码时,默认会存放到工作空间目录中,此选项可以指定检出到工作空间的子目录中,示例如下所示:

   options{
      checkoutToSubdirectory('subdir')
    }
  • disableConcurrentBuilds

    同一个pipeline,Jenkins默认是可以同时执行的,而此选项则是禁止多个pipeline并行执行,示例如下所示:

   options {
      disableConcurrentBuilds()
    }
  • retry

    当发生失败时进行重试,可以指定整个pipeline的重试次数。示例如下所示:

   options{
       retry(3)
   }

需要注意的是这里的重试次数是指总次数,即包含第一次失败。当使用retry选项时,options可以放在stage中

  • timeout

    若pipeline执行时间过长,超出了设置的超时时间之后,则Jenkins将中止pipeline。示例如下所示:

   options{
       timeout(time:1,unit:'SECONDS')
   }

1.timeout时间单位有SECONDSMINUTESHOURS
2.当使用timeout选项时,options可以放在stage块中

  • timestamps

    为控制台输出时间戳。示例如下所示:

   options {
        timestamps()
    }

3.2.5 parallel

    在pipeline中使用parallel可以很方便的实现并行构建。

3.2.5.1 阶段并行

    示例如下所示:

pipeline{
    agent any
    stages{
        stage("Non Parallel stage"){
            steps{
                echo "This is non-parallel stage"
            }
        }
        stage("Parallel stage"){
            failFast true
            parallel{
                stage("Parallel A"){
                    steps{
                        echo "Parallel A"
                    }
                }
                stage("Parallel B"){
                    steps{
                        echo "Parallel B"
                    }
                }
                stage("Parallel C"){
                    steps{
                        echo "Parallel C"
                    }
                }
            }
        }
    }
}

    在使用parallel时,注意事项如下所示:

  • parallel 块本身不允许包含agenttools
  • 默认情况下,pipeline要等parallel块下所有的阶段都运行完成,才能确定运行结果。若希望所有并行阶段中某个阶段失败后,就即将中止所有阶段,则需要在parallel同级位置加入failFast true

failFast true 简单来讲就是表示,只要有一个并行阶段运行失败,则立即退出。

3.2.5.2 步骤并行

    示例如下所示:

pipeline{
    agent any
    stages{
        stage("Non-parallel steps"){
            steps{
                echo "Non-parallel steps"
            }
        }
        stage("Parallel steps"){
            steps{
                parallel(
                  parallelA:{
                      echo "parallelA steps"
                  },
                  parallelB:{
                      echo "parallelB steps"
                  },
                  parallelC:{
                      echo "parallelC steps"
                  }
                )
            }
        }
    }
}

    阶段并行和步骤并行的主要区别如下所示:

  • 写法区别:在阶段并行时,使用的是大括号,而步骤并行时,使用的是括号
  • 运行区别:阶段并行是运行在不同的executor,而步骤并行,则是运行在同一个executorr

你可能感兴趣的:(Jenkins实践指南-05-Jenkins pipeline 语法01)