wydevops——与Jenkins集成

        前文已对wydevops本地工作模式下的各种功能进行了介绍，本文主要介绍wydevops的jenkins工作模式相关知识。

1. 流水线阶段划分

        为了避免出现脚本碎片化并对所有脚本进行版本管理，在设计之初就希望将CICD整个流程中的相关阶段的脚本统一融合为一个完整的项目，可通过传入参数控制其执行CICD某个阶段的流程。最终wydevops将其CICD流水线分解为5个阶段：编译(build)、Docker镜像生成（docker）、Chart镜像生成（chart）、离线安装包生成（package）、服务部署（deploy）共5个阶段。

2. 全局参数串行化与反串行化

       各流水线阶段都需要执行命令行参数解析和全局参数初始化过程。在全局参数初始化过程中会涉及到参数映射和yaml文件合并等比较耗时的操作。为了不重复执行这些耗时操作，wydevops在build阶段会将参数映射和yaml文件合并后初始化的全局参数保存到一个本地文件中(_global_params.yaml)，后续执行的流水线阶段在检测到该文件存在，则跳过参数映射和yaml文件合并操作，直接从该文件中读取全局参数及其初始化值。为了便于将全局参数串化到文件，wydevops将所有的全局参数都以字符串的形式定义在一个数组（gGlobalParamNames）中，如下图：

数组中的全局变量使用eval语句完成真正的全局变量声明，如下图：

      这样通过gGlobalParamNames数组，wydevops就能很容易的完成参数到文件的串行化(cacheGlobalParamsToFile)和反串行化(loadGlobalParamsFromCacheFile)操作。

3. 准备wydevops项目

3.1 下载wydevops源码

        从开源项目地址下载wydevops源码:

wydevops: 支持多语言项目的、可自主扩展的、工程化的DevOps工具https://gitee.com/tmt_china/wydevops      将下载的源码提交到使用的私库中，后续将使用私库中的wydevops项目。

3.2 初始化wydevops源码中的配置

3.2.1 配置部署环境参数

        定义不用语言使用的全参数配置模板文件(script/templates/config/{语言类型}/_ci-cd-template.yaml)中的部署环境相关的参数。   

• 如果采用K8S集群部署服务则deploy[0].k8s.dev配置节的apiServer和namespace参数是必须配置的。如果集群使用的docker仓库与wydevops的docker阶段配置的docker仓库不是同一个，则还需要配置dockerRepo参数。
• 如果采用docker方式部署服务则deploy[0].docker.dev配置节下的nodeIPs参数必须配置。
• 如果存在多套部署环境，则可以复制粘贴deploy[0].k8s.dev整个配置节，并将dev更新为该套部署环境的名称（例如：test)；同理deploy[0].docker.dev配置节也可以复制粘贴创建新的部署环境。如下图：

        该图中新定义了一个test测试集群的配置信息，其中红框部分需要预先配置好。使用dev环境还是test环境是由下图红框中的activeProfile参数指定的，${activeProfile}默认值为dev。

        根据需要也可以在deploy[0].docker配置节下参照上面的描述定义新的集群信息。·

3.2.2 配置参数映射

        在wydevops源码的script/templates/config/{语言类型}/param-mapping目录下定义好参数映射文件，这部分的配置可参考java目录下的*.conf文件的内容。目前wydevops项目仅支持为yaml文件和xml文件配置参数映射，尚未提供为ini文件配置参数映射的功能，如下图：

4. Jenkins安装与配置

4.1 docker方式部署Jenkins服务

        在Windows10中，采用docker-compose.yaml文件来部署Jenkins。docker-compose.yaml文件内容如下：        

version: "3.8"

services:
  jenkins:
    image: jenkins/jenkins:lts-jdk17
    ports:
      - "8080:8080"
      - "50000:50000"
    volumes:
      - local_home:/var/jenkins_home
 
volumes: 
  local_home: 
    driver: local  
    driver_opts:
      o: bind
      type: none             
      device: E:\docker\jenkins\home

上图最后一行中的目录，可自行修改为本地合适的路径。

执行:

docker-compose up -d

运行完毕后，在浏览器中访问：http://localhost:8080，即可打开jenkins初始化界面，如下：

按UI上的提示，找到并填入初始密码。点击"继续"按钮后显示插件初始化界面:

选择“安装推荐的插件”，显示如下界面：

等待直至插件安装完毕（不需要所有插件都安装成功），点击“继续”，则显示登录账号配置界面

配置好登录账号后继续，则显示如下图内容：

因为使用的是docker方式部署的，所以此处不能使用localhost，要更改为实际的IP地址(后续还可以在“系统配置”中修改)。最后点击“保存并完成”按钮, 随后显示如下界面：

在上图界面中，点击“开始使用Jenkins”按钮。显示如下主界面：

4.2 安装Jenkins插件

4.2.1 Generic Webhook Trigger

点击上图左边的Manage Jenkins项，在右边新显示的界面上（如下图）点击“Plugins”此时，Jenkins会打开插件管理功能页面，如下图。选中左边的Available plugins项，接着再右边查询输入框中输入“Generic Webhook Trigger”，此时会如下图所示显示找到的目标插件项。然后再勾选该插件并点击安装按钮。

此时界面更新为下图。

下载完毕后，勾选最下面的勾选框（如上图红框处）Jenkins将重启。此处我们采用的docker方式安装的Jenkins，需要我们在docker desktop中手动重启Jenkins服务（此时jenkins已经退出了）

 安装Pipeline 2.6

4.2.2 Pipeline

Pipeline插件已经在Jenkins安装过程中的“安装推荐插件”时完成了安装。

4.3 配置全局变量

        这里需要配置wydevops在Jenkins工作模式下运行的环境参数。如下图，进入系统管理->系统配置。

4.3.1 Jenkins Location配置

        在打开的系统配置界面中, 找到并确认Jenkins URL参数中使用的是IP地址而不是localhost。由于后续我们会使用docker搭建Jenkins的构建节点，这里的URL参数就不能使用localhost；不然会导致docker方式的构建节点无法正确连接到Jenkins服务。

4.3.2 新增环境变量  

4.3.2.1 构建脚本根目录（BUILD_SCRIPT_ROOT）

在全局属性中新增环境变量BUILD_SCRIPT_ROOT，变量的值可自行定义，如下图：

(注：图中环境变量的键中下划线没有正确显示出来)

4.3.2.2 Docker镜像仓库信息（DOCKER_REPO_INFO）

         在全局属性中新增环境变量DOCKER_REPO_INFO，变量值的格式与wydevops在本地工作模式下命令行参数-D的格式保持一致。如下图。具体值请与你的本地配置保持一致。

(注：图中环境变量的键中下划线没有正确显示出来)

4.3.2.3 Chart镜像仓库信息（CHART_REPO_INFO）

在全局属性中新增环境变量CHART_REPO_INFO，变量值的格式与wydevops在本地工作模式下命令行参数-C的格式保持一致。如下图。具体值请与你的本地配置保持一致。

(注：图中环境变量的键中下划线没有正确显示出来)

4.4 配置凭据

       这里的凭据是指：当Jenkins的Job到Git源码仓库拉取源码时向Git服务器提供的账号和密码。

配置步骤如下：

        进入系统管理->凭据管理，如下图。点击“全局”链接旁边的下拉箭头（鼠标移到“全局”上才会出现），在点击显示的“添加凭据”菜单。

        此时，Jenkins显示新增凭据的界面，如下图：

类型——选中"Username and password"

范围——保持不变：全局有效

用户名——Git源码仓库登录时使用的账号

密码——Git源码仓库登录账号的密码

ID——为这个凭据定义的唯一名称，后续可在pipeline流水线脚本中引用这个ID来指明下载源码时使用哪个具体凭据。

描述——说明这个凭据的作用

填写完毕后，点击“Create”即可完成凭据的创建，如下图：

4.5 配置代理节点

        如下图，进入“系统管理”->"节点和云管理",

在新打开的节点列表界面（如下图）上点击“New Node”按钮，打开新增节点界面。

如下图，设置好新节点的名称并选中"固定节点"选项，点击“Create”按钮。

此时会显示节点详细配置界面，如下图：

其中，远程工作目录必须设置，这里设置为/data目录。继续向下滚动，设置好标签（这里设置值为maven2，后续会用到），并将启动方式设置为下图中的值。

点击上图中"保存"按钮，则Jenkins回到节点列表界面，如下图：

注意：master节点是Jenkins专用的，不能用来执行构建任务。

此时还有最后一步：获取代理节点连接Jenkins的脚本。点击上图列表中的”maven2“链接，Jenkins会显示如下界面，这界面中给出了各个操作系统下代理节点连接Jenkins的脚本, 这个脚本在4.6节会使用到。

4.6 构建代理节点Docker镜像

        我们推荐使用构建一个Docker镜像来模拟一个Jenkins从节点，这样可以在单台服务器上同时部署多种语言的构建节点。下面以Java语言为例，讲述构建从节点镜像的过程。

4.6.1 定义从节点镜像的Dockerfile

        Java项目有两种主流的构建工具: maven和gradle。gradle是比maven更新一代的构建工具，但maven项目更普遍存在，这里定义的Dockerfile针对的是maven项目（使用maven作为构建工具的Java项目）。Dockerfile内容如下：

FROM maven:latest

ENV JENKINS_IP=127.0.0.1
ENV JENKINS_PORT=8080
ENV NODE_NAME=maven
ENV NODE_WORK_DIR=/data
ENV SECRET_CODE=123
#get docker's group id by using 'getent group docker' command in ubuntu on windows 
ENV DOCKER_GROUP_ID=1001

USER root

RUN mkdir -p ~/jenkins

RUN echo -e "groupadd -g \$DOCKER_GROUP_ID docker \n\
usermod -aG docker root \n\
curl -sO http://\$JENKINS_IP:\$JENKINS_PORT/jnlpJars/agent.jar \n\
java -jar agent.jar -url http://\$JENKINS_IP:\$JENKINS_PORT/ -secret \$SECRET_CODE -name \$NODE_NAME -workDir \$NODE_WORK_DIR" \
> ~/jenkins/agent-start.sh

ENTRYPOINT bash ~/jenkins/agent-start.sh

（这Dockerfile文件是根据Jenkins给出的代理节点的连接脚本写的。在执行docker run时需要配置Dockerfile文件中定义好的环境变量）

4.6.2 生成从节点镜像

接下来，在上述Dockerfile文件所在目录中打开git bash,执行以下命令，注意最后有一个点符合(”.“）：

docker build -t jenkins-node-maven .

成功执行后，我们就得到了需要的从节点镜像jenkins-node-maven:latest，这个从节点镜像可用来构建任一Java Maven项目，是通用的。

4.6.3 运行从节点镜像

以下是该从节点镜像在windows中ubuntu on windwos命令行中运行的命令:

docker run -e JENKINS_IP=192.168.1.214 -e JENKINS_PORT=8080 -e NODE_NAME=maven2 -d -e SECRET_CODE=b71fca619714adf6456b69c5773eaad0929d089ba7595417125c06b11e0704c3 -v /mnt/d/jenkins/node/maven1:/data -v /mnt/d/maven-repository:/root/.m2 -v /var/run/docker.sock:/var/run/docker.sock -v /usr/bin/docker:/usr/bin/docker --privileged --name maven1 jenkins-node-maven:latest

其中：对4个环境变量进行了赋值（读者可根据自己的环境进行设置），并且挂载了宿主机中4个目录到容器中：

-v /mnt/d/jenkins/node/maven1:/data ——挂载了Jenkins工作目录所在的根目录（也即在Jenkins新增节点时定义的远程工作目录）。

-v /mnt/d/maven-repository:/root/.m2——挂载了maven本地库目录，避免每次都重新下载这种构建过程中需要的库文件。

后面两个挂载的是宿主机中的docker，使得容器中可以执行docker命令。

-v /var/run/docker.sock:/var/run/docker.sock

-v /usr/bin/docker:/usr/bin/docker

上述docker run命令执行成功后，我们在Jenkins的从节点列表中可以看到，maven2节点的状态已经变为在线状态了，如下图：

5. 配置通用构建项目

创建Jenkins构建项目的策略有两种：

• 为公司的每个项目都创建一个Jenkins JOB项目。这种策略的优点在于可对单个项目自定义各种Jenkins提供的扩展，而不影响其他JOB。缺点是：每个项目都需要创建对应的JOB项目；且每个项目在Git源码仓库中的webhook配置也是不同的，配置时必须确保webhook通知的目标URL地址是与Jenkins中JOB的地址是一致的。 这种方式下，新项目构建前需要对Jenkins和Git源码仓库中该项目的webhook两者都进行配置。
• 创建一个通用Jenkins JOB项目, 通过该JOB项目构建所有公司内的软件项目。这种策略不适合需要对单个项目进行某种构建扩展的场景。优点也是明显的，不需要为每个项目创建一个JOB，且Git源码仓库的webhook中的URL的请求地址只有一个(参数不同)，与具体项目名称无关，配置时不易出错。这种方式下，新项目构建前仅需对Git源码仓库中该项目的webhook进行配置。

推荐采用第二种方式。

5.1 创建通用构建JOB

5.1.1 新建流水线任务

在Jenkins主界面上点击左边的”新建任务“，Jenkins打开如下图界面：

在该界面中输入任务名称，并选中流水线（wydevops项目源码中提供了流水线脚本文件）类型，最后点击下面的”确定“按钮。此时Jenkins打开任务详细配置界面，如下图：

勾选”参数化构建过程“和”Generic Webhook Trigger“两项。

5.1.2 配置Generic Webhook Trigger参数

为Generic Webhook Trigger配置以下post参数: 

还有以下request参数：

5.1.3 配置流水线

向下滚动，继续配置流水线参数。

在Additional Behaviours处，新增”检出到子目录“项。

并配置检出子目录为:/data/workspace/wydevops，各参数解释如下图。

最后点击保存，即完成了通用构建JOB的创建。

6. 通过流水线界面执行构建

6.１ 配置从节点到部署服务器的SSH免密登录

        从节点要能完整执行wydevops构建流程，需要首先配置好从节点到部署服务器的SSH免密登录。我这里使用的是ubuntu on windows子系统作为部署服务器的，在buntu on windows子系统中执行ip addr show 命令，可以查询到buntu on windows子系统的IP地址， 如下图红框：

有了服务器IP地址后，我们从docker desktop进入容器（这里的容器是maven2）的命令行，在其命令行中执行如下两条命令：

ssh-keygen -t rsa (一直回车，直到命令执行完毕)

ssh-copy-id {账号}@{目标服务器IP地址} （中间会要求输入账号对应的密码）

其中：

账号——是通过SSH连接目标服务器时使用的账号

目标服务器IP地址——即上述的查询到的服务器IP地址。

执行截图如下：

上图中第一次执行ssh-copy-id命令失败了，原因是ubuntu on windows开启ssh服务。在ubuntu on windows子系统中执行了sudo service ssh restart命令（如果没有安装ssh，则先执行sudo apt install openssh-server命令）后，再次执行ssh-copy-id就成功了（中途要输入一次yes和账号的密码），如下图。

执行完毕后，容器maven2就能ssh免密登录目标部署服务器了。

6.2 首次流水线构建

        流水线任务创建完毕后，Jenkins的任务列表如下，可以看到刚才创建的wydevops-build-all任务项。点击该任务项，打开任务详情页面。

在下面的任务项详情界面中，点击左侧的”立即构建“。

第一次构建肯定会失败，但会自动配置好流水线需要的构建参数（之前没有手动配置，我们通过这个首次构建来自动完成）。首次构建失败后，刷新当前页面，会发现多出来了下图红框处的菜单项。

6.3 参数化构建

点击上图出现的 "Build with Parameters"菜单，会打开如下界面：

可以看到：

       默认构建项目名称为java-sample，这是在wydevops源码中Jenkins.all文件中定义的默认值，如下图。可以在Jenkins.all文件中将这个参数修改为”choice“类型的参数，这样就可以约束只能构建某些项目。下图中，GIT_USER_ID参数的值为”1“,这个正是之前定义凭据时为其定义的ID值，向Jenkins指明了在拉取目标项目时向Git源码仓库提交哪套用户凭据信息。从这里可以看出，该用户在Git源码仓库中应拥有拉取wydevops项目和其他目标项目的权限才行，否则在拉取源码时会报错。

上图中还有一个AGENT_LABEL参数，这个参数默认指定了构建本项目使用的从节点的标签。因此在创建从节点时一定要设置好从节点标签名称。流水线相关知识这里就不展开了。

在上面的参数化构建界面上，我们更改ARCH_TYPES参数为linux/amd64,并更新AGENT_LABEL参数的值为maven2，最后点击”build“按钮。此时需要刷新一下页面才会出现新的构建进度条，如下图：

将鼠标移动到新出现的构建进度条#3处，会出现一个下拉图标，点击下拉图标会弹出上图的菜单条，在该菜单条中选择Console Output项，Jenkins会打开构建日志详情输出界面，如下图：

这里输出的日志，除了CheckOut部分外，其他的与本地工作模式下输出的日志就时一样的了，如下图：

6.3 WebHook触发构建

6.3.1 Git源码项目中配置webhook参数

        如下图，点击wydevops-build-all任务的配置菜单，

Jenkins会打开该任务的详细配置界面，此时，可以看到参数化构建过程项下面多出来了很多参数，这些参数就是首次构建时自动从jenkins.all文件读取的配置参数，如下图：

继续找到如下图的内容：

红框部分即是webhook的通知地址，需要将JENKINS_URL换成Jenkins服务的公网IP地址（可以是内外映射出去的IP地址），并且需要带上定义的request参数。最终的webhook URL地址格式如下（这里是按java-sample项目配置的）：

http://JENKINS_URL/generic-webhook-trigger/invoke?PROJECT_LANGUAGE=java&AGENT_LABEL=maven2&BUILD_PATH=./

注意：Jenkins还会从webhook提交的数据中获取到以下Post参数的值：GIT_PROJECT_NAME、GIT_GROUP、GIT_BRANCH；还会从环境变量中获取：BUILD_SCRIPT_ROOT、 DOCKER_REPO_INFO、CHART_REPO_INFO参数。

特别说明：到目前为止可以看到，不论是从Jenkins流水线界面还是从WebHook触发wydevops的构建流程，其提供的构建参数都没有本地模式下命令行输入的参数齐全。流水线界面没有定义目标架构类型和离线安装包的架构类型（默认等于目标架构类型）；Webhook发出的请求中还多缺少了一个BUILD_TYPE参数。这些缺少的参数将会默认使用项目中ci-cd-config.yaml文件中或全参数模板文件(_ci-cd-template.yaml)中的值。镜像缓存目录参数在jenkins模式下无效。

6.3.2 webhook触发构建的演示

        偷一下懒，这个就不演示了。

7. 流水线效果图

7.1 Pipeline Console效果图

7.2 Pipeline Overview效果图

8. 结束语

        在写这篇文章之前，发现使用的Jenkins版本比较老，就使用了比较新的上述版本的Jenkins镜像。由此作为例子的maven节点镜像也需要重新构建。在这个过程中也遇到了很多问题，这篇文章写的比较细，也是为了以后不再踩已经踩过的坑。

       这里再提一点，从节点的并行构建数最好设置为1，因为如果大于1的情况下，如果同一个项目的两次并发构建任务其架构是不同，而在同一个docker环境中同名镜像只能存在一个，此时必定会有一个构建任务会失败（wydevops内部检查了构建成功的Docker镜像的架构是否于目标架构一致，不一致会报错退出）。

        至此，wydevops与jenkins的集成就介绍到这里了。期待你的关注、点赞和收藏！