注意

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

报告文档错误

使用 cephadm 进行开发

有几种方法可以使用 cephadm 进行开发。具体使用哪种方法取决于您要完成的任务。

vstart --cephadm

• 使用 vstart 启动一个集群，并配置 cephadm

• 使用 cephadm 管理任何额外的守护进程

• 需要编译的 ceph 二进制文件

在这种情况下，mon 和 manager 至少以通常的 vstart 方式运行，不受 cephadm 管理。但是 cephadm 已启用并且已添加本地主机，因此您可以部署额外的守护进程或添加额外的主机。

这非常适合开发 cephadm 本身，因为任何 mgr/cephadm 或 cephadm/cephadm 代码更改都可以通过使用 ceph mgr fail x 来重启 ceph-mgr 以应用。（当 mgr (重新)启动时，它会将 cephadm/cephadm 脚本加载到内存中。）

MON=1 MGR=1 OSD=0 MDS=0 ../src/vstart.sh -d -n -x --cephadm

• ~/.ssh/id_dsa[.pub] 用作集群密钥。假设此密钥已授权用于 ssh，无需密码即可连接到 root@`hostname`。

• cephadm 不会尝试管理由 vstart.sh 启动的任何守护进程（环境变量中的任何非零数字）。未为 mon 或 mgr 定义服务规范。

• 您会看到来自 cephadm 的有关“stray daemons”（游离守护进程）的健康警告——这是因为 vstart 启动的守护进程不受 cephadm 控制。

• 默认镜像是 quay.io/ceph-ci/ceph:main，但您可以通过传递 -o container_image=... 或 ceph config set global container_image ... 来更改它。

cstart 和 cpatch

cstart.sh 脚本将使用 cephadm 启动一个集群，并将 conf 和 keyring 放入您的构建目录中，以便 bin/ceph ... CLI 可以工作（就像 vstart 一样）。ckill.sh 脚本将关闭它。

• 一个唯一但稳定的 fsid 存储在 fsid 中（在构建目录中）。

• mon 端口是随机的，就像 vstart 一样。

• 容器镜像是 quay.io/ceph-ci/ceph:$tag，其中 $tag 是 fsid 的前 8 个字符。

• 如果您第一次运行 cstart 时容器镜像尚不存在，则会使用 cpatch 构建它。

这里有几个优点

• 该集群是一个“正常”的 cephadm 集群，看起来和行为都像用户的集群一样。相比之下，vstart 和 teuthology 集群在细微（和不那么细微）方面往往是特殊的（例如，打开 lockdep）。

启动测试集群

sudo ../src/cstart.sh

输出的最后一行将是您可以剪切+粘贴以更新容器镜像的行。例如

sudo ../src/script/cpatch -t quay.io/ceph-ci/ceph:8f509f4e

默认情况下，cpatch 会将本地构建目录中所有它能想到的东西都修补到容器镜像中。但是，如果您正在处理系统的特定部分，则可以通过进行较小的更改来加快 cpatch 的运行速度。例如

sudo ../src/script/cpatch -t quay.io/ceph-ci/ceph:8f509f4e --py

将更新 mgr 模块（减去 dashboard）。或者

sudo ../src/script/cpatch -t quay.io/ceph-ci/ceph:8f509f4e --core

将执行大多数二进制文件和库。传递 -h 给 cpatch 以获取所有选项。

更新容器后，您可以通过以下方式重启守护进程来刷新/重新启动它们

sudo systemctl restart ceph-`cat fsid`.target

完成后，您可以使用以下命令关闭集群

sudo ../src/ckill.sh   # or,
sudo ../src/cephadm/cephadm rm-cluster --force --fsid `cat fsid`

cephadm bootstrap --shared_ceph_folder

Cephadm 也可以直接使用，无需编译 ceph 二进制文件。

像这样运行 cephadm

sudo ./cephadm bootstrap --mon-ip 127.0.0.1 \
  --ssh-private-key /home/<user>/.ssh/id_rsa \
  --skip-mon-network \
  --skip-monitoring-stack --single-host-defaults \
  --skip-dashboard \
  --shared_ceph_folder /home/<user>/path/to/ceph/

• ~/.ssh/id_rsa 用作集群密钥。假设此密钥已授权用于 ssh，无需密码即可连接到 root@`hostname`。

在 pybind/mgr/ 目录中所做的源代码更改需要重新启动守护进程才能生效。

Kcli：一种虚拟化管理工具，使协调器开发变得容易

Kcli 用于与现有虚拟化提供商（libvirt、KubeVirt、oVirt、OpenStack、VMware vSphere、GCP 和 AWS）交互，并轻松地从云镜像部署和自定义虚拟机。

它允许您使用首选配置（内存、CPU、磁盘）和操作系统风格设置包含多个虚拟机的环境。

主要优点：

• 快速。通常您可以在不到 5 分钟内准备好一个全新的 Ceph 集群来调试和开发协调器功能。

• “接近生产”的实验室。生成的实验室接近 QE 实验室甚至生产中的“真实”集群。这使得在几乎“真实”的环境中测试“真实事物”变得容易。

• 安全且隔离。不依赖于您在机器中安装的东西。并且虚拟机与您的环境隔离。

• 易于工作的“开发”环境。对于“未编译”的软件部分，例如任何 mgr 模块。这是一个允许您交互式测试更改的环境。

安装：

kcli 安装中有完整的文档，但我们建议使用容器镜像方法。

需要做的事情

• 1. 查看要求并安装/配置满足要求所需的一切。

• 2. 获取 kcli 镜像并为执行 kcli 命令创建一个别名

  # podman pull quay.io/karmab/kcli
  # alias kcli='podman run --net host -it --rm --security-opt label=disable -v $HOME/.ssh:/root/.ssh -v $HOME/.kcli:/root/.kcli -v /var/lib/libvirt/images:/var/lib/libvirt/images -v /var/run/libvirt:/var/run/libvirt -v $PWD:/workdir -v /var/tmp:/ignitiondir quay.io/karmab/kcli'
  

注意

这假设 /var/lib/libvirt/images 是您的默认 libvirt 池……如果使用不同的路径，请进行调整

注意

一旦您使用 kcli 工具创建并使用了不同的实验室，我们建议您坚持使用给定的容器标签并更新您的 kcli 别名。为什么？kcli 使用滚动发布模型，坚持使用特定的容器标签将提高整体稳定性。我们想要的是整体稳定性。

测试您的 kcli 安装：

请参阅 kcli 基本使用工作流

创建 Ceph 实验室集群

为了简化此任务，我们将使用一个“plan”（计划）。

“plan”是一个文件，您可以在其中定义一组具有不同设置的虚拟机。您可以定义硬件参数（cpu、内存、磁盘等）、操作系统，它还允许您自动化安装和配置您想要的任何软件。

有一个包含可用于不同目的的计划集合的仓库。我们有预定义的计划来使用 Ceph ansible 或 cephadm 安装 Ceph 集群，所以让我们使用 cephadm 创建我们的第一个 Ceph 集群

# kcli create plan -u https://github.com/karmab/kcli-plans/blob/master/ceph/ceph_cluster.yml

这将使用 URL 指向的计划文件创建一组三个虚拟机。几分钟后，让我们检查集群

• 查看创建的虚拟机

  # kcli list vms
  

• 进入引导节点

  # kcli ssh ceph-node-00
  

• 查看已安装的 ceph 集群

  [centos@ceph-node-00 ~]$ sudo -i
  [root@ceph-node-00 ~]# cephadm version
  [root@ceph-node-00 ~]# cephadm shell
  [ceph: root@ceph-node-00 /]# ceph orch host ls
  

创建一个 Ceph 集群以方便开发 mgr 模块（协调器和 Dashboard）

cephadm kcli 计划（和 cephadm）已为此做好准备。

此方法背后的想法是用主机机器中的源代码文件夹替换每个 ceph 守护进程中的几个 python mgr 文件夹。这个“技巧”将允许您在任何协调器或 dashboard 模块中进行更改并立即测试它们。（只需要禁用/启用 mgr 模块）

因此，为了创建用于开发目的的 ceph 集群，您必须使用相同的 cephadm 计划，但要使用指向您的 Ceph 源代码文件夹的新参数

# kcli create plan -u https://github.com/karmab/kcli-plans/blob/master/ceph/ceph_cluster.yml -P ceph_dev_folder=/home/mycodefolder/ceph

Ceph Dashboard 开发

如果您之前没有生成前端 bundle，Ceph dashboard 模块将不会被加载。

目前，为了正确加载 Ceph Dashboard 模块并应用前端更改，您必须在笔记本电脑上运行“ng build”

# Start local frontend build with watcher (in background):
sudo dnf install -y nodejs
cd <path-to-your-ceph-repo>
cd src/pybind/mgr/dashboard/frontend
sudo chown -R <your-user>:root dist node_modules
NG_CLI_ANALYTICS=false npm ci
npm run build -- --deleteOutputPath=false --watch &

保存更改后，前端 bundle 将再次构建。完成后，您将看到

"Localized bundle generation complete."

然后您可以重新加载 Dashboard 浏览器选项卡。

Cephadm box 容器（Podman inside Podman）开发环境

由于 kcli 启动时间较长，我们创建了一种使用 Podman inside Podman 更快的替代方案。这种方法也有其缺点，因为我们必须使用回环设备模拟 osd 的创建和设备的添加。

Cephadm 的 box 环境设置简单。设置要求您获取 Ceph 和我们称为 box 所需的 Podman 镜像。box 是 Podman 容器的第一层，可以是 seed 或 host。seed 是主 box，它包含 Cephadm，您可以在其中引导集群。另一方面，您有设置了 SSH 服务器的主机，因此您可以将这些主机添加到集群中。由 Cephadm 管理的第二层，位于 seed box 内部，需要 Ceph 镜像。

警告

这个开发环境仍处于实验阶段，可能会出现意外行为。请查看路线图和已知问题部分以了解开发进度。

要求

• podman-compose

• lvm

设置

要设置 Cephadm 的 box，请运行

cd src/cephadm/box
./box.py -v cluster setup

注意

建议使用 verbose (-v) 运行 box，因为它会显示正在运行的 shell 命令的输出。

获取所有需要的镜像后，我们可以创建一个没有 OSD 和主机的简单集群

./box.py -v cluster start

如果您想部署具有更多 OSD 和主机的集群：

# 默认 3 个 osd 和 3 个主机 sudo box -v cluster start --extended # 明确更改主机和 osd 的数量 sudo box -v cluster start --extended --osds 5 --hosts 5

警告

OSD 仍不受 box implementation with Podman 支持。正在开发中。

如果没有 extended 选项，明确添加更多主机或 OSD 不会改变集群的状态。

注意

即使未调用 cluster setup，cluster start 也会尝试设置。

注意

OSD 是用回环设备创建的，因此，需要 sudo 来创建能够容纳 OSD 的回环设备。

注意

每个 osd 将需要 5GiB 的空间。

引导集群后，您可以进入 seed box，在其中您将能够运行 Cephadm 命令

./box.py -v cluster bash
[root@8d52a7860245] cephadm --help
[root@8d52a7860245] cephadm shell
...

如果您想导航到 dashboard，请在浏览器中输入 https://:8443。

您还可以使用以下命令找到每个 box 容器的主机名和 IP

./box.py cluster list

您将看到类似

IP               Name            Hostname
172.30.0.2       box_hosts_1     6283b7b51d91
172.30.0.3       box_hosts_3     3dcf7f1b25a4
172.30.0.4       box_seed_1      8d52a7860245
172.30.0.5       box_hosts_2     c3c7b3273bf1

要删除集群并清理，请运行

./box.py cluster down

如果您只想清理创建的最后一个集群，请运行

./box.py cluster cleanup

要检查所有可用命令，请运行

./box.py --help

如果您想使用 Docker 运行 box，您可以。您必须指定要使用的引擎，例如

./box.py -v --engine docker cluster list

使用 Docker，像 bootstrap 和 osd creation 这样的命令应该使用 sudo 调用，因为它需要权限才能在 VG 和 LV 上创建 osd

sudo ./box.py -v --engine docker cluster start --expanded

警告

使用 Docker 作为 box 引擎是危险的，因为在某些情况下 Xorg 会话会被终止。

已知问题

• 如果您在 Cephadm 中遇到权限问题，因为它无法推断 keyring 和配置，请像此示例一样运行 cephadm

  cephadm shell --config /etc/ceph/ceph.conf --keyring /etc/ceph/ceph.kerying
  

• Docker 容器以 --privileged 标志运行，这已被发现会导致某些计算机注销。

• 如果未禁用 SELinux，您可能会看到意外行为。例如：如果并非所有 Ceph repo 文件权限都设置为您的用户，它可能会在 podman-compose 启动时失败。

• 如果运行命令失败，因为它找不到容器，您可以通过运行带有 -v 标志显示的相同 podman-compose .. up 命令进行调试。

路线图

• 使用 ceph-volume raw 创建 osd。

• 使 ceph-volume 能够将回环设备标记为库存中有效的块设备。

• 使 box 准备好运行 dashboard CI 测试（包括集群扩展）。

关于 CLI 处理程序中网络调用的说明

执行任何 cephadm CLI 命令（如 ceph orch ls）将阻塞 MGR 中的 mon 命令处理程序线程，从而阻止任何并发 CLI 调用。请注意，按下 ^C 不会解决这种情况，因为*只有*客户端会被中止，而不会中止协调器管理器模块本身中命令的执行。这意味着，cephadm 将完全无响应，直到 CLI 处理程序的执行完全完成。请注意，即使是 ceph orch ps 在另一个处理程序执行时也不会响应。

这意味着我们应该对远程主机进行非常少的同步调用。作为指导原则，cephadm 在 CLI 处理程序中最多应进行 O(1) 网络调用。其他所有内容都应在其他线程中异步完成，例如 serve()。

关于代码中使用的不同变量的说明

• service_type 是在 ServiceSpec 中定义的类似 mon、mgr、alertmanager 等的东西

• service_id 是服务的名称。有些服务没有名称。

• service_name 是 <service_type>.<service_id>

• daemon_type 与 service_type 相同，但 ingress 除外，它具有 haproxy 和 keepalived 守护进程类型。

• daemon_id 通常是 <service_id>.<hostname>.<random-string>。（OSD 等情况并非如此。OSD 总是称为 OSD.N）

• daemon_name 是 <daemon_type>.<daemon_id>

编译 cephadm

最近版本的 cephadm 基于 Python Zip Application 支持，并从 ceph 树中的 Python 源代码文件“编译”。要创建自己的 cephadm“二进制文件”副本，请使用位于 Ceph 树中 src/cephadm/build.py 的脚本。命令形式应为 ./src/cephadm/build.py [output]。

您可以传递一组有限的版本元数据值，这些值将存储在编译后的 cepadm 中。这些选项可以通过 --set-version-var 或 -S 选项传递给构建脚本。这些值的形式应为 KEY=VALUE，有效键包括：* CEPH_GIT_VER * CEPH_GIT_NICE_VER * CEPH_RELEASE * CEPH_RELEASE_NAME * CEPH_RELEASE_TYPE

示例：./src/cephadm/build.py -SCEPH_GIT_VER=$(git rev-parse HEAD) -SCEPH_GIT_NICE_VER=$(git describe) /tmp/cephadm

通常这些值会由其他更高级别的构建工具（例如 cmake）传递给 build.py。

编译后的二进制版本可能包含 zipapp 中的精选依赖项集。用于获取捆绑依赖项的工具可以是 Python 的 pip、本地安装的 RPM，或者可以禁用捆绑依赖项。要选择捆绑依赖项的模式，请使用 --bundled-dependencies 或 -B 选项，其值为 pip、rpm 或 none。

编译后的 cephadm zipapp 文件保留了有关其构建方式的元数据。可以通过运行 cephadm version --verbose 来显示此信息。该命令将发出一个 JSON 格式的对象，其中显示版本元数据（如果可用）、构建脚本生成的捆绑依赖项列表（如果启用了捆绑依赖项），以及 zipapp 顶级内容的摘要。示例

$ ./cephadm version --verbose
{
  "name": "cephadm",
  "ceph_git_nice_ver": "18.0.0-6867-g6a1df2d0b01",
  "ceph_git_ver": "6a1df2d0b01da581bfef3357940e1e88d5ce70ce",
  "ceph_release_name": "reef",
  "ceph_release_type": "dev",
  "bundled_packages": [
    {
      "name": "Jinja2",
      "version": "3.1.2",
      "package_source": "pip",
      "requirements_entry": "Jinja2 == 3.1.2"
    },
    {
      "name": "MarkupSafe",
      "version": "2.1.3",
      "package_source": "pip",
      "requirements_entry": "MarkupSafe == 2.1.3"
    }
  ],
  "zip_root_entries": [
    "Jinja2-3.1.2-py3.9.egg-info",
    "MarkupSafe-2.1.3-py3.9.egg-info",
    "__main__.py",
    "__main__.pyc",
    "_cephadmmeta",
    "cephadmlib",
    "jinja2",
    "markupsafe"
  ]
}

由 Ceph 基金会为您呈现

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