Ceph cephadm 命令行工具完全指南本地主机的容器化编排管理【免费下载链接】cephCeph is a distributed object, block, and file storage platform项目地址: https://gitcode.com/gh_mirrors/ce/cephcephadm 是 Ceph 分布式存储系统中用于管理本地主机的命令行工具是 cephadm 编排器orchestrator在单台节点上的执行入口。它提供了一套面向单机的命令用来检查、部署、调试和清理本机上与集群相关的各类守护进程容器。读完本文你将掌握 cephadm 的全部全局选项与 20 余个子命令的用法能够在引导集群、排查守护进程、迁移旧部署、配置自定义镜像仓库等真实场景中直接上手操作并结合仓库源码理解每个命令背后的实现机制。cephadm 是什么定位与适用场景cephadm 是一个 Python 3 实现的命令行工具其核心实现位于仓库 src/cephadm/cephadm.py单文件、约六千余行配套的常量定义与子模块位于 src/cephadm/cephadmlib。它面向 cephadm orchestrator 管理本地主机主要用途包括调查某个特定守护进程的状态如容器是否在运行、版本是多少修改当前主机的状态如部署、移除守护进程操作 systemd 单元进入容器执行调试命令、查看日志。需要特别说明的是cephadm并非要求部署在所有主机上但当你需要调查某个守护进程时它是最直接的工具。集群层面的编排操作如ceph orch apply通常由 Manager 模块通过 SSH 在远端主机上调用 cephadm 完成这与本文聚焦的本地单机管理视角相互补充。全局命令行语法Synopsiscephadm 的完整调用形式如下全局选项位于子命令之前cephadm [-h] [--image IMAGE] [--docker] [--data-dir DATA_DIR] [--log-dir LOG_DIR] [--logrotate-dir LOGROTATE_DIR] [--unit-dir UNIT_DIR] [--verbose] [--timeout TIMEOUT] [--retry RETRY] [--no-container-init] {version,pull,inspect-image,ls,list-networks,list-rdma,adopt,rm-daemon,rm-cluster,remove-file,deploy-file,run,shell,enter,ceph-volume,unit,logs,bootstrap,deploy,check-host,prepare-host,prepare-host-sudo-hardening,setup-ssh-user,add-repo,rm-repo,install,list-images,update-osd-service} ...每个子命令又有自己的参数例如cephadm pull cephadm --image IMAGE_NAME inspect-image cephadm ls [-h] [--no-detail] [--legacy-dir LEGACY_DIR] cephadm list-networks cephadm list-rdma cephadm bootstrap [-h] [--config CONFIG] [--mon-id MON_ID] ... cephadm deploy --name NAME --fsid FSID [--config CONFIG] ... cephadm shell [--fsid FSID] [--name NAME] [--config CONFIG] [--keyring KEYRING] --mount [MOUNT ...] [--env ENV] [--] [command ...] cephadm unit [--fsid FSID] --name NAME command cephadm logs [--fsid FSID] --name NAME [command ...] cephadm registry-login [--registry-url URL] [--registry-username USER] [--registry-password PASS] [--registry-json FILE] [--fsid FSID]全局选项Options下表汇总了作用于所有子命令的全局选项括号中为文档声明的默认值选项作用默认值--image IMAGE指定容器镜像无可通过环境变量CEPHADM_IMAGE设置--docker使用 docker 而非 podman 作为容器引擎False--data-dir DATA_DIR守护进程数据的基目录/var/lib/ceph--log-dir LOG_DIR守护进程日志的基目录/var/log/ceph--logrotate-dir LOGROTATE_DIRlogrotate 配置文件所在目录/etc/logrotate.d--unit-dir UNIT_DIRsystemd 单元文件的基目录/etc/systemd/system--verbose, -v输出 debug 级别的日志False--timeout TIMEOUT命令超时时间秒无--retry RETRY最大重试次数10--no-container-init不以--init方式运行 podman/docker 容器False这些默认值在源码中有对应定义。从 src/cephadm/cephadmlib/constants.py 可以看到DATA_DIR /var/lib/ceph、LOG_DIR /var/log/ceph、LOGROTATE_DIR /etc/logrotate.d、UNIT_DIR /etc/systemd/system、CEPH_DEFAULT_CONF /etc/ceph/ceph.conf且目录权限掩码被设置为DATA_DIR_MODE 0o700、LOG_DIR_MODE 0o770这解释了守护进程数据目录权限收紧仅属主可读写而日志目录允许组访问的设计。另外CONTAINER_INIT True表明默认情况下容器会以 PID 1 init 进程启动这也是--no-container-init存在的原因。集群引导bootstrapbootstrap是使用 cephadm 部署新集群的起点命令。它在本地主机上引导出一个全新集群部署一个 Monitor 和一个 Manager随后自动在该主机上部署监控栈Prometheus、Grafana、Alertmanager、Node Exporter并调用ceph orch host add $(hostname)把本机登记为集群主机。参数详解参数说明--config CONFIG, -c CONFIG要并入的ceph.conf文件--mon-id MON_IDmon 的 ID默认取本地主机名--mon-addrv MON_ADDRVmon 地址族如[v2:localipaddr:3300,v1:localipaddr:6789]--mon-net MON_NETmon 网络CIDR如192.168.1.0/24--mon-ip MON_IPmon IP 地址--mgr-id MGR_IDmgr 的 ID默认随机生成--fsid FSID集群 FSID--log-to-file配置集群将日志写入传统日志文件--single-host-defaults配置集群运行在单台主机上--output-dir OUTPUT_DIR写入 config、keyring、公钥文件的目录--output-keyring OUTPUT_KEYRING新集群 admin 与 mon 密钥环文件的写入位置--output-config OUTPUT_CONFIG连接新集群的 conf 文件写入位置--output-pub-ssh-key OUTPUT_PUB_SSH_KEY集群公钥的写入位置--skip-ssh跳过在本地主机上设置 SSH 密钥--initial-dashboard-user USERDashboard 初始用户--initial-dashboard-password PASSDashboard 初始用户密码--ssl-dashboard-port PORT通过 SSL 连接 Dashboard 的端口--dashboard-key KEYDashboard 私钥--dashboard-crt CRTDashboard 证书--ssh-config SSH_CONFIGSSH 配置文件--ssh-private-key KEYSSH 私钥--ssh-public-key KEYSSH 公钥--ssh-user USERSSH 到集群主机所用的用户非 root 用户需要免密 sudo--skip-mon-network基于 bootstrap 的 mon IP 设置 mon 的 public_network--skip-dashboard不启用 Ceph Dashboard--dashboard-password-noupdate停止强制修改 Dashboard 初始密码--no-minimize-config不吸收assimilate和最小化配置文件--skip-ping-check不校验 mon IP 是否可 ping 通--skip-pull引导前不拉取最新镜像--skip-firewalld不配置 firewalld--allow-overwrite允许覆盖已有的--output-*配置文件/密钥环/SSH 文件--allow-fqdn-hostname允许使用包含.的完全限定主机名--skip-prepare-host不执行主机准备步骤--orphan-initial-daemons将 mon、mgr 服务设为 unmanaged且不创建 crash 服务--skip-monitoring-stack不自动部署监控栈prometheus、grafana、alertmanager、node-exporter--apply-spec APPLY_SPECbootstrap 后应用集群 spec复制 SSH 密钥、添加主机并应用服务--registry-url URL要登录的自定义镜像仓库 URL如 docker.io、quay.io--registry-username USER自定义仓库的登录用户名--registry-password PASS自定义仓库的登录密码--registry-json JSON含仓库登录信息的 JSON 文件格式见 registry-login 小节源码视角bootstrap 的执行流程从 src/cephadm/cephadm.py 的command_bootstrap实现可以看出引导过程的典型步骤若未显式指定输出文件则把ceph.conf、ceph.keyring、公钥分别写到--output-dir下的默认文件名若目标文件已存在且未传--allow-overwrite直接报错拒绝覆盖校验 SSH 私钥/公钥/签名证书参数的配对关系私钥必须与公钥或 CA 签名证书二选一搭配校验 FSID 合法性并在--data-dir/fsid已存在时抛出ClusterAlreadyExists避免误建重复集群未指定 FSID 时会自动生成非 root 的--ssh-user会先做 SSH 连通性检查除非--skip-prepare-host否则先执行主机准备command_prepare_host检查主机名是否含.FQDN默认拒绝、需显式--allow-fqdn-hostname默认先拉取镜像_pull_image再通过容器运行ceph --version校验镜像与 cephadm 自身的 release 是否匹配从镜像中提取 ceph 用户的 uid/gid生成 mon/mgr/admin 密钥与 bootstrap 密钥环创建初始 monmap随后按序部署 mon、mgr 等守护进程。典型的引导命令示例sudo cephadm bootstrap --mon-ip 192.168.1.10 --initial-dashboard-user admin \ --initial-dashboard-password my-secret --ssh-user cephadm镜像管理pull / inspect-image / list-images / registry-loginpull拉取 Ceph 容器镜像到本地cephadm pull默认使用--image指定的镜像或CEPHADM_IMAGE环境变量从仓库常量看镜像默认值定义于 src/cephadm/cephadmlib/constants.py 的DEFAULT_IMAGE。inspect-image检查本地 Ceph 容器镜像的元数据。从 Reef 版本起必须用--image显式指定要检查的镜像cephadm --image IMAGE_NAME inspect-imagelist-images以 ini 格式列出所有服务的默认容器镜像。输出可以被修改换成自定义镜像后通过--config参数传给bootstrap从而定制整个集群各服务使用的镜像版本。registry-login向 cephadm 提供需要认证的镜像仓库的登录信息URL、用户名、密码cephadm 会尝试把调用主机登录到该仓库cephadm registry-login --registry-url [REGISTRY_URL] --registry-username [USERNAME] --registry-password [PASSWORD]也可以使用 JSON 文件传递登录信息单仓库格式如下{ url: REGISTRY_URL, username: REGISTRY_USERNAME, password: REGISTRY_PASSWORD }需要同时登录多个仓库时使用如下格式{ registry_credentials: [ { url: REGISTRY_URL1, username: REGISTRY_USERNAME1, password: REGISTRY_PASSWORD1 }, { url: REGISTRY_URL2, username: REGISTRY_USERNAME2, password: REGISTRY_PASSWORD2 } ] }然后通过--registry-json提交cephadm registry-login --registry-json [JSON FILE]参数--registry-url仓库 URL如 docker.io、quay.io、--registry-username、--registry-password、--registry-json、--fsid。该命令与bootstrap的--registry-*参数互补引导时既可直接传 URL/用户名/密码也可用同格式的 JSON 文件。主机检查与准备check-host检查主机配置是否适合承载 Ceph 集群cephadm check-host [--expect-hostname EXPECT_HOSTNAME]--expect-hostname用于校验主机名是否与期望值一致。prepare-host为 cephadm 的使用准备主机--expect-hostname可设定期望的主机名。prepare-host-sudo-hardening为 sudo 加固准备主机授权 SSH 密钥、安装/升级 cephadm 包并配置受限的 sudoers 权限cephadm prepare-host-sudo-hardening --ssh-user cephadm --ssh-pub-key key该命令依次执行三步为指定用户授权提供的 SSH 公钥安装或升级 cephadm 包到与集群版本一致该包内含cephadm_invoker.py其实现位于 src/cephadm/cephadm_invoker.py为cephadm_invoker.py配置受限的 sudoers 权限。参数--ssh-user用于密钥授权的 SSH 用户默认 root、--ssh-pub-key要授权的公钥、--cephadm-version指定要安装的 cephadm 版本。setup-ssh-user配置带免密 sudo 和 SSH 密钥授权的 SSH 用户cephadm setup-ssh-user --ssh-user cephadm --ssh-pub-key public_key执行步骤校验用户已存在于系统中为该用户设置免密 sudoroot 用户跳过把 SSH 公钥加入用户的authorized_keys。该命令会被ceph cephadm set-user自动调用用于在集群所有主机上配置 SSH 用户。参数--ssh-user必填、--ssh-pub-key必填。list-networks / list-rdmalist-networks列出主机的 IP 网络list-rdma列出 RDMA 设备及其对应的 netdev 接口。这两个命令在排查网络规划、确认 mon 监听地址或 RDMA 网卡归属时非常实用。守护进程管理ls / deploy / run / unit / logs / enterls列出当前主机上 cephadm 已知的守护进程实例输出为 JSON 数组$ cephadm ls [ { style: cephadm:v1, name: mgr.storage-14b-1.ysubfo, fsid: 5110cb22-8332-11ea-9148-0894ef7e8bdc, enabled: true, state: running, container_id: 8562de72370a3836473ecfff8a22c9ccdd99815386b4692a2b30924fb5493c44, container_image_name: quay.io/ceph/ceph:v20, container_image_id: bc83a388465f0568dab4501fb7684398dca8b50ca12a342a57f21815721723c2, version: 20.2.3, started: 2020-04-21T01:16:41.831456, created: 2020-04-21T01:16:41.775024, deployed: 2020-04-21T01:16:41.415021, configured: 2020-04-21T01:16:41.775024 }, ...每个条目包含部署风格style、守护进程名type.id格式、FSID、systemd 是否启用enabled、运行状态、容器 ID、镜像名与镜像 ID、Ceph 版本以及 started/created/deployed/configured 四个时间戳可用于判断守护进程的生命周期。参数--no-detail不包含守护进程状态、--legacy-dirlegacy 守护进程数据的基目录。deploy在本地主机上部署一个守护进程通常由 orchestrator CLI 在后台调用cephadm shell -- ceph orch apply type ...参数--name NAME守护进程名type.id必填--fsid FSID集群 FSID必填--config CONFIG, -c CONFIG新守护进程的配置文件--config-json CONFIG_JSONJSON 格式的附加配置信息--keyring KEYRING新守护进程的密钥环--key KEY新守护进程的密钥--osd-fsid OSD_FSID创建 OSD 容器时的 OSD UUID--skip-firewalld不配置 firewalld--tcp-ports TCP_PORTS需要在主机防火墙中放行的 TCP 端口列表--reconfig重新配置之前已部署的守护进程--allow-ptrace允许守护进程容器启用SYS_PTRACE。run在前台、以容器方式运行一个 Ceph 守护进程。参数--name NAME必填、--fsid FSID必填。适合手动前台调试某个守护进程的启动过程。unit对守护进程对应的 systemd 单元执行操作cephadm unit --fsid fsid --name name start位置参数command是 systemd 命令start、stop、restart、enable、disable等必填参数为--fsid与--name。从源码看systemd 单元默认安装在--unit-dir即/etc/systemd/system与 src/cephadm/cephadmlib/systemd.py 中的封装逻辑对应。logs打印守护进程容器的 journald 日志等价于对 systemd 单元执行journalctlcephadm logs --name mgr.myhost.ysubfo等价于journalctl -u mgr.myhost.ysubfo可以在--之后追加 journalctl 的参数cephadm logs --name mgr.myhost.ysubfo -- -n 20 # 只看最后 20 行 cephadm logs --name mgr.myhost.ysubfo -- -f # 持续跟踪日志位置参数为可选的 journal 参数参数--fsid、--name必填。enter进入一个正在运行的守护进程容器得到交互式 shellcephadm enter --name mgr.myhost.ysubfo位置参数command为容器内要执行的命令参数--fsid、--name必填。从 src/cephadm/cephadm.py 的command_enter实现看它会根据守护进程名推断 FSID 与容器身份然后以交互模式-i进入容器。与shell相比enter严格绑定某个已运行的守护进程容器而shell是启动一个独立的临时容器。交互式容器shell / ceph-volumeshell启动一个交互式 shellcephadm shell或者在容器内执行单条命令后退出cephadm shell -- ceph orch ls位置参数command可选参数--fsid FSID集群 FSID--name NAME, -n NAME守护进程名type.id--config CONFIG, -c CONFIG传入容器的ceph.conf--keyring KEYRING, -k KEYRING传入容器的ceph.keyring--mount MOUNT, -m MOUNT把文件或目录挂载到容器内的/mnt下--env ENV, -e ENV设置容器环境变量。shell是排查集群问题最常用的入口。从 src/cephadm/cephadm.py 的command_shell实现可以看到若干值得注意的细节容器以privileged特权方式运行便于执行网络、存储相关的调试操作未指定--name时使用shell类型的一套精简挂载指定--name时会按该守护进程的 identity 挂载对应数据目录默认会把宿主机的/var/lib/ceph只读挂载到容器内的/srv/cephro,zz标记适配 SELinux--mount 源:目标支持显式指定容器内目标路径不指定目标时默认挂到/mnt/文件名未传入命令时默认进入bash并设置自定义PS1提示符CUSTOM_PS1且把/var/lib/ceph/fsid/home作为容器内 root 的 home 目录首次进入时从/etc/skel复制 bash 配置。ceph-volume在容器内运行 ceph-volume 命令例如cephadm ceph-volume inventory位置参数command为 ceph-volume 子命令必填参数--fsid、--config-json含配置与client.bootstrap-osd密钥的 JSON 文件、--config/-cceph.conf文件、--keyring/-k传入容器的ceph.keyring。crape-volume 的完整用法可参考仓库中的 ceph-volume(8) 手册。OSD 部署场景下--config-json通常由 orchestrator 生成内含 OSD 引导所需的配置与 bootstrap-osd 密钥环。文件操作remove-file / deploy-file这两个命令用于编排器在主机间安全地传递配置文件。remove-file删除本地主机上的一个普通文件路径不存在时静默忽略cephadm remove-file --fsid fsid --path /absolute/path参数--fsid、--path要删除文件的绝对路径必填。deploy-file向本地主机写入或替换一个文件。整个文件内容从标准输入按原始字节读取不做任何编码或换行转换这对保持配置文件的字节级一致性很重要cat /path/to/config | cephadm deploy-file --path /etc/ceph/ceph.conf参数--fsid、--path目标绝对路径必填、--mode八进制文件权限如644或0644、--uid属主数字 UID必须与--gid同时给出、--gid属组数字 GID必须与--uid同时给出。该命令的实现在 src/cephadm/cephadm.py 的command_deploy_file从源码结构看它要求 uid/gid 成对出现以避免只改属主或只改属组造成权限不一致。守护进程/集群清理rm-daemon / rm-clusterrm-daemon移除某个具体的守护进程实例cephadm rm-daemon --name mgr.myhost.ysubfo --fsid fsid参数--nametype.id必填、--fsid必填、--force即使可能销毁有价值数据也继续、--force-delete-data直接删除有价值数据而非先做备份。从 src/cephadm/cephadm.py 的command_rm_daemon实现可以推断默认情况下 cephadm 会把待删除守护进程的数据备份到本地目录而--force-delete-data会跳过备份直接删除因此日常操作应优先使用不带该参数的版本。rm-cluster移除某个集群的所有守护进程cephadm rm-cluster --fsid fsid参数--fsid必填、--force即使可能销毁有价值数据也继续。包与仓库管理add-repo / rm-repo / installadd-repo把 Ceph 软件仓库追加到本地包仓库配置中cephadm add-repo --release octopus # 使用命名发布版最新版本 cephadm add-repo --version 17.2.5 # 使用特定上游版本 x.y.z参数--release RELEASE使用某个命名发布版的最新版本如octopus--version VERSION使用特定上游版本x.y.z--dev DEV使用来自指定 git 分支或 tag 的 bleeding-edge 构建--dev-commit DEV_COMMIT使用来自指定 git commit 的 bleeding-edge 构建--gpg-url GPG_URL指定备用的 GPG 公钥地址--repo-url REPO_URL指定备用的仓库地址。rm-repo移除包仓库配置cephadm rm-repoinstall安装 Ceph 软件包cephadm install ceph-common cephadm位置参数packages为要安装的包名列表可多个。旧部署迁移adoptadopt用于把由其他部署工具部署的守护进程迁移到 cephadm 管理之下cephadm adopt --name mon.a --style legacy --cluster cluster-name参数--name NAME, -n NAME守护进程名type.id必填--style STYLE部署风格如legacy必填--cluster CLUSTER集群名--legacy-dir LEGACY_DIRlegacy 守护进程数据的基目录--config-json CONFIG_JSONJSON 格式的附加配置信息--skip-firewalld不配置 firewalld--skip-pull采纳前不拉取最新镜像。从源码看adopt 针对不同守护进程类型有专门的处理逻辑command_adopt_ceph、command_adopt_prometheus、command_adopt_grafana、command_adopt_alertmanager等位于 src/cephadm/cephadm.py覆盖 ceph 系守护进程与监控栈组件的迁移场景。配置查找顺序重要adopt 在启动 shell 时按以下顺序查找配置只使用最先找到的值用户显式指定的配置文件路径-c/--config选项由--name指定的守护进程配置文件/var/lib/ceph/fsid/daemon-name/config/var/lib/ceph/fsid/config/ceph.conf若存在mon 守护进程的配置文件/var/lib/ceph/fsid/mon.mon-id/config若存在最后回退到默认文件/etc/ceph/ceph.conf。这套查找逻辑与 src/cephadm/cephadmlib/context_getters.py 中get_config_and_keyring等函数的设计一致优先使用守护进程专属配置其次使用集群级配置最终回退到传统/etc/ceph目录从而兼容从 legacy 部署迁移过来的场景。其他命令速查命令作用version显示 cephadm 自身版本update-osd-service为指定 OSD 更新其 OSD 服务--fsid、--osd-ids逗号分隔的 OSD ID必填、--service-nameOSD 服务名必填可用性与延伸阅读cephadm 是 Ceph大规模可扩展的开源分布式存储系统的组成部分。若要继续深入建议阅读仓库中的以下资料cephadm 实现源码全部子命令的入口函数、容器封装CephContainer、SSH 与 systemd 交互逻辑cephadmlib 子模块常量、容器引擎封装、systemd 单元生成、防火墙firewalld配置等基础组件cephadm 编排器文档cephadm orchestrator 的完整使用指南集群部署、主机管理、升级、运维ceph-volume(8) 手册OSD 容器内卷管理命令的参考。通过本文的全局选项、命令参数与源码对应关系你可以在任意 Ceph 节点上快速完成查状态ls/logs— 进容器shell/enter— 改配置deploy-file/remove-file— 清清理rm-daemon/rm-cluster的完整排查闭环为基于 cephadm 的集群运维打下坚实基础。【免费下载链接】cephCeph is a distributed object, block, and file storage platform项目地址: https://gitcode.com/gh_mirrors/ce/ceph创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Ceph cephadm 命令行工具完全指南：本地主机的容器化编排管理
Ceph cephadm 命令行工具完全指南本地主机的容器化编排管理【免费下载链接】cephCeph is a distributed object, block, and file storage platform项目地址: https://gitcode.com/gh_mirrors/ce/cephcephadm 是 Ceph 分布式存储系统中用于管理本地主机的命令行工具是 cephadm 编排器orchestrator在单台节点上的执行入口。它提供了一套面向单机的命令用来检查、部署、调试和清理本机上与集群相关的各类守护进程容器。读完本文你将掌握 cephadm 的全部全局选项与 20 余个子命令的用法能够在引导集群、排查守护进程、迁移旧部署、配置自定义镜像仓库等真实场景中直接上手操作并结合仓库源码理解每个命令背后的实现机制。cephadm 是什么定位与适用场景cephadm 是一个 Python 3 实现的命令行工具其核心实现位于仓库 src/cephadm/cephadm.py单文件、约六千余行配套的常量定义与子模块位于 src/cephadm/cephadmlib。它面向 cephadm orchestrator 管理本地主机主要用途包括调查某个特定守护进程的状态如容器是否在运行、版本是多少修改当前主机的状态如部署、移除守护进程操作 systemd 单元进入容器执行调试命令、查看日志。需要特别说明的是cephadm并非要求部署在所有主机上但当你需要调查某个守护进程时它是最直接的工具。集群层面的编排操作如ceph orch apply通常由 Manager 模块通过 SSH 在远端主机上调用 cephadm 完成这与本文聚焦的本地单机管理视角相互补充。全局命令行语法Synopsiscephadm 的完整调用形式如下全局选项位于子命令之前cephadm [-h] [--image IMAGE] [--docker] [--data-dir DATA_DIR] [--log-dir LOG_DIR] [--logrotate-dir LOGROTATE_DIR] [--unit-dir UNIT_DIR] [--verbose] [--timeout TIMEOUT] [--retry RETRY] [--no-container-init] {version,pull,inspect-image,ls,list-networks,list-rdma,adopt,rm-daemon,rm-cluster,remove-file,deploy-file,run,shell,enter,ceph-volume,unit,logs,bootstrap,deploy,check-host,prepare-host,prepare-host-sudo-hardening,setup-ssh-user,add-repo,rm-repo,install,list-images,update-osd-service} ...每个子命令又有自己的参数例如cephadm pull cephadm --image IMAGE_NAME inspect-image cephadm ls [-h] [--no-detail] [--legacy-dir LEGACY_DIR] cephadm list-networks cephadm list-rdma cephadm bootstrap [-h] [--config CONFIG] [--mon-id MON_ID] ... cephadm deploy --name NAME --fsid FSID [--config CONFIG] ... cephadm shell [--fsid FSID] [--name NAME] [--config CONFIG] [--keyring KEYRING] --mount [MOUNT ...] [--env ENV] [--] [command ...] cephadm unit [--fsid FSID] --name NAME command cephadm logs [--fsid FSID] --name NAME [command ...] cephadm registry-login [--registry-url URL] [--registry-username USER] [--registry-password PASS] [--registry-json FILE] [--fsid FSID]全局选项Options下表汇总了作用于所有子命令的全局选项括号中为文档声明的默认值选项作用默认值--image IMAGE指定容器镜像无可通过环境变量CEPHADM_IMAGE设置--docker使用 docker 而非 podman 作为容器引擎False--data-dir DATA_DIR守护进程数据的基目录/var/lib/ceph--log-dir LOG_DIR守护进程日志的基目录/var/log/ceph--logrotate-dir LOGROTATE_DIRlogrotate 配置文件所在目录/etc/logrotate.d--unit-dir UNIT_DIRsystemd 单元文件的基目录/etc/systemd/system--verbose, -v输出 debug 级别的日志False--timeout TIMEOUT命令超时时间秒无--retry RETRY最大重试次数10--no-container-init不以--init方式运行 podman/docker 容器False这些默认值在源码中有对应定义。从 src/cephadm/cephadmlib/constants.py 可以看到DATA_DIR /var/lib/ceph、LOG_DIR /var/log/ceph、LOGROTATE_DIR /etc/logrotate.d、UNIT_DIR /etc/systemd/system、CEPH_DEFAULT_CONF /etc/ceph/ceph.conf且目录权限掩码被设置为DATA_DIR_MODE 0o700、LOG_DIR_MODE 0o770这解释了守护进程数据目录权限收紧仅属主可读写而日志目录允许组访问的设计。另外CONTAINER_INIT True表明默认情况下容器会以 PID 1 init 进程启动这也是--no-container-init存在的原因。集群引导bootstrapbootstrap是使用 cephadm 部署新集群的起点命令。它在本地主机上引导出一个全新集群部署一个 Monitor 和一个 Manager随后自动在该主机上部署监控栈Prometheus、Grafana、Alertmanager、Node Exporter并调用ceph orch host add $(hostname)把本机登记为集群主机。参数详解参数说明--config CONFIG, -c CONFIG要并入的ceph.conf文件--mon-id MON_IDmon 的 ID默认取本地主机名--mon-addrv MON_ADDRVmon 地址族如[v2:localipaddr:3300,v1:localipaddr:6789]--mon-net MON_NETmon 网络CIDR如192.168.1.0/24--mon-ip MON_IPmon IP 地址--mgr-id MGR_IDmgr 的 ID默认随机生成--fsid FSID集群 FSID--log-to-file配置集群将日志写入传统日志文件--single-host-defaults配置集群运行在单台主机上--output-dir OUTPUT_DIR写入 config、keyring、公钥文件的目录--output-keyring OUTPUT_KEYRING新集群 admin 与 mon 密钥环文件的写入位置--output-config OUTPUT_CONFIG连接新集群的 conf 文件写入位置--output-pub-ssh-key OUTPUT_PUB_SSH_KEY集群公钥的写入位置--skip-ssh跳过在本地主机上设置 SSH 密钥--initial-dashboard-user USERDashboard 初始用户--initial-dashboard-password PASSDashboard 初始用户密码--ssl-dashboard-port PORT通过 SSL 连接 Dashboard 的端口--dashboard-key KEYDashboard 私钥--dashboard-crt CRTDashboard 证书--ssh-config SSH_CONFIGSSH 配置文件--ssh-private-key KEYSSH 私钥--ssh-public-key KEYSSH 公钥--ssh-user USERSSH 到集群主机所用的用户非 root 用户需要免密 sudo--skip-mon-network基于 bootstrap 的 mon IP 设置 mon 的 public_network--skip-dashboard不启用 Ceph Dashboard--dashboard-password-noupdate停止强制修改 Dashboard 初始密码--no-minimize-config不吸收assimilate和最小化配置文件--skip-ping-check不校验 mon IP 是否可 ping 通--skip-pull引导前不拉取最新镜像--skip-firewalld不配置 firewalld--allow-overwrite允许覆盖已有的--output-*配置文件/密钥环/SSH 文件--allow-fqdn-hostname允许使用包含.的完全限定主机名--skip-prepare-host不执行主机准备步骤--orphan-initial-daemons将 mon、mgr 服务设为 unmanaged且不创建 crash 服务--skip-monitoring-stack不自动部署监控栈prometheus、grafana、alertmanager、node-exporter--apply-spec APPLY_SPECbootstrap 后应用集群 spec复制 SSH 密钥、添加主机并应用服务--registry-url URL要登录的自定义镜像仓库 URL如 docker.io、quay.io--registry-username USER自定义仓库的登录用户名--registry-password PASS自定义仓库的登录密码--registry-json JSON含仓库登录信息的 JSON 文件格式见 registry-login 小节源码视角bootstrap 的执行流程从 src/cephadm/cephadm.py 的command_bootstrap实现可以看出引导过程的典型步骤若未显式指定输出文件则把ceph.conf、ceph.keyring、公钥分别写到--output-dir下的默认文件名若目标文件已存在且未传--allow-overwrite直接报错拒绝覆盖校验 SSH 私钥/公钥/签名证书参数的配对关系私钥必须与公钥或 CA 签名证书二选一搭配校验 FSID 合法性并在--data-dir/fsid已存在时抛出ClusterAlreadyExists避免误建重复集群未指定 FSID 时会自动生成非 root 的--ssh-user会先做 SSH 连通性检查除非--skip-prepare-host否则先执行主机准备command_prepare_host检查主机名是否含.FQDN默认拒绝、需显式--allow-fqdn-hostname默认先拉取镜像_pull_image再通过容器运行ceph --version校验镜像与 cephadm 自身的 release 是否匹配从镜像中提取 ceph 用户的 uid/gid生成 mon/mgr/admin 密钥与 bootstrap 密钥环创建初始 monmap随后按序部署 mon、mgr 等守护进程。典型的引导命令示例sudo cephadm bootstrap --mon-ip 192.168.1.10 --initial-dashboard-user admin \ --initial-dashboard-password my-secret --ssh-user cephadm镜像管理pull / inspect-image / list-images / registry-loginpull拉取 Ceph 容器镜像到本地cephadm pull默认使用--image指定的镜像或CEPHADM_IMAGE环境变量从仓库常量看镜像默认值定义于 src/cephadm/cephadmlib/constants.py 的DEFAULT_IMAGE。inspect-image检查本地 Ceph 容器镜像的元数据。从 Reef 版本起必须用--image显式指定要检查的镜像cephadm --image IMAGE_NAME inspect-imagelist-images以 ini 格式列出所有服务的默认容器镜像。输出可以被修改换成自定义镜像后通过--config参数传给bootstrap从而定制整个集群各服务使用的镜像版本。registry-login向 cephadm 提供需要认证的镜像仓库的登录信息URL、用户名、密码cephadm 会尝试把调用主机登录到该仓库cephadm registry-login --registry-url [REGISTRY_URL] --registry-username [USERNAME] --registry-password [PASSWORD]也可以使用 JSON 文件传递登录信息单仓库格式如下{ url: REGISTRY_URL, username: REGISTRY_USERNAME, password: REGISTRY_PASSWORD }需要同时登录多个仓库时使用如下格式{ registry_credentials: [ { url: REGISTRY_URL1, username: REGISTRY_USERNAME1, password: REGISTRY_PASSWORD1 }, { url: REGISTRY_URL2, username: REGISTRY_USERNAME2, password: REGISTRY_PASSWORD2 } ] }然后通过--registry-json提交cephadm registry-login --registry-json [JSON FILE]参数--registry-url仓库 URL如 docker.io、quay.io、--registry-username、--registry-password、--registry-json、--fsid。该命令与bootstrap的--registry-*参数互补引导时既可直接传 URL/用户名/密码也可用同格式的 JSON 文件。主机检查与准备check-host检查主机配置是否适合承载 Ceph 集群cephadm check-host [--expect-hostname EXPECT_HOSTNAME]--expect-hostname用于校验主机名是否与期望值一致。prepare-host为 cephadm 的使用准备主机--expect-hostname可设定期望的主机名。prepare-host-sudo-hardening为 sudo 加固准备主机授权 SSH 密钥、安装/升级 cephadm 包并配置受限的 sudoers 权限cephadm prepare-host-sudo-hardening --ssh-user cephadm --ssh-pub-key key该命令依次执行三步为指定用户授权提供的 SSH 公钥安装或升级 cephadm 包到与集群版本一致该包内含cephadm_invoker.py其实现位于 src/cephadm/cephadm_invoker.py为cephadm_invoker.py配置受限的 sudoers 权限。参数--ssh-user用于密钥授权的 SSH 用户默认 root、--ssh-pub-key要授权的公钥、--cephadm-version指定要安装的 cephadm 版本。setup-ssh-user配置带免密 sudo 和 SSH 密钥授权的 SSH 用户cephadm setup-ssh-user --ssh-user cephadm --ssh-pub-key public_key执行步骤校验用户已存在于系统中为该用户设置免密 sudoroot 用户跳过把 SSH 公钥加入用户的authorized_keys。该命令会被ceph cephadm set-user自动调用用于在集群所有主机上配置 SSH 用户。参数--ssh-user必填、--ssh-pub-key必填。list-networks / list-rdmalist-networks列出主机的 IP 网络list-rdma列出 RDMA 设备及其对应的 netdev 接口。这两个命令在排查网络规划、确认 mon 监听地址或 RDMA 网卡归属时非常实用。守护进程管理ls / deploy / run / unit / logs / enterls列出当前主机上 cephadm 已知的守护进程实例输出为 JSON 数组$ cephadm ls [ { style: cephadm:v1, name: mgr.storage-14b-1.ysubfo, fsid: 5110cb22-8332-11ea-9148-0894ef7e8bdc, enabled: true, state: running, container_id: 8562de72370a3836473ecfff8a22c9ccdd99815386b4692a2b30924fb5493c44, container_image_name: quay.io/ceph/ceph:v20, container_image_id: bc83a388465f0568dab4501fb7684398dca8b50ca12a342a57f21815721723c2, version: 20.2.3, started: 2020-04-21T01:16:41.831456, created: 2020-04-21T01:16:41.775024, deployed: 2020-04-21T01:16:41.415021, configured: 2020-04-21T01:16:41.775024 }, ...每个条目包含部署风格style、守护进程名type.id格式、FSID、systemd 是否启用enabled、运行状态、容器 ID、镜像名与镜像 ID、Ceph 版本以及 started/created/deployed/configured 四个时间戳可用于判断守护进程的生命周期。参数--no-detail不包含守护进程状态、--legacy-dirlegacy 守护进程数据的基目录。deploy在本地主机上部署一个守护进程通常由 orchestrator CLI 在后台调用cephadm shell -- ceph orch apply type ...参数--name NAME守护进程名type.id必填--fsid FSID集群 FSID必填--config CONFIG, -c CONFIG新守护进程的配置文件--config-json CONFIG_JSONJSON 格式的附加配置信息--keyring KEYRING新守护进程的密钥环--key KEY新守护进程的密钥--osd-fsid OSD_FSID创建 OSD 容器时的 OSD UUID--skip-firewalld不配置 firewalld--tcp-ports TCP_PORTS需要在主机防火墙中放行的 TCP 端口列表--reconfig重新配置之前已部署的守护进程--allow-ptrace允许守护进程容器启用SYS_PTRACE。run在前台、以容器方式运行一个 Ceph 守护进程。参数--name NAME必填、--fsid FSID必填。适合手动前台调试某个守护进程的启动过程。unit对守护进程对应的 systemd 单元执行操作cephadm unit --fsid fsid --name name start位置参数command是 systemd 命令start、stop、restart、enable、disable等必填参数为--fsid与--name。从源码看systemd 单元默认安装在--unit-dir即/etc/systemd/system与 src/cephadm/cephadmlib/systemd.py 中的封装逻辑对应。logs打印守护进程容器的 journald 日志等价于对 systemd 单元执行journalctlcephadm logs --name mgr.myhost.ysubfo等价于journalctl -u mgr.myhost.ysubfo可以在--之后追加 journalctl 的参数cephadm logs --name mgr.myhost.ysubfo -- -n 20 # 只看最后 20 行 cephadm logs --name mgr.myhost.ysubfo -- -f # 持续跟踪日志位置参数为可选的 journal 参数参数--fsid、--name必填。enter进入一个正在运行的守护进程容器得到交互式 shellcephadm enter --name mgr.myhost.ysubfo位置参数command为容器内要执行的命令参数--fsid、--name必填。从 src/cephadm/cephadm.py 的command_enter实现看它会根据守护进程名推断 FSID 与容器身份然后以交互模式-i进入容器。与shell相比enter严格绑定某个已运行的守护进程容器而shell是启动一个独立的临时容器。交互式容器shell / ceph-volumeshell启动一个交互式 shellcephadm shell或者在容器内执行单条命令后退出cephadm shell -- ceph orch ls位置参数command可选参数--fsid FSID集群 FSID--name NAME, -n NAME守护进程名type.id--config CONFIG, -c CONFIG传入容器的ceph.conf--keyring KEYRING, -k KEYRING传入容器的ceph.keyring--mount MOUNT, -m MOUNT把文件或目录挂载到容器内的/mnt下--env ENV, -e ENV设置容器环境变量。shell是排查集群问题最常用的入口。从 src/cephadm/cephadm.py 的command_shell实现可以看到若干值得注意的细节容器以privileged特权方式运行便于执行网络、存储相关的调试操作未指定--name时使用shell类型的一套精简挂载指定--name时会按该守护进程的 identity 挂载对应数据目录默认会把宿主机的/var/lib/ceph只读挂载到容器内的/srv/cephro,zz标记适配 SELinux--mount 源:目标支持显式指定容器内目标路径不指定目标时默认挂到/mnt/文件名未传入命令时默认进入bash并设置自定义PS1提示符CUSTOM_PS1且把/var/lib/ceph/fsid/home作为容器内 root 的 home 目录首次进入时从/etc/skel复制 bash 配置。ceph-volume在容器内运行 ceph-volume 命令例如cephadm ceph-volume inventory位置参数command为 ceph-volume 子命令必填参数--fsid、--config-json含配置与client.bootstrap-osd密钥的 JSON 文件、--config/-cceph.conf文件、--keyring/-k传入容器的ceph.keyring。crape-volume 的完整用法可参考仓库中的 ceph-volume(8) 手册。OSD 部署场景下--config-json通常由 orchestrator 生成内含 OSD 引导所需的配置与 bootstrap-osd 密钥环。文件操作remove-file / deploy-file这两个命令用于编排器在主机间安全地传递配置文件。remove-file删除本地主机上的一个普通文件路径不存在时静默忽略cephadm remove-file --fsid fsid --path /absolute/path参数--fsid、--path要删除文件的绝对路径必填。deploy-file向本地主机写入或替换一个文件。整个文件内容从标准输入按原始字节读取不做任何编码或换行转换这对保持配置文件的字节级一致性很重要cat /path/to/config | cephadm deploy-file --path /etc/ceph/ceph.conf参数--fsid、--path目标绝对路径必填、--mode八进制文件权限如644或0644、--uid属主数字 UID必须与--gid同时给出、--gid属组数字 GID必须与--uid同时给出。该命令的实现在 src/cephadm/cephadm.py 的command_deploy_file从源码结构看它要求 uid/gid 成对出现以避免只改属主或只改属组造成权限不一致。守护进程/集群清理rm-daemon / rm-clusterrm-daemon移除某个具体的守护进程实例cephadm rm-daemon --name mgr.myhost.ysubfo --fsid fsid参数--nametype.id必填、--fsid必填、--force即使可能销毁有价值数据也继续、--force-delete-data直接删除有价值数据而非先做备份。从 src/cephadm/cephadm.py 的command_rm_daemon实现可以推断默认情况下 cephadm 会把待删除守护进程的数据备份到本地目录而--force-delete-data会跳过备份直接删除因此日常操作应优先使用不带该参数的版本。rm-cluster移除某个集群的所有守护进程cephadm rm-cluster --fsid fsid参数--fsid必填、--force即使可能销毁有价值数据也继续。包与仓库管理add-repo / rm-repo / installadd-repo把 Ceph 软件仓库追加到本地包仓库配置中cephadm add-repo --release octopus # 使用命名发布版最新版本 cephadm add-repo --version 17.2.5 # 使用特定上游版本 x.y.z参数--release RELEASE使用某个命名发布版的最新版本如octopus--version VERSION使用特定上游版本x.y.z--dev DEV使用来自指定 git 分支或 tag 的 bleeding-edge 构建--dev-commit DEV_COMMIT使用来自指定 git commit 的 bleeding-edge 构建--gpg-url GPG_URL指定备用的 GPG 公钥地址--repo-url REPO_URL指定备用的仓库地址。rm-repo移除包仓库配置cephadm rm-repoinstall安装 Ceph 软件包cephadm install ceph-common cephadm位置参数packages为要安装的包名列表可多个。旧部署迁移adoptadopt用于把由其他部署工具部署的守护进程迁移到 cephadm 管理之下cephadm adopt --name mon.a --style legacy --cluster cluster-name参数--name NAME, -n NAME守护进程名type.id必填--style STYLE部署风格如legacy必填--cluster CLUSTER集群名--legacy-dir LEGACY_DIRlegacy 守护进程数据的基目录--config-json CONFIG_JSONJSON 格式的附加配置信息--skip-firewalld不配置 firewalld--skip-pull采纳前不拉取最新镜像。从源码看adopt 针对不同守护进程类型有专门的处理逻辑command_adopt_ceph、command_adopt_prometheus、command_adopt_grafana、command_adopt_alertmanager等位于 src/cephadm/cephadm.py覆盖 ceph 系守护进程与监控栈组件的迁移场景。配置查找顺序重要adopt 在启动 shell 时按以下顺序查找配置只使用最先找到的值用户显式指定的配置文件路径-c/--config选项由--name指定的守护进程配置文件/var/lib/ceph/fsid/daemon-name/config/var/lib/ceph/fsid/config/ceph.conf若存在mon 守护进程的配置文件/var/lib/ceph/fsid/mon.mon-id/config若存在最后回退到默认文件/etc/ceph/ceph.conf。这套查找逻辑与 src/cephadm/cephadmlib/context_getters.py 中get_config_and_keyring等函数的设计一致优先使用守护进程专属配置其次使用集群级配置最终回退到传统/etc/ceph目录从而兼容从 legacy 部署迁移过来的场景。其他命令速查命令作用version显示 cephadm 自身版本update-osd-service为指定 OSD 更新其 OSD 服务--fsid、--osd-ids逗号分隔的 OSD ID必填、--service-nameOSD 服务名必填可用性与延伸阅读cephadm 是 Ceph大规模可扩展的开源分布式存储系统的组成部分。若要继续深入建议阅读仓库中的以下资料cephadm 实现源码全部子命令的入口函数、容器封装CephContainer、SSH 与 systemd 交互逻辑cephadmlib 子模块常量、容器引擎封装、systemd 单元生成、防火墙firewalld配置等基础组件cephadm 编排器文档cephadm orchestrator 的完整使用指南集群部署、主机管理、升级、运维ceph-volume(8) 手册OSD 容器内卷管理命令的参考。通过本文的全局选项、命令参数与源码对应关系你可以在任意 Ceph 节点上快速完成查状态ls/logs— 进容器shell/enter— 改配置deploy-file/remove-file— 清清理rm-daemon/rm-cluster的完整排查闭环为基于 cephadm 的集群运维打下坚实基础。【免费下载链接】cephCeph is a distributed object, block, and file storage platform项目地址: https://gitcode.com/gh_mirrors/ce/ceph创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考