Jenkins 凭证 Devops 的粘合剂

2021 年 7 月 9 日
筆記
CICD, DevOps, Jenkins

大家好，我是小猿来也，一个热衷于搞 Devops 自动化的 Java 程序猿。

万事具备，只欠东风。当我决定大搞特搞 Devops 的时候，Jenkins 凭证却傻傻分不清。

玩 Devops 的小伙伴应该对 Jenkins 都有了解。

Github 上 16.8k 的 Star 的项目，1500+ 的构建、发布等自动化插件可供选择，事实上的业界 CICD 标准领导者。

今天就和大家简单分享一下 Jenkins 凭证，主要内容包括 Jenkins 凭据的介绍，Jenkins 凭据的种类，Jenkins 凭证的安全性，以及如何配置 Jenkins 凭据，最后通过一个基于 GitHub 的 SSH 凭证配置的试验，来详细演示 Jenkins 凭据的配置流程及注意事项。

1. 凭证介绍

Jenkins 凭证是指很多可以和 Jenkins 进行交互的第三方站点和应用程序，如 GitHub，SonarQube，Jira，Docker 等为 Jenkins 专门配置的凭证，通过这样的专门的凭证可以将 Jenkins 对第三方站点和应用程序的可用功能区间锁定在特定的范围内。

2. 凭证的种类

Jenkins可以存储以下类型的凭证：

Username and password (用户名和密码) ：可以是单独的用户名、密码，也可以是冒号分隔的字符串（格式为 username:password），如 GitHub 的用户名和密码
GitHub App ： Github App 可以通过 Github 提供的认证信息去调用 Github API。GitHub端的设置路径在 GitHub 的 Settings / Developer settings 下。
SSH Username with private key （ SSH 用户名与私有密钥）：一个 SSH 公钥/私钥对
Secret file（加密文件）：本质上是文件中的加密内容
Secret text（加密文本）：API令牌（例如 GitHub 个人访问令牌）
Certificate （证书）：一个PKCS＃12证书文件和可选密码

3. 凭证的安全性

为了最大程度地提高安全性，在 Jenkins 中配置的凭证会以加密形式存储在 Jenkins 实例上（基于 Jenkins 实例 ID 进行加密），并且Jenkins job 中仅通过凭证 ID 来使用。

这最大程度地减少了将实际凭证本身暴露给 Jenkins 用户的机会，并阻碍了将凭证从一个 Jenkins 实例复制到另一个实例的可能。

4. 配置凭证

任何具有”凭证”>”创建”权限的 Jenkins 用户都可以将凭证添加到 Jenkins。Jenkins 用户可以使用 Administer 权限来配置这些权限。

同时，如果你的 Jenkins 实例的”全局安全配置”页面的”授权策略”被设置为默认的”登录用户可以执行任何设置”或”任何人可以做任何设置”，则任何 Jenkins 用户都可以添加和配置凭证。

5. 添加新的全局凭证

要将新的全局凭证添加到 Jenkins 实例，需要执行以下操作：

确保已登录 Jenkins，具有 “凭证” > “创建” 权限。
在 Jenkins 主页中，单击左侧的 Manage Jenkins > Manage Credentials。
在右侧作用范围为 Jenkins 的凭证存储下，单击 Jenkins。
在”System”下，单击”Global credentials (unrestricted)”链接以进入默认域。
点击左侧的添加凭证。
注意：如果此默认域中没有凭证，则也可以单击”添加一些凭证”（与单击”添加凭证”相同）。

选择凭证种类，在”种类”字段中，选择要添加的凭证的类型。
在”范围”字段中，选择以下任一项：

全局：如果要添加的凭证是针对管道 job 的。选择此选项会将凭证的范围应用于管道 job “对象”及其所有后代对象。
系统：如果要添加的凭证是 Jenkins 实例本身与系统管理功能（例如，电子邮件身份验证，代理连接等）进行交互的 job。选择此选项会将凭证的范围应用于只单个 job。

将凭证本身添加到所选凭证类型的相应字段中：

加密文本：复制加密文本并将其粘贴到”Secret”字段中。
用户名和密码：在相应字段中指定凭证的用户名和密码。
加密文件：点击选择文件按钮旁边的文件字段选择秘密文件上传到 Jenkins。
带有私钥的 SSH 用户名-在其各自的字段中指定凭证 Username， Private Key 和可选的 Passphrase。
注意：直接选择 Enter 可让您复制私钥的文本并将其粘贴到生成的 Key 文本框中。
证书：指定证书和可选的密码。选择上传 PKCS＃12 证书，可以通过出现的上传证书按钮将证书作为文件上传。
Docker 主机证书认证：将适当的详细信息复制并粘贴到客户端密钥，客户端证书和服务器CA证书字段中。

在 ID 字段中，指定一个有意义的凭证 ID 值-例如 jenkins-user-for-xyz-artifact-repository。您可以使用大写或小写字母作为凭证 ID，以及任何有效的分隔符。但是，为了使您的 Jenkins 实例上的所有用户受益，最好使用单一且一致的约定来指定凭证 ID。
注意：此字段是可选的。如果未指定其值，Jenkins 将为凭证ID分配一个全局唯一 ID（GUID）值。需要强调的是，一旦设置了凭证 ID，就无法再更改它。
为凭证指定一个可选的描述。
单击确定以保存凭证。

6. 基于 GitHub 的 SSH 凭证配置试验

6.1. 添加凭证

SSH 的凭证由一个公钥文件一个私钥文件，这样两个文件组成。

$ cd .ssh/
$ pwd
/Users/your-jenkins-run-system-user/.ssh
$ ls
id_rsa			id_rsa.pub

我们需要把其中的id_rsa.pub的内容，即公钥的内容配置到 GitHub 端。

同时把id_rsa的内容，即私钥的内容配置到 Jenkins 端，这样才算完成了 Jenkins 和 GitHub 交互前的凭证配置。

给 Jenkins 添加一个凭证最直接的方法就是如第5部分内容所描述的操作步骤，进入添加凭证的页面(如上图所示)。

在添加凭证的表单的凭证类型字段中选择SSH Username with private key类型。
ID 字段非必填，不填系统会自动生成。
描述字段非必填，可以随意填写。
Username 字段非必填，可以随意填写，不填时保存后会默认补上运行 Jenkins 的操作系统用户。
Private Key 字段就是配置你的 SSH 私钥的地方。正确的打开方式是你需要拷贝你的id_rsa文件的实际内容到这个地方即可。

这里因为是在做试验，所以随意填写一个字符串，比如codingnb，当然你可以按照自己的喜好随意填写。
完整的凭证配置信息如下图所示。

Passphrase 字段根据你生成 SSH 的凭证时的实际情况填写，一般情况下这个字段不填即可。
填完所有信息”确定”之后，你就会在全局凭证列表中看到刚才添加的名为ssh-credentials-test-error的凭证。

正如它的名字一样，ssh-credentials-test-error是一个错误的凭证，后面我们会验证这个凭证的有效性。

6.2. 测试凭证的有效性

凭证有了，那么怎么验证它的有效性呢？
为了验证凭证的有效性，我们创建了一个自由风格的 Jenkins job 来做试验，这个 job 我们把它叫做ssh-credentials-demo。

Jenkins 中自由风格的 job 由General、源码管理、构建触发器、构建环境、构建、构建后操作6个阶段组成。

本试验中这个 job 做的事情非常简单，就是从 GitHub 上拉取事先准备好的源代码，然后执行ls -a命令查看下载之后的文件目录。如果能够正常拉取代码则证明凭证有效，否则凭证无效。

试验中这6个阶段中需要稍加配置的阶段，我会在下面分别给予说明，未做说明的阶段，你使用默认的配置即可。

源码管理

仓库地址：[email protected]:tobrainto/demo.git 分支：main。

在配置源码仓库地址和分支的同时你还需要指定 Jenkins 和 GitHub 交互的凭证。
这个时候你可以选择一个已经添加好的凭证，也可以通过 Jenkins 在源码管理配置的界面中提供的快捷入口来添加一个新的凭证。

为了完成对比试验，这里先选择之前创建的那个有问题的名为ssh-credentials-test-error的凭证，之后我们会通过这边提供的快捷入口添加一个正确的凭证。

选中ssh-credentials-test-error后，经过1秒到2秒 Jenkins 会自动去验证凭证的有效性，因为凭证ssh-credentials-test-error中 Private Key 字段是随意填写的，所以这里凭证会验证失败。

详细的错误信息如下

无法连接仓库：Command "git ls-remote -h -- [email protected]:tobrainto/demo.git HEAD" returned status code 128:
stdout:
stderr: Load key "/var/folders/hq/9rdkq_5j7cz_25s2lqntqhwr0000gn/T/jenkins-gitclient-ssh12631328169216538563.key": invalid format
[email protected]: Permission denied (publickey).
fatal: 无法读取远程仓库。

请确认您有正确的访问权限并且仓库存在。

我们先不管这个错误，继续进行试验。

构建

构建阶段只是简单的执行ls -a命令查看下载之后的文件目录。

3. 构建后操作

构建后我们删除当前工作区，以免影响下一次试验的构建。

对这些需要配置的阶段完成配置之后，我们立即构建ssh-credentials-demo这个 job，不出意外这个 job 构建失败了。

这个时候我们回到ssh-credentials-demo这个 job 的配置中，重新进入源码管理阶段，通过源码管理提供的凭证”添加”按钮添加一个正确的凭证。

点击上图红框内的”添加”按钮，弹出下图所示的凭证添加表单窗。

这一次 Private Key 字段我们配置正确的内容，即和上面 GitHub 端配置的公钥配对的私钥文件的内容。

提交表单之后，我们在源码管理中的备选凭证列表中已经可以看到刚才添加的名为ssh-credentials-test-yeah的凭证。

我们选中它，最初选中的时候，依然会有上面的红色的凭证验证失败的提示，那个提示是之前使用ssh-credentials-test-error凭证留下的验证信息，我们不用管它。

大概过了1秒到2秒之后，基于ssh-credentials-test-yeah凭证的校验信息就会覆盖它，新的凭证校验成功，之前红色的凭证验证失败的提示信息消失了。

紧接着我们再一次构建ssh-credentials-demo这个 job ，嗯构建成功了。

另外当我回到全局凭证列表，在列表中我们已经可以看到刚刚添加的名为ssh-credentials-test-yeah的凭证。

在这个列表里我们选择ssh-credentials-test-error这个凭证进行编辑，我们仅仅把它的 Private Key 字段的值由之前随意填写的codingnb改成同ssh-credentials-test-error凭证的 Private Key 字段的值相同的真正的 SSH 私钥文件的内容，其他字段内容一律不做修改，保持不变。
然后我们回到ssh-credentials-demo这个 job ，我们再次把它使用的凭证改为ssh-credentials-test-error这个凭证。
以上变更过程中的图我们这里就不再贴了。
最后我们再一次构建ssh-credentials-demo这个 job ，嗯同样，我们使用修改之后的ssh-credentials-test-error这个凭证对job构建成功了。

6.3. 结论

最后我们简单总结一下，Jenkins 支持 6 种类型的凭证，我们最常使用的是 SSH 凭证。

试验中我们我们分别演示了从 job 中创建凭证和从系统管理中创建凭证。

实验中可以看出来给 Jenkins 配置 SSH 凭证，只要填上正确的 SSH 私钥即可，用户名等其他字段的信息对凭证的有效性是没有影响。

Jenkins 凭据我们这次就先介绍这么多，更多有关 Jenkins 的知识，Devops 从零到一的落地实践，我们慢慢一起学习，一起实践，我会继续在这里分享。

Tags: CICD DevOps Jenkins