Jenkins Custom WAR Packager

概述

Custom WAR Packager（CWP）允许使用YAML规范构建即用型Jenkins包。该工具可生成Docker镜像、WAR文件和Jenkinsfile Runner Docker镜像（也称为单次运行Jenkins主节点）。这些包可包含Jenkins核心、插件、额外库，以及通过Groovy Hook脚本或Configuration-as-Code插件 YAML文件的自配置。

更多信息请参见此博客文章。

核心功能与特性

• 支持构建多种类型的Jenkins包：Docker镜像、WAR文件、Jenkinsfile Runner Docker镜像
• 可包含Jenkins核心、指定版本的插件、额外库
• 支持通过Groovy Hook脚本或Configuration-as-Code插件实现自配置
• 提供CLI和Maven插件两种使用方式
• 支持物料清单（BOM）作为输入，加载插件和组件依赖
• 允许从POM文件获取插件，简化开发版本的打包

使用场景

• 构建自定义Jenkins WAR文件，包含特定版本的核心和插件
• 创建集成Maven的Jenkins包
• 配置Jenkins外部任务日志到Elasticsearch
• 通过Configuration-as-Code插件使用YAML配置Jenkins
• 修改Jenkins核心组件（库、模块）
• 构建包含完整CI流程的独立Jenkins演示包
• 打包Jenkinsfile Runner Docker镜像

演示示例

• Jenkins WAR - 所有最新版 - 捆绑核心和一些关键库/模块的主分支
• Jenkins WAR - 所有最新版与Maven - 与上述相同，但包含Maven
• 外部任务日志到Elasticsearch - 运行外部日志演示并通过System Groovy Hooks预配置。该演示以Docker打包，并提供即用型Docker Compose包。
• 配置即代码 - 通过YAML使用Configuration-as-Code插件配置WAR
• 核心组件构建 - 演示如何修改核心组件（库、模块）
• Custom WAR Packager CI演示 - 带有集成CI流程的独立演示
• Jenkinsfile Runner - 打包Jenkinsfile Runner的Docker镜像

使用方法

前提条件

• Maven 3.5.0或更高版本
• Java 8
• Git（如果定义了任何Git源）

Custom WAR Packager提供了一个Docker镜像，其中捆绑了所有必需的工具。

CLI

shell
java -jar custom-war-packager-cli.jar -configPath=mywar.yml -version=1.0-SNAPSHOT -tmpDir=tmp

构建后，生成的WAR文件将被放置在tmp/output/target/${artifactId}.war。

要使用此配置以演示模式运行工具，请使用以下命令：

shell
java -jar war-packager-cli.jar -demo

不带选项调用工具可获取完整的CLI选项列表。

Maven

Maven插件运行打包器并生成工件。工件将被放置在target/custom-war-packager-maven-plugin/output/target/${bundle.artifactId}.war，并添加到项目工件中。

xml
  <build>
    <plugins>
      <plugin>
        <groupId>io.jenkins.tools.custom-war-packager</groupId>
        <artifactId>custom-war-packager-maven-plugin</artifactId>
        <version>@project.version@</version>
        <executions>
          <execution>
            <phase>package</phase>
            <goals>
              <goal>custom-war</goal>
            </goals>
            <configuration>
              <configFilePath>spotcheck.yml</configFilePath>
              <warVersion>1.1-SNAPSHOT</warVersion>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>

注意，此插件调用Maven-in-Maven，且不会将构建选项传递给插件。可使用配置文件配置下游构建器。

配置文件

示例：

yaml
bundle:
  groupId: "io.github.oleg-nenashev"
  artifactId: "mywar"
  description: "Just a WAR auto-generation-sample"
  vendor: "Jenkins project"
buildSettings:
  docker:
    base: "jenkins/jenkins:2.121.1"
    tag: "jenkins/demo-external-task-logging-elk"
    build: true
war:
  groupId: "org.jenkins-ci.main"
  artifactId: "jenkins-war"
  source:
    version: 2.107
plugins:
  - groupId: "org.jenkins-ci.plugins"
    artifactId: "matrix-project"
    source:
      version: 1.9
  - groupId: "org.jenkins-ci.plugins"
    artifactId: "durable-task"
    source:
      git: [***]
      branch: watch-JENKINS-38381
  - groupId: "org.jenkins-ci.plugins.workflow"
    artifactId: "workflow-durable-task-step"
    source:
      git: [***]
      commit: 6c424e059bba90fc94a9c1e87dc9c4a324bfef26
  - groupId: "io.jenkins"
    artifactId: "configuration-as-code"
    source:
      version: 0.11-alpha-rc373.933033f6b51e
libPatches:
  - groupId: "org.jenkins-ci.main"
    artifactId: "remoting"
    source:
      git: [***]
systemProperties: {
     jenkins.model.Jenkins.slaveAgentPort: "50000",
     jenkins.model.Jenkins.slaveAgentPortEnforce: "true"}
groovyHooks:
  - type: "init"
    id: "initScripts"
    source: 
      dir: scripts
casc:
  - id: "jcasc-config"
    source:
      dir: jenkins.yml

还有更多可用选项。有关示例，请参见链接的演示。

BOM支持

该插件支持JEP-309中描述的物料清单（BOM）作为输入。

如果定义了BOM，Custom WAR Packager将从中加载插件和组件依赖。以下示例从BOM获取输入并生成自定义WAR和Docker包。

yaml
bundle:
  groupId: "io.jenkins.tools.war-packager.demo"
  artifactId: "bom-demo"
buildSettings:
  bom: bom.yml
  environment: aws
  docker:
    base: "jenkins/jenkins:2.121.2"
    tag: "jenkins/cwp-bom-demo"
    build: true

此类配置的示例可在此处获取。

来自POM的插件

为简化开发版本的打包，可以将Custom War Packager链接到POM文件，以便从中获取要捆绑的插件。

如果设置了pom选项，将添加所有依赖项，包括测试依赖项。当前父项也将被捆绑，除非设置了pomIgnoreRoot标志。

yaml
bundle:
  groupId: "io.jenkins.tools.war-packager.demo"
  artifactId: "pom-input-demo"
buildSettings:
  pom: pom.xml
  pomIgnoreRoot: true
war:
  groupId: "org.jenkins-ci.main"
  artifactId: "jenkins-war"
  source:
    version: 2.121.1

示例可在此处获取。

高级功能

特性：

• 使用自定义依赖项（如Remoting或Stapler）重建Jenkins核心
• 向Jenkins核心添加额外库，以便在扩展中使用

限制

当前，该工具处于alpha状态。它有一些严重的限制：

• 所有带有Git源的构建工件都将安装到本地仓库中
  • 每个提交的版本都是唯一的，因此请注意本地仓库污染
• 系统属性仅适用于核心中定义的自定义jenkins.util.SystemProperties类
  • 如果需要设置其他系统属性，请使用Groovy Hook脚本
• libPatches步骤仅捆绑指定的JAR文件，而非其依赖项 如果依赖项与基础WAR文件相比有变化，则也需要显式打包这些依赖项
  • 可使用libExcludes删除不再需要的依赖项