Jenkins实践指南-10-Jenkins 插件

2023-01-06 本文已影响0人 Surpassme

6. Jenkin 插件

Jenkins之所以这么流行，不仅在于本身功能非常齐全，也在于本身插件非常丰富，以下主要介绍平时经常使用的到插件。

6.1 插件安装

依次点击Manage Jenkins -> Manage Plugins -> Available，搜索插件并安装即可，示意图如下所示：

0601 安装插件.png

6.2 常用插件

6.2.1 Git Parameter

该插件允许在构建时，选择指定的git分支、标签等，官网地址：https://plugins.jenkins.io/git-parameter/。pipeline 示例录下所示：

pipeline {
  agent any
  environment{
     CODE_SUB_DIR_PATH="surpass"
     CODE_GitURL="https://gitlab.surpass.com/surpass/demo.git"
  }
  parameters {
     gitParameter(
        name:"CODE_TAG_BRANCH_NAME",
        type:"PT_BRANCH_TAG",
        branchFilter: "origin/(.*)",
        defaultValue: "test",
        selectedValue:"DEFAULT",
        sortMode:"DESCENDING_SMART",
        useRepository:"${env.CODE_GitURL}",
        description: "请选择branch或tag"
        )
  }
  stages {
    stage("拉取代码"){
           steps{
            checkout([
                    $class:"GitSCM",
                    branches:[[name:"${params.CODE_TAG_BRANCH_NAME}"]],
                    doGenerateSubmoduleConfigurations: false,
                    extensions: [[
                       $class:"RelativeTargetDirectory",
                       relativeTargetDir:"${env.CODE_SUB_DIR_PATH}"
                       ]],
                    gitTool: "Default",
                    submoduleCfg: [],
                    userRemoteConfigs:[[
                       credentialsId:"32eddb12-cd66-444b-859d-ccb61c3864d1",
                       url:"${env.CODE_GitURL}"
                       ]]
                   ]
               )
           }
        }
    }
}

其主要参数解释如下所示：

type:主要支持PT_TAG、PT_BRANCH、PT_BRANCH_TAG、PT_REVISION、PT_PULL_REQUEST
sortMode：主要支持NONE、ASCENDING_SMART、DESCENDING_SMART、ASCENDING、DESCENDING
useRepository：默认使用的gitlab仓库地址

6.2.2 build user vars

通过设置环境变量来获取启动任务的用户名，官网地址：https://plugins.jenkins.io/build-user-vars-plugin/，一般常用于多用户下的Jenkins环境。主要支持的环境变量如下所示：

变量名称	描述信息
BUILD_USER	Full name (first name + last name)
BUILD_USER_FIRST_NAME	First name
BUILD_USER_LAST_NAME	Last name
BUILD_USER_ID	Jenkins user ID
BUILD_USER_GROUPS	Jenkins user groups
BUILD_USER_EMAIL	Email address

示例用法如下所示：

pipeline{
    agent any
    stages{
        stage("get build user demo"){
            steps{
                script{
                    wrap([$class: 'BuildUser']) {
                      env.BUILD_USER = "${BUILD_USER_ID}"
                   }
                }
            }
        }
        stage("print build  user"){
            steps{
                echo "build user is ${env.BUILD_USER}"
            }
        }
    }
}

6.2.3 Pipeline Utility Steps

该插件功能非常多，可以用来比较版本大小、查找文件、读取CSV、JSON、YAML等，其官网地址：https://plugins.jenkins.io/pipeline-utility-steps/，我们以读写YAML为示例，如下所示：

def readYamlFile(filePath,imageName){
    if (fileExists(filePath)){
       println("Yaml file path is ${filePath}")
       def data=readYaml(file:filePath)
       println("YAML文件内容：\n${data}")
       def testText=data.spec.template.spec.containers[0][0].image
       data.spec.template.spec.containers[0][0].image=imageName
       println("修改前的镜像地址:${testText}\n修改后的镜像地址:${imageName}")
       return data
    }
    else{
       println("${filePath} not exists,please check !!!")
    }
}

def writeYamlFile(filePath,content,overwrite=true,charset="UTF-8"){
    if (fileExists(filePath)){
        writeYaml(file:filePath,datas:content,overwrite:overwrite,charset:charset)
    }
    else{
       println("${filePath} not exists,please check !!!")
    }
}

6.2.4 HTTP Request

主要用于发送HTTP请求，比如向企业微信机器人发送消息等，官网地址：https://plugins.jenkins.io/http_request/，HTTP Request支持的参数如下所示：

url：字符串类型，请示URL地址
acceptType:枚举类型，HTTP请求Header的Accept的值类型，可以支持的参数如下所示：

- NOT_SET
- TEXT_HTML
- TEXT_PLAIN
- APPLICATION_FORM
- APPLICATION_JSON
- APPLICATION_JSON_UTF8 // 若含中文，需要使用这种方式
- APPLICATION_TAR
- APPLICATION_ZIP
- APPLICATION_OCTETSTREAM

authentication:字符串类型，使用的是HTTP Basic谁，即用户名+密码这种形式
consoleLogResponseBody:布尔类型，是否将请求的响应body打印出来
contentType:枚举类型，HTTP请求的Content-Type值类型，同acceptType
customHeaders:HttpRequestNameValuePair对象数组，HTTP请求Header部分内容，该对象有3个参数。

name:字符串类型，Header名称
value:字符串类型，Header值
maskValue:布尔类型，是否隐藏Header值。若为true,则打印时使用*代替

httpMode:枚举类型，HTTP方法，有GET(默认)、HEAD、POST、PUT、DELETE、OPTIONS、PATCH等
httpProxy:字符串类型，HTTP代理地址
ignoreSslErrors:布尔类型，是否忽略SSL错误
requestBody:字符串类型，请求的body内容
timeout:整理，超时时间，单位为秒。默认为0，代表不设置超时时间
vaildResponseCodes:字符串类型，代表HTTP请求成功的状态码。其支持3种格式的值

- 单状态值：如200，当收到200状态码，表示HTTP请求成功
- 多状态值：当响应状态码符合多个状态码中的一个时，则代表请求成功，多个状态码之间使用逗号分隔。如200,300
- 范围状态值：格式为"From:To"，如200:302，代表收到200~302的响应状态码都算请求成功

validResponseContent:字符串类型，假设设置其值为：supass.name，则只有当HTTP返回的内容中包含了supass.name时，才算请求成功。
quiet:布尔类型，是否关闭所有的日志打印，默认为false
responseHandle:枚举类型，获取HTTP响应内容的方式，其值可以为：

- NONE：不读取响应内容
- LEAVE_OPEN:当执行完请求后，并不会返回响应内容，而是返回一个打开的inputStream，由你自己决定如何读取响应内容，在使用完之后，需要调用inputStream的close方法关闭
- STRING：默认值，将响应内容转换为一个字符串

outputFile:字符串类型，请求响应内容的输出路径alue:布尔类型，是否隐藏Header值。若为true,则打印时使用*代替

示例代码如下所示：

def httpRequestSendMessage(address,method,body){
    def response=httpRequest(url:address,
                           acceptType:"APPLICATION_JSON_UTF8",
                           contentType:"APPLICATION_JSON_UTF8",
                           httpMode:method,
                           requestBody:body,
                           ignoreSslErrors:true,
                           validResponseCodes:"200"
                          )
    println("response.status is:${response.status}\nresponse.content:${response.content}")

6.2.5 Allure

allure是一个轻量级别的多语言测试报告插件，常用于在自动化测试中以WEB形式展示测试报告，官网地址：https://plugins.jenkins.io/allure-jenkins-plugin/，其示例用法如下所示：

post{
  always{
    script{
       allure([
         includeProperties : false,
         jdk:"",
         properties: [],
         reportBuildPolicy: "ALWAYS",
         report: "${env.ALLURE_REPORT_PATH}",
         results: [[ path: "${env.ALLURE_RESULT_PATH}" ]]
       ])
    }
  }
}

使用注意事项如下所示：

report：生成allure最终报告的存储路径，其中默认生成的路径为相对于$WORKSPACE的路径
results：生成allure的中间数据，即生成的原始报告数据，支持多个路径中间数据，其中默认生成的路径为相对于$WORKSPACE的路径

6.2.6 Active Choices

Active Choices 插件常用于创建动态交互式参数化插件。其官网地址：https://plugins.jenkins.io/uno-choice/，其主要支持的参数类型有：

Active Choices Parameter
Active Choices Reactive Parameter
Active Choices Reactive Reference Parameter

Active Choices parameters 允许用户为任务参数选择值，参数值如下所示：

dynamically generated：动态生成(使用Groovy)
dynamically updated based on other UI parameters：基于其他UI参数进行更新
multi-valued：多个值
rendered with a variety of UI controls, including dynamic HTML：使用多种UI控件渲染，包含动态HTML

6.2.6.1 Active Choices Parameter

1.Behavior

Active Choices parameter 使用Groovy脚本动态生成参数列表

2.Rendering

Active Choices parameters 可以生成标准列表选择、复选框和单选框
可以生成文本框筛选器来筛选选项

0605 Active Choices Parameter 生成参数类型示意图.jpg

图片来自于：https://github.com/jenkinsci/active-choices-plugin/blob/master/docs/images/001.jpg

6.2.6.2 Active Choices Reactive and Reactive Reference Parameters

1.Behavior

与Active Choices Parameter类似，可以使用Groovy脚本为构建任务动态生成参数选项，当UI控件值发生变更时，也可以动态级联更新。

2.Rendering Options

Active Choices Reactive：可以生成标准列表选择、复选框、单选框和文本框筛选器来筛选选项
Active Choices Reactive Reference：可以生成HTML列表、HTML输入框、动态生成HTML等

0606 Active Choices Reactive and Reactive Reference Parameters 生成参数类型示意图.jpg

图片来自于：https://cdn.jsdelivr.net/gh/jenkinsci/active-choices-plugin@master/docs/images/002.gif

6.2.6.3 Behavior and Rendering Summary

以下为三种Active Choices parameter的行为和呈现特征对比

0607 Behavior and Rendering Summary summary.jpg

图片来自于：https://cdn.jsdelivr.net/gh/jenkinsci/active-choices-plugin@master/docs/images/003.jpg

6.2.6.4 Active Choices Parameter 示例

6.2.6.4.1 Active Choices Parameter 示例

以下为在自由风格中的配置，示例如下所示：

0608 Active Choices Parameter 示例演示.png

主要参数解释如下所示：

Name 和 Describe

与常规Jenkins 参数一致，用于一个参数的名称和描述信息

Script

动态生成参数所使用的脚本代码，脚本返回必须为java.util.List、java、java.util.Map

Fallback Script

主要提供备用选项，在脚本出错时，使用该值

Choice Type

主要提供四种不同的类型选择单选框、复选框、列表单选、列表多选

Enable Filte

是否启用筛选搜索

6.2.6.4.2 Active Choices Parameter Rendering示例

示例-1

0609 Active Choices Parameter Rendering-01.png

示例-2

0610 Active Choices Parameter Rendering-02.png

6.2.6.5 pipeline 示例

通过自由风格来配置Active Choice非常方便，但迁移起来也非常麻烦的，pipeline示例如下所示：

properties([
  parameters([
    [
      $class: "ChoiceParameter",
      choiceType: "PT_SINGLE_SELECT",
      description:"请选择一个省份",
      filterable: true,
      filterLength: 1,
      name: "Province",
      script: [
         $class: "GroovyScript",
         script:[
            classpath: [],
            sandbox: true,
            script: "return ['江苏','浙江','安徽']"
            ],
         fallbackScript:[
           classpath: [],
           sandbox: true,
           script: "return['错误']"
         ]
      ]
    ],
    [
      $class: "CascadeChoiceParameter",
      choiceType: "PT_CHECKBOX",
      name: "City",
      referencedParameters: "Province",
      script: [
         $class: "GroovyScript",
         script:[
            classpath: [],
            sandbox: true,
            script: '''
                if(Province.equals("江苏")){
                   return ["南京:selected","苏州","无锡","常州"]
                } else if(Province.equals("浙江")){
                   return ["杭州:selected","绍兴","宁波","温州"]
                } else if(Province.equals("安徽")){
                   return ["合肥:selected","芜湖","六安","马鞍山"]
                } else {
                   return ["未知城市"]
                }
            '''
            ],
         fallbackScript:[
           classpath: [],
           sandbox: true,
           script: "return['脚本错误']"
         ]
      ]
   ]
 ])
])

pipeline{
    agent any
    options{
        timestamps()
    }

    stages{
        stage("active choice demo"){
            steps{
                echo "Province is:${params.Province}"
                echo "City is:${params.City}"
            }
        }
    }
}

运行结果如下所示：

0611 activeChoice pipeline 示例.png

注意事项：sandbox需要配置为true，因Jenkins安全策略限制，若为false，可能配置选项无法显示

常见的Choice Type 如下所示：

PT_SINGLE_SELECT：下拉单选
PT_MULTI_SELECT：列表多选
PT_CHECKBOX：筛选框
PT_RADIO：单选框

源码定义如下所示：

/*
* Constants.
*/
// default choice type
public static final String PARAMETER_TYPE_SINGLE_SELECT = "PT_SINGLE_SELECT";
public static final String PARAMETER_TYPE_MULTI_SELECT = "PT_MULTI_SELECT";
public static final String PARAMETER_TYPE_CHECK_BOX = "PT_CHECKBOX";
public static final String PARAMETER_TYPE_RADIO = "PT_RADIO";

// default choice type
public static final String ELEMENT_TYPE_TEXT_BOX = "ET_TEXT_BOX"; 
public static final String ELEMENT_TYPE_ORDERED_LIST = "ET_ORDERED_LIST";
public static final String ELEMENT_TYPE_UNORDERED_LIST = "ET_UNORDERED_LIST";
public static final String ELEMENT_TYPE_FORMATTED_HTML = "ET_FORMATTED_HTML";
public static final String ELEMENT_TYPE_FORMATTED_HIDDEN_HTML = "ET_FORMATTED_HIDDEN_HTML";

源码链接：https://github.com/jenkinsci/active-choices-plugin/blob/master/src/main/java/org/biouno/unochoice/AbstractUnoChoiceParameter.java

6.2.7 邮件通知

邮件也是日常Jenkins常用的通知方式，Jenkins默认支持

6.2.7.1 使用Jenkins内置邮件通知功能

以QQ邮箱演示，操作步骤如下所示：

在配置邮箱时，需要确认所使用的邮箱已经打开SMTP服务

1. 设置管理员邮箱，如下所示：

0612 设置Jenkins管理员邮箱.png

2、配置SMTP服务器信息

0613 测试邮箱配置.png

3、在pipeline中Post部分加入发送邮件配置

pipeline{
    agent any
    options{
        timestamps()
    }

    stages{
        stage("Test e-mail Demo"){
            steps{
                echo "Test e-mail demo"
            }
        }
    }

    post{
        success{
            mail(
                from: "surpassme@qq.com",
                to:   "surpassme@qq.com",
                body: "This is test Jenkins send e-mail,please don't reply",
                subject: "Test e-mail demo"
                )
        }
    }
}

主要参数解释如下所示：

from: 发件人地址
to:收件人地址
body:邮件正文
subject:邮件主题

6.2.7.2 使用E-mail Extension 插件通知

如果觉得Jenkins内置的邮件功能不能满足要求，也可以试试插件E-mail Extension，其官网为：https://plugins.jenkins.io/email-ext/，其主要特色功能：

可以定制收件人列表
可以将日志以附件形式进行发送
可以发送附件

E-mail Extension使用步骤如下所示：

1、配置SMTP服务器信息，如下所示：

0614 配置E-mail Extension SMTP 信息.png

2、在pipeline中Post部分加入发送邮件配置

pipeline{
    agent any
    options{
        timestamps()
    }

    stages{
        stage("Test e-mail Demo"){
            steps{
                echo "Test e-mail demo"
            }
        }
    }

    post{
        success{
            emailext (
                to:   "surpassme@qq.com",
                subject: "Test e-mail demo",
                body: """
                       JobName:${env.JOB_NAME}
                       BuildNumber:${env.BUILD_NUMBER}
                       BuildURL:${env.BUILD_URL}
                       View console log url:${env.BUILD_URL}console
                      """,
                compressLog: true,
                attachLog: true,
                recipientProviders: [developers(), requestor()],
                )
        }
    }
}

运行结果如下所示：

0615 运行结果.png

emailext的主要参数解释如下所示：

from:可选，为string类型，发件人地址
to:可选，为string类型，收件人地址
subject:为string类型，邮件主题
body:为string类型，邮件正文
compressLog：为boolean类型，是否压缩日志
attachLog：可选，为boolean类型，是否将构建日志以附件形式发送
attachmentsPattern:可选，为string类型，需要发送的附件的路径，支持ANT风格路径表达式
recipientProviders：可选，List类型，收件人列表类型

常用的收件人列表类型如下所示

类型名称	功能解释
developers	此次构建所涉及变更的所有提交者列表
requestor	启动构建任务的人
culprits	引发构建失败的，即最后一次构建成功和最后一次构建失败之间的变更提交者列表

6.2.8 Periodic Backup

Jenkins本身并不提供备份功能，而是使用插件来进行备份。这里推荐使用插件Periodic Backup(https://plugins.jenkins.io/periodicbackup/)来实现备份。操作步骤如下所示：

1.Manage Jenkins -> Periodic Backup Manager 如下所示：

0602 Periodic Backup 备份插件.png

2.点击Periodic Backup Manager，进行配置

0603 Periodic Backup 备份配置.png

主要参数如下所示：

Backup schedule (cron)

备份的cron表达式，在配置后，可以点击Validate cron syntax进行校验

File Management Strategy

设备备份策略，ConfigOnly仅备份配置文件，FullBackup 全量备份，也可以在Excludes list 使用Ant风格路径表达式，排除不希望进行备份的文件

Storage Strategy

备份文件的保存格式。

Backup Location

备份文件存放位置。需要对文件夹具有相应的读写权限

3.备份成功后，在Restore页面，可以看到最近的备份结果

0604 查看备份结果.png

4.若需要还原，选中对应的备份文件，点击Restore selected backup即可。