使用 Jenkinsfile 创建流水线

Jenkinsfile 是一个文本文件，它包含 Jenkins 流水线的定义，并被检入源代码控制仓库。Jenkinsfile 将整个工作流存储为代码，因此它是代码审查和流水线迭代过程的基础。有关更多信息，请参见 Jenkins 官方文档。

本教程演示如何基于 GitHub 仓库中的 Jenkinsfile 创建流水线。您可以使用该流水线将示例应用程序分别部署到可从外部访问的开发环境和生产环境。

备注

KubeSphere 中可以创建两种类型的流水线：一种是本教程中介绍的基于 SCM 中 Jenkinsfile 创建的流水线，另一种是通过图形编辑面板创建的流水线。Jenkinsfile in SCM 需要源代码管理 (SCM) 中有内置 Jenkinsfile，换句话说，Jenkinsfile 作为 SCM 的一部分。KubeSphere DevOps 系统会根据代码仓库的现有 Jenkinsfile 自动构建 CI/CD 流水线。您可以定义工作流，例如 stage 和 step。

准备工作

流水线概述

本示例流水线包括以下八个阶段。

流水线概览

备注

  • 阶段 1：Checkout SCM：从 GitHub 仓库检出源代码。
  • 阶段 2：单元测试：待该测试通过后才会进行下一阶段。
  • 阶段 3：SonarQube 分析：SonarQube 代码质量分析。
  • 阶段 4：构建并推送快照镜像：根据行为策略中选定的分支来构建镜像，并将 SNAPSHOT-$BRANCH_NAME-$BUILD_NUMBER 标签推送至 Docker Hub，其中 $BUILD_NUMBER 为流水线活动列表中的运行序号。
  • 阶段 5：推送最新镜像：将 SonarQube 分支标记为 latest，并推送至 Docker Hub。
  • 阶段 6：部署至开发环境：将 SonarQube 分支部署到开发环境，此阶段需要审核。
  • 阶段 7：带标签推送：生成标签并发布到 GitHub，该标签会推送到 Docker Hub。
  • 阶段 8：部署至生产环境：将已发布的标签部署到生产环境。

动手实验

步骤 1：创建凭证

  1. 以 project-regular 身份登录 KubeSphere 控制台。转到您的 DevOps 工程，在工程管理下的凭证页面创建以下凭证。有关如何创建凭证的更多信息，请参见凭证管理。

    备注

    如果您的帐户或密码中包含任何特殊字符，例如 @ 和 $，可能会因为无法识别而在流水线运行时导致错误。在这种情况下，您需要先在一些第三方网站（例如 urlencoder）上对帐户或密码进行编码，然后将输出结果复制粘贴作为您的凭证信息。

    凭证 ID类型用途
    dockerhub-id帐户凭证Docker Hub
    github-id帐户凭证GitHub
    demo-kubeconfigkubeconfigKubernetes

  2. 您还需要为 SonarQube 创建一个凭证 ID (sonar-token)，用于上述的阶段 3（SonarQube 分析）。请参考为新工程创建 SonarQube 令牌 (Token)，在下图所示的密钥字段中输入令牌。点击确定完成操作。

    Sonar 令牌

  3. 您还需要创建具有如下图所示权限的 GitHub 个人访问令牌 (PAT)，然后在 DevOps 项目中，使用生成的令牌创建用于 GitHub 认证的帐户凭证（例如，github-token）。

    github-token-scope

    备注

    如需创建 GitHub 个人访问令牌，请转到您 GitHub 帐户的 Settings，点击 Developer settings，选择 Personal access tokens，然后点击 Generate new token。

  4. 您可以在列表中看到已创建的五个凭证。

    credential-list1

步骤 2：在 GitHub 仓库中修改 Jenkinsfile

  1. 登录 GitHub 并 Fork GitHub 仓库 devops-java-sample 至您的 GitHub 个人帐户。

    fork-github-repo1

  2. 在您自己的 GitHub 仓库 devops-java-sample 中，点击根目录中的文件 Jenkinsfile-online。

    jenkins-edit–1

  3. 点击右侧的编辑图标，编辑环境变量。

    jenkins-edit–2

    条目值描述信息
    DOCKER_CREDENTIAL_IDdockerhub-id您在 KubeSphere 中为 Docker Hub 帐户设置的凭证 ID。
    GITHUB_CREDENTIAL_IDgithub-id您在 KubeSphere 中为 GitHub 帐户设置的凭证 ID，用于将标签推送至您的 GitHub 仓库。
    KUBECONFIG_CREDENTIAL_IDdemo-kubeconfig您在 KubeSphere 中为 kubeconfig 设置的凭证 ID，用于访问运行中的 Kubernetes 集群。
    REGISTRYdocker.io默认为 docker.io，用作推送镜像的地址。
    DOCKERHUB_NAMESPACEyour-dockerhub-account请替换为您的 Docker Hub 帐户名，也可以替换为该帐户下的 Organization 名称。
    GITHUB_ACCOUNTyour-github-account请替换为您的 GitHub 帐户名。例如，如果您的 GitHub 地址是 https://github.com/kubesphere/，则您的 GitHub 帐户名为 kubesphere，也可以替换为该帐户下的 Organization 名称。
    APP_NAMEdevops-java-sample应用名称。
    SONAR_CREDENTIAL_IDsonar-token您在 KubeSphere 中为 SonarQube 令牌设置的凭证 ID，用于代码质量检测。

    备注

    Jenkinsfile 中 mvn 命令的参数 -o 表示开启离线模式。本教程中已下载相关依赖项，以节省时间并适应某些环境中的网络干扰。离线模式默认开启。

  4. 编辑环境变量后，点击页面底部的 Commit changes，更新 SonarQube 分支中的文件。

    commit-changes1

步骤 3：创建项目

您需要创建两个项目，例如 kubesphere-sample-dev 和 kubesphere-sample-prod，分别代表开发环境和生产环境。待流水线成功运行，将在这两个项目中自动创建应用程序的相关部署 (Deployment) 和服务 (Service)。

备注

您需要提前创建 project-admin 帐户，用作 CI/CD 流水线的审核者。有关更多信息，请参见创建企业空间、项目、帐户和角色。

  1. 以 project-admin 身份登录 KubeSphere。在您创建 DevOps 工程的企业空间中创建以下两个项目。请确保邀请 project-regular 帐户至这两个项目中并赋予 operator 角色。

    项目名称别名
    kubesphere-sample-devdevelopment environment
    kubesphere-sample-prodproduction environment

  2. 项目创建后，会显示在项目列表中，如下所示：

    项目列表

步骤 4：创建流水线

  1. 登出 KubeSphere，然后以 project-regular 身份重新登录，转到 DevOps 工程 demo-devops，点击创建构建新流水线。

    创建流水线

  2. 在弹出对话框中填入基本信息，将其命名为 jenkinsfile-in-scm 并选择一个代码仓库。

    创建流水线-2

  3. 在 GitHub 选项卡，从下拉菜单中选择 github-token，然后点击确认来选择您的仓库。

    select-token1

  4. 选择您的 GitHub 帐户，与该令牌相关的所有仓库将在右侧列出。选择 devops-java-sample 并点击选择此仓库，点击下一步继续。

    选择仓库

  5. 在高级设置中，选中丢弃旧的分支旁边的方框。本教程中，您可以为保留分支的天数和保留分支的最大个数使用默认值。

    分支设置

    丢弃旧的分支意味着您将一并丢弃分支记录。分支记录包括控制台输出、已归档制品以及特定分支的其他相关元数据。更少的分支意味着您可以节省 Jenkins 正在使用的磁盘空间。KubeSphere 提供两个选项来确定何时丢弃旧分支：

    • 保留分支的天数：在一定天数之后，丢弃分支。

    • 保留分支的最大个数：分支达到一定数量后，丢弃最旧的分支。

    备注

    保留分支的天数和保留分支的最大个数可以同时应用于分支。只要某个分支满足其中一个字段所设置的条件，则会丢弃该分支。例如，如果您将保留天数和最大分支数分别指定为 2 和 3，待某个分支的保留天数超过 2 或者分支保留数量超过 3，则会丢弃该分支。KubeSphere 默认用 -1 预填充这两个字段，表示已删除的分支将被丢弃。

  6. 在行为策略中，KubeSphere 默认提供四种策略。本示例中不会使用从 Fork 仓库中发现 PR 这条策略，因此您可以删除该策略。您无需修改设置，可以直接使用默认值。

    remove-behavioral-strategy1

    Jenkins 流水线运行时，开发者提交的 Pull Request (PR) 也将被视为一个单独的分支。

    发现分支

    • 排除也作为 PR 提交的分支：不扫描源分支，例如源仓库的 master 分支。需要合并这些分支。
    • 只有被提交为 PR 的分支：仅扫描 PR 分支。
    • 所有分支：拉取源仓库中的所有分支。

    从原仓库中发现 PR

    • PR 与目标分支合并后的源代码版本：PR 合并到目标分支后，基于源代码创建并运行流水线。
    • PR 本身的源代码版本：根据 PR 本身的源代码创建并运行流水线。
    • 发现 PR 时会创建两个流水线：KubeSphere 创建两个流水线，一个流水线使用 PR 与目标分支合并后的源代码版本，另一个使用 PR 本身的源代码版本。

    备注

    您需要选择 GitHub 作为代码仓库才能启用此处的行为策略设置。

  7. 向下滚动到脚本路径。该字段指定代码仓库中的 Jenkinsfile 路径。它表示仓库的根目录。如果文件位置变更，则脚本路径也需要更改。请将其更改为 Jenkinsfile-online，这是示例仓库中位于根目录下的 Jenkinsfile 的文件名。

    Jenkinsfile-online

  8. 在扫描 Repo Trigger 中，点击如果没有扫描触发，则定期扫描并设置时间间隔为 5 分钟。点击创建完成配置。

    高级设置

    备注

    您可以设置特定的时间间隔让流水线扫描远程仓库，以便根据您在行为策略中设置的策略来检测代码更新或新的 PR。

步骤 5：运行流水线

  1. 流水线创建后，将显示在下图所示的列表中。点击该流水线进入其详情页面。

    流水线列表

    备注

    • 您可以点击该流水线右侧的三个点，然后选择复制流水线来创建该流水线的副本。如需并发运行不包含多分支的多个流水线，您可以将这些流水线全选，然后点击运行来批量运行它们。
    • 流水线详情页显示同步状态，即 KubeSphere 和 Jenkins 的同步结果。若同步成功，您会看到成功图标中打上绿色的对号。

  2. 在活动选项卡下，正在扫描三个分支。点击右侧的运行，流水线将根据您设置的行为策略来运行。从下拉列表中选择 sonarqube，然后添加标签号，例如 v0.0.2。点击确定触发新活动。

    流水线详情

    标签名称

    备注

    • 如果您在此页面上未看到任何活动，则需要手动刷新浏览器或点击下拉菜单（更多操作按钮）中的扫描远程分支。
    • 标签名称用于在 GitHub 和 Docker Hub 中指代新生成的发布版本和镜像。现有标签名称不能再次用于字段 TAG_NAME。否则，流水线将无法成功运行。

  3. 稍等片刻，您会看到一些活动停止，一些活动失败。点击第一个活动查看其详细信息。

    活动失败

    备注

    活动失败可能由不同因素所引起。本示例中，在上述步骤中编辑分支环境变量时，仅更改了 sonarqube 分支的 Jenkinsfile。相反地，dependency 和 master 分支中的这些变量保持不变（使用了错误的 GitHub 和 Docker Hub 帐户），从而导致失败。您可以点击该活动，查看其日志中的详细信息。导致失败的其他原因可能是网络问题、Jenkinsfile 中的编码不正确等等。

  4. 流水线在 deploy to dev 阶段暂停，您需要手动点击继续。请注意，在 Jenkinsfile 中分别定义了三个阶段 deploy to dev、push with tag 和 deploy to production，因此将对流水线进行三次审核。

    流水线继续

    在开发或生产环境中，可能需要具有更高权限的人员（例如版本管理员）来审核流水线、镜像以及代码分析结果。他们有权决定流水线是否能进入下一阶段。在 Jenkinsfile 中，您可以使用 input 来指定由谁审核流水线。如果您想指定一个用户（例如 project-admin）来审核，您可以在 Jenkinsfile 中添加一个字段。如果有多个用户，则需要通过逗号进行分隔，如下所示：

    1. ···
    2. input(id: 'release-image-with-tag', message: 'release image with tag?', submitter: 'project-admin,project-admin1')
    3. ···

    备注

    在 KubeSphere 3.1 中，如果不指定审核员，那么能够运行流水线的帐户也能够继续或终止该流水线。流水线创建者、在该工程中具有 admin 角色的帐户或者您指定的帐户也有权限继续或终止流水线。

步骤 6：检查流水线状态

  1. 在运行状态中，您可以查看流水线的运行状态。请注意，流水线在刚创建后将继续初始化几分钟。示例流水线有八个阶段，它们已在 Jenkinsfile-online 中单独定义。

    查看流水线日志-1

  2. 点击右上角的查看日志来查看流水线运行日志。您可以看到流水线的动态日志输出，包括可能导致流水线无法运行的错误。对于每个阶段，您都可以点击该阶段来查看其日志，而且可以将日志下载到本地计算机进行进一步分析。

    查看流水线日志-2

步骤 7：验证结果

  1. 流水线成功运行后，点击代码质量通过 SonarQube 查看结果，如下所示。

    SonarQube 结果详情

    SonarQube 结果详情

  2. 按照 Jenkinsfile 中的定义，通过流水线构建的 Docker 镜像也已成功推送到 Docker Hub。在 Docker Hub 中，您会看到带有标签 v0.0.2 的镜像，该标签在流水线运行之前已指定。

    Docker Hub 镜像

  3. 同时，GitHub 中已生成一个新标签和一个新发布版本。

    GitHub 结果

  4. 示例应用程序将部署到 kubesphere-sample-dev 和 kubesphere-sample-prod，并创建相应的部署和服务。转到这两个项目，预期结果如下所示：

    环境URL命名空间部署服务
    Developmenthttp://{$NodeIP}:{$30861}kubesphere-sample-devks-sample-devks-sample-dev
    Productionhttp://{$NodeIP}:{$30961}kubesphere-sample-prodks-sampleks-sample

    部署

    流水线部署

    服务

    流水线服务

    备注

    您可能需要在您的安全组中放行该端口，以便通过 URL 访问应用程序。

步骤 8：访问示例服务

  1. 以 admin 身份登录 KubeSphere 并使用工具箱中的 Web Kubectl 访问该服务。转到 kubesphere-sample-dev 项目，然后在应用负载下的服务中选择 ks-sample-dev。Endpoint 可用于访问该服务。

    查看示例应用

    访问 Endpoint

  2. 在右下角的工具箱中使用 Web Kubectl 执行以下命令：

    1. curl 10.233.120.230:8080

  3. 预期输出:

    1. Really appreciate your star, that's the power of our life.

    备注

    使用 curl 访问 Endpoint，或者访问 {$Virtual IP}:{$Port} 或 {$Node IP}:{$NodePort}。

  4. 同样地，您可以在项目 kubesphere-sample-prod 中测试服务，您将看到相同的输出结果。

    1. $ curl 10.233.120.236:8080
    2. Really appreciate your star, that's the power of our life.