注意

本文档适用于 Ceph 的开发版本。

报告文档错误

使用 Teuthology 工作流程的集成测试

基础设施

组件

1. ceph-ci: 主 Ceph 仓库的克隆，用于触发 Jenkins Ceph 构建以进行开发。

2. Ceph Jenkins: 负责触发构建，将包上传到 Chacra，并将有关构建的更新推送到 Shaman。

3. Shaman: 用于检查构建状态的 UI 界面。在其后端，它是一个用于查询和存储构建信息的 REST API。

4. Chacra: 上传软件包的服务。上传到此处的二进制文件可以被任何人下载和使用。

5. Teuthology CLI: 开发人员可以使用各种 Teuthology 命令来调度和管理测试运行。

6. Teuthology: 此组件负责将测试作业推送到 Beanstalk 队列和 Paddles。它还从队列中获取作业并运行测试。

7. Beanstalk queue: 一个包含所有排队作业的优先级队列。开发人员通常不需要与其交互。

8. Paddles: 一个存储所有测试运行信息的后端服务。开发人员通常不需要与其交互。

9. Pulpito: 一个 UI 界面（用于存储在 Paddles 中的信息），允许开发人员查看有关其调度测试的详细信息，包括状态和结果。

10. Testnodes: 用于运行测试的各种机器集群。开发人员通常将测试调度到 smithi 机器上运行，这些机器是用于 Teuthology 集成测试的专用测试节点。

每个 Teuthology 测试运行包含多个测试作业。每个作业都在一个与其他作业隔离的环境中运行，位于不同的测试节点集合上。

工作流程概述

要测试 Ceph 中的更改，首先将包含更改的分支推送到 ceph-ci 仓库。这将自动触发 Jenkins 进程来构建 Ceph 二进制文件 - 构建状态可以在 Shaman 上观察到。这些构建的软件包将上传到 Chacra。

要针对此新构建调度 Teuthology 集成测试，您需要访问 Sepia 实验室。获得访问权限后，登录到 Teuthology 机器并完成运行 Teuthology 命令所需的一次性 Teuthology 初始设置。设置完成后，使用 teuthology-suite 命令调度 Teuthology 运行。在此命令中，使用 -c <ceph-ci branch name> 选项指定您的构建。您的测试结果可以在 Pulpito 上观察到。登录到 开发人员演练场机器 以查看 Teuthology 运行的存档日志。

本文档的其余部分将详细解释这些步骤

1. 获取二进制文件 - 构建 Ceph。

2. 调度测试运行

   1. 关于测试套件。

   2. 触发 Teuthology 测试。

   3. 测试 QA 更改（无需重新构建二进制文件）。

   4. 过滤测试。

3. 查看测试结果

   1. Pulpito 仪表板。

   2. Teuthology 存档（查看日志）。

4. 终止测试。

5. 重新运行测试。

获取二进制文件 - 构建 Ceph

在您可以使用 teuthology 运行集成测试之前，必须为您的分支构建 Ceph 二进制文件。按照以下步骤构建 Ceph 二进制文件

1. 将分支推送到 ceph-ci 仓库。这将触发在 Jenkins CI 上构建二进制文件的过程。

2. 为确保构建过程已启动，请确认分支名称已出现在 Shaman 上的“最新可用构建”列表中。启动构建过程后不久，测试基础设施会将其他名称相似的构建添加到“最新可用构建”列表中。这些新构建的名称将包含各种 Linux 发行版的名称，并将用于针对这些 Linux 发行版测试您的构建。

3. 等待软件包构建并上传到 Chacra，并等待提供软件包的仓库创建完成。 Shaman 上“最新可用构建”列表中分支名称的条目将变为绿色，表示软件包已上传到 Chacra 并表示已创建其仓库。等待每个条目都变为绿色。这通常需要两到三个小时，具体取决于机器的可用性。

   特定构建的 Chacra URL 可以从 Chacra 站点 查询。

注意

要推送到 ceph-ci 的分支可以是任何分支。该分支不必是 PR 分支。

注意

如果您打算推送 master 或任何其他标准分支，请事先检查 Shaman，因为它可能已经完成了构建。

推送到 ceph-ci 仓库

按照以下步骤推送到 ceph-ci 仓库。推送后，将自动调度新构建。

1. 将 ceph-ci 仓库添加为本地 Ceph 仓库克隆的远程仓库

   git remote add ceph-ci git@github.com:ceph/ceph-ci.git
   
   $ git remote -v
   origin   git@github.com:ceph/ceph.git (fetch)
   origin   git@github.com:ceph/ceph.git (push)
   ceph-ci  git@github.com:ceph/ceph-ci.git (fetch)
   ceph-ci  git@github.com:ceph/ceph-ci.git (push)
   

2. 通过运行以下形式的命令将您的分支上推

   $ git push ceph-ci wip-yourname-feature-x
   

命名 ceph-ci 分支

在将分支推送到 ceph-ci 之前，在分支名称前加上您的姓名。例如，名为 feature-x 的分支应命名为 wip-$yourname-feature-x，其中 $yourname 被替换为您的姓名。用您的姓名标识您的分支使其在 Shaman 和 Pulpito 上易于查找。

如果您使用的是稳定分支（quincy、pacific 等），请在您的 ceph-ci 分支名称中包含该稳定分支的名称。例如，feature-x PR 分支应命名为 wip-feature-x-nautilus。这不仅仅是一个约定。这确保了您的分支在正确的环境中构建。

当您不再需要 ceph-ci 上的分支时，请将其删除。如果您已登录 GitHub，您可以在此处找到 ceph-ci 上的所有分支：https://github.com/ceph/ceph-ci/branches。

注意

您可以选择仅触发 CentOS 9.Stream 构建（排除 ubuntu 等其他发行版），方法是在 ceph-ci 分支名称末尾添加“centos9-only”。例如，wip-$yourname-feature-centos9-only。当您不需要其他发行版的二进制文件时，这有助于加快构建速度并节省资源。

调度测试运行

关于测试套件

集成测试被组织成“套件”，这些套件在 Ceph 仓库的 qa/suites 子目录中定义。这些测试套件可以使用 teuthology-suite 命令运行。

有关可用集成测试套件的列表，请参阅 套件清单。

有关如何定义这些测试套件的更多详细信息，请参阅 集成测试介绍页面。

触发 Teuthology 测试

为分支构建 Ceph 二进制文件后，您可以使用 teuthology 运行测试。此过程解释了如何使用 teuthology 运行测试。

1. 登录 teuthology 机器

   ssh <username>@teuthology.front.sepia.ceph.com
   

   这需要 Sepia 实验室访问权限。要请求 Sepia 实验室访问权限，请参阅：https://ceph.github.io/sepia/adding_users/。

2. 对于初始设置，请按照 teuthology 安装指南 为 teuthology 机器上的用户设置 teuthology。这将使您能够运行 teuthology 命令。

3. 运行 teuthology-suite 命令

   teuthology-suite -v \
   -m smithi \
   -c wip-devname-feature-x \
   -s fs \
   -p 110 \
   --filter "cephfs-shell" \
   -e foo@gmail.com
   

   上面命令中的选项定义如下

   选项	含义
   -v	详细
   -m	机器名称
   -c	推送到 ceph-ci 上的分支名称
   -s	测试套件名称
   -p	数字越高，作业优先级越低
   --filter	过滤给定套件中的测试。传递给此过滤器的参数指定您要运行的测试
   -e <email>	当测试完成或超时时，向指定地址发送电子邮件。也可以在 ~/.teuthology.yaml 中指定为 ‘results_email’

   注意

   上面命令中出现的优先级数字是一个占位符。不要在您自己的测试中使用它。有关推荐值的信息，请参阅 测试优先级。

   注意

   不要在没有优先级数字的情况下发出命令。默认值是 1000，这个值太大了，你的作业不太可能运行。

   运行 teuthology-suite --help 以阅读这些选项和其他可用选项的描述。

4. 等待测试运行。 teuthology-suite 会打印一个指向 Pulpito 的链接，可以在其中查看测试结果。

--dry-run 选项允许您演示运行 teuthology-suite 命令，而无需实际调度 teuthology 测试。这有助于检查命令将调度多少个作业以及哪些作业。

其他常用的/有用的选项是 -d（或 --distro）、--distro-version、--filter-out、--timeout、flavor、--rerun、--limit（用于限制作业数量）、-N（用于作业运行次数）和 --subset（用于减少触发的测试数量）。运行 teuthology-suite --help 以阅读这些选项和其他选项的描述。

测试 QA 更改（无需重新构建二进制文件）

如果您仅在 qa/ 目录中进行更改，则无需在重新运行测试之前重新构建二进制文件。如果您仅在 qa/ 中进行更改，则可以使用为 ceph-ci 分支构建的二进制文件重新运行测试。您只需确保告诉 teuthology-suite 命令使用单独的分支运行测试即可。

如果您仅在 qa/ 中进行更改（https://github.com/ceph/ceph/tree/master/qa），则无需重新构建二进制文件。您可以使用为 master 和其他稳定分支定期构建的现有二进制文件，并针对它们运行您的测试更改。通过向 teuthology-suite 命令传递两个额外的参数来测试包含 qa 更改的分支：（1）--suite-repo，指定您的 ceph 仓库，和（2）--suite-branch，指定您的分支名称。

例如，如果您想在测试 branch-x（其 ceph-ci 分支为 wip-username-branch-x）之后在 qa/ 中进行更改，请运行以下命令

teuthology-suite -v \
 -m smithi \
 -c wip-username-branch-x \
 -s fs \
 -p 50 \
 --filter cephfs-shell

然后进行本地修改，更新 PR 分支，并从您的 PR 分支触发测试，如下所示

teuthology-suite -v \
 -m smithi \
 -c wip-username-branch-x \
 -s fs -p 50 \
 --filter cephfs-shell \
 --suite-repo https://github.com/$username/ceph \
 --suite-branch branch-x

您可以通过查看 teuthology 作业开始时打印的作业配置中键 suite_branch、suite_repo 和 suite_sha1 的值来验证测试是否使用此分支运行。

注意

如果您进行的更改不在 qa/ 目录中，则必须遵循触发构建、等待构建完成、然后触发测试并等待测试结果的标准过程。

过滤测试

测试套件包含许多 yaml 文件的组合，这可能导致为套件调度大量作业。因此，过滤器可以帮助减少作业数量或调度套件中的特定作业。

用于过滤测试的关键字可以在 Ceph 仓库的 qa/suites/<suite-name>/<subsuite-name>/tasks 中找到，并可以用作 --filter 的参数。该目录中的每个 YAML 文件都可以触发测试；使用不带文件扩展名的文件名作为 --filter 的参数会触发这些测试。

例如，在 测试 QA 更改 部分的上述命令中，指定了 cephfs-shell。这之所以有效，是因为 qa/suites/fs/basic_functional/tasks/ 中有一个名为 cephfs-shell.yaml 的文件。

如果文件名没有表明它触发了哪种测试，请搜索文件内容中的 modules 属性。对于 cephfs-shell.yaml，modules 属性是 tasks.cephfs.test_cephfs_shell。这意味着它触发了 qa/tasks/cephfs/test_cephfs_shell.py 中的所有测试。

阅读有关如何 按描述过滤测试 的更多信息。

查看测试结果

Pulpito 仪表板

调度 teuthology 作业后，可以在 https://pulpito.ceph.com/ 上查看测试运行的状态和结果。

Teuthology 存档

测试运行完成后，可以通过单击与您的测试关联的 Pulpito 运行页面上的作业 ID 来获取作业日志。下载日志然后查看它比在互联网浏览器中查看更方便，因为这些日志的大小很容易达到 1 GB。也可以 ssh 登录到 开发人员演练场机器 并访问以下路径

/teuthology/<run-name>/<job-id>/teuthology.log

例如：对于上面的测试 ID，路径是

/teuthology/teuthology-2019-12-10_05:00:03-smoke-master-testing-basic-smithi/4588482/teuthology.log

此方法可以比通过浏览器更快地查看日志。

要查看 ceph 日志（cephadm、ceph monitors、ceph-mgr 等）或系统日志，请从浏览器上的作业 teuthology 日志 url 中删除 teuthology.log，然后导航到 remote/<machine>/log/。系统日志可以在 remote/<machine>/syslog/ 中找到。同样，这些日志可以在开发人员演练场机器上找到 /teuthology/<test-id>/<job-id>/remote/<machine>/。

包含用于调试目的的其他一些文件

• unit_test_summary.yaml: 提供所有单元测试失败的摘要。当作业的 YAML 文件中使用 unit_test_scan 配置选项时（可选）生成。

• valgrind.yaml: 总结可能发生的任何 Valgrind 错误。

注意

为了更方便地访问存档，/a/ 已符号链接到 /teuthology/。例如，要访问上一个示例，我们可以使用如下内容

/a/teuthology-2019-12-10_05:00:03-smoke-master-testing-basic-smithi/4588482/teuthology.log

终止测试

teuthology-kill 可用于终止意外运行数小时的作业，或者当开发人员希望在测试完成前终止测试时。

这是终止作业的命令

teuthology-kill -p  -r teuthology-2019-12-10_05:00:03-smoke-master-testing-basic-smithi -m smithi -o scheduled_teuthology@teuthology

传递给 -r 的参数是运行名称。在您触发的测试的 Pulpito 页面链接中可以轻松找到它。例如，对于上面的测试 ID，链接是 - http://pulpito.front.sepia.ceph.com/teuthology-2019-12-10_05:00:03-smoke-master-testing-basic-smithi/

重新运行测试

teuthology-suite 命令有一个 -r（或 --rerun）选项，允许您重新运行测试。当您的测试失败或最终死亡时，这很方便。 --rerun 选项将 teuthology 运行的名称作为参数。可以与 -r 一起传递选项 -R（或 --rerun-statuses）来选择应从运行中拾取哪种测试。例如，您可以仅重新运行上一次运行中最终死亡的那些测试。下面是一个实际示例

teuthology-suite -v \
 -m smithi \
 -c wip-rishabh-fs-test_cephfs_shell-fix \
 -p 50 \
 --r teuthology-2019-12-10_05:00:03-smoke-master-testing-basic-smithi \
 -R fail,dead,queued \
 -e $CEPH_QA_MAIL

以下是本节中引入的新选项的定义

选项	含义
-r, --rerun	尝试重新调度运行，仅选择其状态由 --rerun-status 提及的作业。
-R, --rerun-statuses	与 --rerun 一起使用的逗号分隔状态列表。支持的状态：'dead'、'fail'、'pass'、'queued'、'running' 和 'waiting'。默认值：'fail,dead'

由 Ceph 基金会为您呈现

Ceph 文档是由非营利性 Ceph 基金会 资助和托管的社区资源。如果您希望支持这项工作和我们的其他努力，请考虑 立即加入。