Jenkins 配置即代码：使用 JCasC 管理配置

Jenkins Configuration as Code（JCasC，配置即代码）将 Jenkins 配置参数定义在易于阅读的 YAML 文件中，并把这个文件作为源代码保存。它本质上记录了通过 Web 界面配置 Jenkins 时所使用的参数与值。之后，只需编辑这个文件并应用它，就能修改配置。

过去，有经验的 Jenkins 管理员会编写 Apache Groovy 初始化脚本，自动配置 Jenkins 控制器。这种方式确实有效，但要求深入理解 Jenkins API，并具备编写 Groovy 脚本的能力。脚本非常强大，几乎可以完成任何操作，同时也很少为配置错误提供保护。

JCasC 让你无需使用界面就能便捷、灵活地配置控制器。它要求掌握的配置参数知识，不会比通过界面配置 Jenkins 更多，同时还会对填写的值进行一些检查。

将 JCasC 配置文件纳入源代码管理系统（SCM）后，就能知道谁对配置做了哪些修改，并在需要时回滚到以前的配置。

要建立 JCasC 配置，必须在对应的 Jenkins 控制器上安装 Configuration as Code 插件。如果仪表盘的“Manage Jenkins”页面中，“System Configuration”部分没有“Configuration as Code”入口，就需要安装该插件。

查看 JCasC 文件

安装插件后，“Manage Jenkins”页面的“System Configuration”部分会出现“Configuration as Code”。点击它，再点击“View Configuration”，就能查看 YAML 文件。

这个文件是当前控制器配置的导出结果。多数情况下，无需修改就可以使用，不过部署前通常会进行定制。也可以先将未经修改的版本提交到 SCM，作为历史记录的一部分。

“Configuration as Code”页面显示当前 YAML 文件的完整路径，并提供一个输入框，用于指定其他文件。修改 YAML 文件位置的方法见下文。

默认 JCasC YAML 文件包含四个部分：

• jenkins：定义 Jenkins 根对象，包含“Manage Jenkins → System”以及“Manage Jenkins → Configure Nodes and Clouds”页面中的配置。
• tool：定义“Manage Jenkins → Tools”页面中可以设置的构建工具。
• unclassified：定义其他所有配置，包括已安装插件的配置。
• credentials：定义“Manage Jenkins → Manage Credentials”页面中可以设置的凭据。你可能希望从 YAML 文件中删除这一部分；使用 Ansible 与 JCasC 安装 Jenkins 中讨论了这一点。

YAML 文件语法

JCasC 用 YAML 文件定义控制器配置。YAML 是一种常见的配置信息序列化语言，语法直接、易读，但要求精确。

关于 YAML 语法，需要注意以下几点：

• YAML 文件区分大小写。
• 缩进非常重要，必须严格遵守格式。
• 每个项目都是键值对，键后面跟一个冒号 : 和一个空格。
• 除非用引号括起来，否则 YAML 会将某些字符串转换为其他类型。比如 true、false、Yes、No 会转为布尔值；原文将 2 和 3.0 列作转换为浮点值的例子。
• 值可以是一个列表。每个列表项独占一行，以短横线 - 开头，同一列表中的项目必须使用相同的缩进。
• 使用空格缩进，不要使用制表符。
• 原文还提醒不要在 YAML 文件中留空行，否则可能出问题。

关于 YAML 文件语法的更多细节，见 YAML 参考卡。

将 YAML 文件纳入 SCM

要充分发挥 JCasC 的作用，应将 YAML 文件保存在 SCM 中。这样可以通过历史记录追踪修改，并在必要时轻松回滚到早期版本。

JCasC 并不强制把文件放在 SCM 中，因此也不会规定具体的管理方式。最常见的做法是创建一个 SCM 仓库，集中存放全部 JCasC 文件。

如果决定使用 SCM 管理 JCasC YAML 文件，应在修改之前，先提交首次生成的默认文件。

修改 JCasC 文件

使用你习惯的文本编辑器，编辑“Manage Jenkins → Configuration as Code”页面列出的文件。默认路径是 $JENKINS_HOME/jenkins.yaml。

可以先做一个简单练习：修改 Jenkins 仪表盘上显示的“System Message”，了解完整操作流程。

1. 使用文本编辑器打开 JCasC YAML 文件。
2. 找到文件顶部附近的 systemMessage 行：

jenkins:
  systemMessage: "Jenkins configured automatically by Jenkins Configuration as Code plugin\n\n"

3. 将引号之间的文字修改为新的内容。
4. 保存文件。
5. 点击“Reload existing configuration”应用修改。
6. 回到仪表盘，查看更新后的“System Message”。

应用 JCasC 修改不需要重启 Jenkins。不过，在将修改后的 YAML 提交到 SCM 之前，应尝试使用修改后的配置重启 Jenkins，尤其是在进行了实质性的配置变更时。

完成并测试所需的修改后，将更新后的 JCasC YAML 文件推送到 SCM。

通过 JCasC 配置插件

通过 JCasC 配置插件的步骤如下：

1. 使用现有系统的界面安装并配置插件。
2. 点击“Apply → Save”保存配置。
3. 进入“Manage Jenkins → Configuration as Code → View Configuration”，查看包含插件配置的 JCasC 文件。
4. 点击“Download Configuration”，将修改后的配置文件保存到本地。
5. 如有需要，编辑 YAML 文件，进一步调整配置。
6. 保存文件。
7. 点击“Reload existing configuration”，将本地修改加载到 Jenkins 服务器。
8. 在界面中确认修改结果。
9. 充分测试插件配置后，将更新后的 YAML 文件推送到 SCM。

使用 JCasC 配置插件 这篇博客提供了详细说明，并嵌入了演示整个过程的视频。

YAML 文件位置

CasC 配置的 YAML 文件默认位于 $JENKINS_HOME/jenkins.yaml。“Configuration as Code”页面会显示正在使用的文件名称与位置。可以在“Path or URL”输入框中填写完整路径，指定另一个要查看的文件。

要改变 JCasC YAML 文件的创建位置或文件名，可以采用以下任一方式：

• 设置环境变量 CASC_JENKINS_CONFIG，让它指向一个以逗号分隔的配置文件位置列表。
• 使用 Java 属性 casc.jenkins.config 控制文件名与位置。通过软件包管理工具安装 Jenkins 时，这种方式很有用。多数包管理系统支持在升级时保留配置文件；最好不要直接修改软件包管理器安装的文件，因为更新可能覆盖它。

在 Linux 系统上，可以运行 systemctl edit jenkins，然后添加：

[Service]
Environment="JAVA_OPTS=-Dcasc.jenkins.config=/jenkins/casc_configs"

文件位置与名称可以采用以下任一种形式：

• 包含一组配置文件的文件夹路径，例如 /var/jenkins_home/casc_configs。
• 单个文件的完整路径，例如 /var/jenkins_home/casc_configs/jenkins.yaml。
• 指向 Web 上文件的 URL，例如 https://acme.org/jenkins.yaml。

CASC_JENKINS_CONFIG 的值按以下规则解析：

• 如果某个项目指向文件夹，插件会递归遍历该文件夹，寻找后缀为 .yml、.yaml、.YAML 或 .YML 的文件。
• 排除隐藏文件，也排除完整路径中任何位置含隐藏文件夹的文件，例如 /jenkins/casc_configs/.dir1/config.yaml。
• 跟随文件和目录的符号链接。

遍历顺序不影响最终结果，因为发现的所有配置文件必须互为补充。如果一个文件试图覆盖另一个文件中的配置值，就会产生冲突，并抛出 ConfiguratorException。

CasC 配置与界面修改

Jenkins 控制器应选择使用 CasC 或界面进行配置，不应混用。即使某项设置由 CasC 定义，系统仍允许管理员在界面中修改它，但下次控制器重启时，这些界面修改会被覆盖。

可以安装 Extended Read Permission 插件，向用户授予配置参数的只读访问权限。详情见 JEP-224：只读系统配置。

少量管理员可以保留界面配置字段的写入权限，但他们应当理解：JCasC 会覆盖他们在界面中所做的修改。

更多资料

一般资料

• Look Ma! No Hands!：以代码管理 Jenkins 配置，这是 2018 年 DevOps World 演讲的视频，介绍了 JCasC 功能。
• 使用 JCasC 配置插件，包含视频的博客，演示如何使用 JCasC 配置插件。
• 使用 Ansible 与 JCasC 安装 Jenkins，提供 JCasC 使用细节的视频演示。

实现细节

许多详细的 JCasC 文档保存在 GitHub 仓库 中：

• 实现细节。
• demos 目录 包含用于配置特定 Jenkins 组件和插件的 *.yaml 示例，每个目录都附有 README，说明该组件的配置。
• 如何使用 Job DSL 创建初始 seed 作业。
• 使用场景。
• 触发配置重新加载。
• 导出配置。

面向插件开发者与维护者的资料

• JCasC 开发者文档。
• JCasC 要求：插件维护者指南。

原文：Configuration as Code。作者／维护者：Jenkins 项目文档贡献者。本文为原文的中文译文；代码保留原文内容。