Apache Mesos 文档地图:从架构原理到集群运维、容器化与框架开发的完整知识体系

原创2026-10-12 13:49:571,664 阅读
文章标签:云原生

Apache Mesos 文档地图:从架构原理到集群运维、容器化与框架开发的完整知识体系

Apache Mesos 的官方文档以 docs/home.md 为总入口,按“基础原理、构建安装、集群管理、资源管理、安全、容器化、网络、存储、调度与执行器开发、API、社区贡献”等主题组织成一套覆盖全生命周期的技术知识库。本文以这份文档首页为骨架,逐条展开每个主题下的核心文档要旨,并结合当前仓库中的源码与配置印证其实际实现,帮助你建立从“理解架构”到“动手运维”再到“二次开发”的完整检索与学习路径。

本文面向需要部署、运维或基于 Mesos 开发框架的工程师:读完你可以快速定位任意主题的权威文档,并了解其背后的源码实现位置,例如主从架构的 src/master 与 src/slave、容器化实现的 src/slave/containerizer、以及 v1 版本化 API 的 include/mesos/v1。

一、文档体系的组织方式

docs/home.md 是 Apache Mesos 文档的导航首页,采用“主题分区 + 条目链接”的组织形式,全文按功能域划分为:

  • Fundamentals(基础原理):架构、演示材料、版本与支持策略;
  • Build / Installation(构建与安装):编译、二进制包、构建配置、CMake、Windows 支持;
  • Administration(集群管理):运行时配置、高可用、故障恢复、升级降级、日志监控、运维指南等;
  • Resource Management(资源管理):属性与资源、角色、配额、预留、共享资源、超卖;
  • Security(安全):认证、授权、SSL、密钥管理;
  • Containerization(容器化):容器器概览与实现、镜像、GPU、沙箱、Pod 等;
  • Networking(网络):网络概览、CNI、端口映射;
  • Storage(存储):多磁盘、持久卷、CSI 支持;
  • Scheduler and Executor Development(调度与执行器开发):工作负载运行、框架开发指南、任务状态、健康检查、v1 HTTP API;
  • APIs(API 体系):HTTP 端点、客户端库、API 版本、RecordIO、v0/v1 参考;
  • Community(社区与贡献):用户列表、路线图、设计文档、贡献指南、代码风格与评审规范;
  • Books on Mesos:公开出版的 Mesos 书籍。

这种按主题分区的索引设计,让不同角色的读者(构建者、运维者、框架开发者、贡献者)都能以最小成本找到自己的入口。以下各节将按这些分区展开,逐项说明每一篇文档解决什么问题,并给出仓库内的源码/配置佐证。

二、Fundamentals:理解 Mesos 的架构与版本策略

2.1 Mesos 架构总览

Mesos Architecture 是理解整个项目的第一篇文档。它用一幅架构图(docs/images/architecture3.jpg)说明了三大核心组件:

  • master 守护进程:管理每个集群节点上的 agent 守护进程,并以 resource offer(资源邀约) 的形式向框架提供细粒度的资源共享(CPU、内存等)。每个 offer 包含 <agent ID, resource1: amount1, resource2: amount2, ...> 列表;master 根据组织策略(如公平共享或严格优先级)决定“给每个框架多少资源”,并通过模块化架构支持插拔式分配模块。
  • agent 守护进程:运行在每个集群节点上,负责实际启动执行器(executor)与任务。
  • Mesos framework(框架):由 scheduler(调度器) 和 executor(执行器) 两部分组成。调度器向 master 注册以接收 offer,并决定“使用哪些资源”;执行器在 agent 节点上运行框架的任务。

架构文档还给出了一个完整的资源邀约示例(图 docs/images/architecture-example.jpg):Agent 1 向 master 上报 4 CPU 与 4 GB 空闲内存 → master 调用分配策略模块将资源全部邀约给框架 1 → 框架 1 的调度器回复两个任务的资源需求(如 <2 CPUs, 1 GB RAM> 与 <1 CPUs, 2 GB RAM>)→ master 将任务下发给 agent 执行;剩余资源则可能被邀约给框架 2。

Mesos 保持“薄接口”以支持规模扩展和框架独立演进:框架通过 拒绝(reject) 不满足自身约束的 offer 来实现数据本地性等高级诉求,其中“延迟调度(delay scheduling)”策略可取得近乎最优的数据本地性。

仓库佐证:master 的分配器实现位于 src/master/allocator,主从守护进程的主体实现在 src/master/master.cpp 与 src/slave/slave.cpp。

2.2 演示材料与学术论文

2.3 版本发布与 API 兼容性策略

versioning.md 详细定义了 Mesos 1.0 之后的发布节奏与兼容性承诺:

  • 发布节奏:约每 3 个月发布一个 minor 版本(遵循 SemVer,如 1.1、1.2),每个 minor 版本都是稳定版本并推荐用于生产;每个月的补丁版本用于修复 critical issue。任意时刻同时支持 3 个版本(最新版与最近的两个版本)。
  • critical issue 的定义:安全修复、兼容性回归、功能回归、性能回归、第三方集成修复(如 Docker remote API)。
  • 升级:所有稳定版本之间“松散兼容”,master/agent 只要不依赖已废弃特性即可从任意稳定版本 N 直接升级到 M;特性弃用期为 6 个月。
  • API 版本化:HTTP API 使用 /api/vN 前缀(如 master 的 http://localhost:5050/api/v1/scheduler、agent 的 http://localhost:5051/api/v1/executor);API 稳定版本与 Mesos 主版本号对应(v1 API 由 1.0.0、1.4.0 等所有 1.x 版本支持);仅当需要破坏性变更时才提升 API 版本号。
  • API 兼容性判定依据 protobuf 保证:例如“新增 Call 类型、新增可选字段、新增 Event 类型、新增 header 字段”属于向后兼容;而“新增必填字段、重命名/删除字段、重命名/删除现有 Call”属于不兼容变更。

实现细节:版本化 protobuf 与内部 protobuf 解耦——v1 API 的 protobuf 位于 include/mesos/v1(如 include/mesos/v1/scheduler/scheduler.proto),内部未版本化 protobuf 位于 include/mesos/scheduler/scheduler.proto;两者通过 src/internal/evolve.hpp / src/internal/devolve.hpp 转换器互转。从源码结构看,这种“外部版本化 + 内部统一”的设计正是为了支持同一安装同时托管多个 API 版本。

三、Build / Installation:编译安装与构建系统

3.1 从源码构建(Building)

building.md 给出了完整的编译安装流程:

  1. 获取源码:推荐从 Apache 下载最新稳定版 tarball(如 mesos-1.9.0.tar.gz)并解压;高级用户可 git clone 官方仓库。

  2. 系统要求:Mesos 支持 64 位 Linux 与 macOS;构建需要 GCC 4.8.1+ 或 Clang 3.5+;Linux 内核构建期与运行期需 >= 2.6.28,完整进程隔离需 >= 3.10;agent 还支持 Windows(见 windows.md)。

  3. 安装依赖:文档分别给出 Ubuntu 14.04/16.04、macOS、CentOS 6.6/7.1 的依赖安装命令(tar wget git、OpenJDK、autoconf/libtool、build-essential python-dev libcurl4-nss-dev libsasl2-dev maven libapr1-dev libsvn-dev 等)。

  4. 编译(Posix):

    cd mesos
    ./bootstrap            # 仅从 git 仓库构建时需要
    mkdir build && cd build
    ../configure
    make                    # 可加 -j <核数> V=0 加速
    make check              # 运行测试套件
    make install            # 可选
    
  5. 运行示例框架:构建后可启动本地 master/agent 并运行 C++、Java、Python 示例框架,通过 http://127.0.0.1:5050 访问 Mesos Web UI:

    ./bin/mesos-master.sh --ip=127.0.0.1 --work_dir=/var/lib/mesos
    ./bin/mesos-agent.sh --master=127.0.0.1:5050 --work_dir=/var/lib/mesos
    ./src/test-framework --master=127.0.0.1:5050
    ./src/examples/java/test-framework 127.0.0.1:5050
    ./src/examples/python/test-framework 127.0.0.1:5050
    

仓库佐证:示例框架源码就位于 src/examples(C++)与 src/examples/java、src/examples/python;启动脚本模板在 src/deploy。

3.2 二进制包与构建配置

四、Administration:集群运维的完整工具箱

4.1 运行时配置方式

configuration.md 规定了 master/agent 配置的两种统一方式:

  • 命令行参数:--option_name=value,value 既可以是直接值,也可以是 file://path/to/file 指向的文件;
  • 环境变量:MESOS_OPTION_NAME(在选项名前加 MESOS_ 前缀)。

配置查找顺序为“先环境变量、后命令行”。文档还特别强调:mesos-master --help 与 mesos-agent --help 是当前版本支持的全部选项的权威来源。配置选项进一步细分为四类文档:

4.2 高可用(HA)主节点

high-availability.md 讲解如何通过 ZooKeeper 实现多 master 高可用:一个 active leader + 多个 backup,由 ZooKeeper 协调选举与领导者发现。配置要点:

  • master 用 --zk=zk://host1:port1,host2:port2,.../path 启动;
  • agent 用 --master=zk://host1:port1,host2:port2,.../path 启动;
  • 框架调度器使用相同的 zk 路径构造 SchedulerDriver。

此外,可通过任意 master 的 /redirect 端点查询当前 leader;对仅 leader 生效的 HTTP 端点,请求非 leader 时会返回 307 Temporary Redirect(指向 leader)或 503 Service Unavailable。

实现细节(文档也给出了源码定位):src/zookeeper 提供底层 LeaderContender/LeaderDetector 通用选举算法,src/master/contender(contender.cpp/zookeeper.cpp)提供上层的 MasterContender/MasterDetector 适配器;Group 抽象负责 ZooKeeper 组成员注册与监控;断连超时由 --zk_session_timeout 控制。

4.3 Agent 故障恢复与集群升级降级

  • agent-recovery.md:当 mesos-agent 进程退出时,其托管的 executor/task 默认会被关闭;若框架注册时启用了 checkpointing,executor 可重连到新的 agent 进程并继续运行。Agent 会将 SlaveInfo、FrameworkInfo、ExecutorInfo 以及未确认的状态更新等检查点到本地磁盘;重启时校验配置兼容性。相关配置项见 configuration/agent.md:strict(严格恢复模式,默认 true)、reconfiguration_policy(恢复时接受的配置变更类型,默认 equal)等。
  • upgrades.md 与 downgrades.md:分别说明集群升级与降级的具体步骤与注意事项。
  • framework-rate-limiting.md:介绍对框架的消息/请求速率限制,防止单个框架拖垮 master。

4.4 维护、日志、监控与 CLI

五、Resource Management:细粒度资源管理

5.1 属性与资源、角色体系

5.2 配额、预留与权重

  • quota.md:配置 Mesos 为角色提供有保证的资源分配;Quota 相关实现见 src/master/quota.cpp 与 include/mesos/quota。
  • reservation.md:运维人员与框架如何在单个 agent 上为角色预留资源(静态/动态预留)。
  • weights.md:通过权重实现角色间的加权公平共享。
  • oversubscription.md:利用未使用资源执行“尽力而为(best-effort)”任务。该功能自 Mesos 0.23.0 引入,新增 Resource Estimator(资源估算器) 与 QoS Controller(服务质量控制器) 两个 agent 组件:估算器周期性从资源监视器获取 ResourceStatistic 统计以判定可超卖的资源量;agent 在估算变化时上报 master;allocator 将超卖资源标注为 revocable(可回收);只有注册时声明 REVOCABLE_RESOURCES capability 的框架才会收到含可回收资源的 offer。仓库示例见 src/slave/resource_estimators 与 src/slave/qos_controllers。

六、Security:认证、授权、SSL 与密钥

  • authentication.md:认证允许可信实体(框架、agent、运维人员)访问集群,默认关闭。默认认证模块基于 Cyrus SASL 库,默认方法为 CRAM-MD5;实体需提供 credential(principal + secret)。关键配置项:master 的 --<a href="https://link.gitcode.com/i/1615c3019ad2d48fc12a5a5af696abce" target="_blank">no-]authenticate(框架注册认证)、--[no-]authenticate_agents(agent 注册认证)、--[no-]authenticate_http_readonly / --[no-]authenticate_http_readwrite(HTTP 端点认证)、--authenticators(默认 crammd5)、--http_authenticators(默认 basic)、--credentials(凭证文件路径)。认证实现见 [src/authentication/cram_md5 与 src/authentication/http。
  • authorization.md:基于 principal 的授权(ACL);模板示例见 docs/examples/acls_template.json,实现见 src/authorizer 与 include/mesos/authorizer。
  • ssl.md:为 master/agent 之间的 libprocess 通信及 HTTP 端点启用 SSL/TLS 加密。
  • secrets.md:管理 Mesos 内的密钥(如环境变量或文件形式的 secret,供任务使用)。

七、Containerization:容器化体系

7.1 容器器(Containerizer)概览与类型

containerizers.md 说明容器器用于隔离任务、限制资源、控制资源使用并在预打包文件系统镜像中运行软件。Mesos 实现三类容器器,通过 agent 标志 --containerizers 选择:

  • Mesos(默认):--containerizers=mesos,原生容器器,通过可插拔 isolators 提供细粒度操作系统级控制(cgroups/namespaces 等),详见 mesos-containerizer.md;
  • Docker:--containerizers=docker,在 Docker 容器内运行任务,详见 docker-containerizer.md;
  • Composing(组合):--containerizers=mesos,docker(逗号分隔,顺序重要),第一个支持任务容器配置的容器器将被用于启动任务。

实现佐证:容器器代码位于 src/slave/containerizer,其中 composing.cpp、docker.cpp、mesos/ 子目录分别对应上述三类;containerizer-internals.md 讲解内部实现细节(isolator API 流程示意图见 docs/images/containerizer_isolator_api.png)。

7.2 镜像、GPU、沙箱与 Pod

八、Networking:网络模型与 CNI

九、Storage:多磁盘、持久卷与 CSI

  • multiple-disk.md:允许任务使用多个相互隔离的磁盘资源;
  • persistent-volume.md:允许任务访问持久化存储资源;
  • csi.md:Container Storage Interface(CSI) 支持。文档说明:Mesos 1.6+ 支持 CSI 0.2(CSI 0.1 由 1.5 支持)。CSI 的引入是为了解决本地持久卷(无法直接提供块设备、无法选择文件系统)与外部持久卷(绕过 offer 周期、不跟踪资源、无法做配额/预留/公平共享,且基于 Docker Volume Driver Interface)的既有局限,让存储厂商编写“一次编写、多平台可用”的插件。仓库佐证:CSI 全套实现位于 src/csi(含 v0/v1 客户端与卷管理器),CSI protobuf 定义在 include/mesos/csi。

十、Scheduler and Executor Development:框架开发

10.1 运行工作负载与框架开发指南

10.2 v1 Scheduler / Executor HTTP API

scheduler-http-api.md 详细描述了调度器与 master 的通信协议(v1 于 Mesos 0.24.0 引入,1.0 起稳定并成为推荐方式):

  • 调度器可通过两种方式构建:传统 SchedulerDriver C++ 接口,或全新的 HTTP API(无需 C++ 绑定,任何语言用通用 HTTP 库即可,更推荐使用官方客户端库);
  • 交互入口为 master 的 /api/v1/scheduler 端点,接受 JSON 或二进制 Protobuf 编码的 POST 请求;
  • 首个请求必须是 SUBSCRIBE,返回 200 OK 的长连接流式响应(RecordIO 编码),并携带 Mesos-Stream-Id 头;所有后续非 SUBSCRIBE 调用必须携带该 Stream-Id 且使用不同连接;
  • 异步请求返回 202 Accepted,同步请求返回 200 OK;未订阅就调用将得到 403 Forbidden;
  • 请求体示例(FrameworkInfo 含 user、name、roles、capabilities 等字段),订阅成功会收到含 framework_id 与 heartbeat_interval_seconds 的 SUBSCRIBED 事件。

executor-http-api.md 描述执行器与 agent 的 v1 HTTP API(入口 /api/v1/executor)。两个 API 的 protobuf 定义分别在 include/mesos/v1/scheduler/scheduler.proto 与 include/mesos/v1/executor/executor.proto,调用处理实现在 src/sched/sched.cpp 与 src/executor/executor.cpp。示例框架可参考 src/examples/test_http_framework.cpp 与 src/examples/test_http_executor.cpp。

十一、APIs:HTTP 端点、客户端库与 RecordIO

11.1 运维 HTTP API(Operator API)

operator-http-api.md 描述 master 与 agent 的 /api/v1 运维端点。与 Scheduler/Executor API 类似,仅接受 POST(JSON 或 Protobuf):同步请求返回 200 OK,异步请求(如 RESERVE_RESOURCES)返回 202 Accepted,流式事件(SUBSCRIBE)使用 RecordIO 编码。典型调用示例:GET_HEALTH 请求返回 {"type":"GET_HEALTH","get_health":{"healthy":true}}。调用定义见 include/mesos/v1/master/master.proto,处理实现在 src/master/http.cpp。

11.2 HTTP 端点与客户端库

  • 文档首页将 HTTP Endpoints 列为可用 HTTP 端点的索引(注意:当前仓库快照中 docs/endpoints/ 目录未包含在内,端点细节以各 API 文档与 --help 为准);

  • api-client-libraries.md:列出 HTTP API 的官方/第三方客户端库;

  • versioning.md:API 版本化规则(见上文 2.3);

  • recordio.md:HTTP API 流式端点使用的 RecordIO 编码。其 BNF 语法为:

    records         = *record
    record          = record-size LF record-data
    record-size     = 1*DIGIT
    record-data     = record-size(OCTET)
    

    record-size 按无符号 64 位整数(uint64)解释,每条记录前缀为“长度 + 换行 + 数据”,例如 128\n{"type": "SUBSCRIBED",...}。由于 RecordIO 无统一正式规范,使用第三方实现时必须核对与 Mesos 格式一致。

11.3 Mesos Modules 扩展机制

modules.md 说明如何通过共享库按需扩展 Mesos 内部机制(自 0.21.0 起实验性支持):模块可用于 master、agent 与测试,也可用于链接 libmesos 的调度器(暂不支持 executor)。加载方式有两种(二选一):

  • --modules=filepath:通过 JSON 格式的 manifest 文件(file:///path/to/file 或 /path/to/file)或内联 --modules="{...}" 指定模块列表;
  • --modules_dir=dirpath:指定目录,其中每个文件是含模块描述的合法 JSON,按字母序处理。

典型用例包括自定义 allocator(分配器),详见 allocation-module.md(如何编写自定义资源分配器;分配器接口见 include/mesos/allocator/allocator.proto)。示例模块实现可参考 src/examples/test_allocator_module.cpp。

十二、Community:贡献指南与风格规范

文档首页的社区分区面向贡献者,给出了从入门到提交的完整路径:

十三、总结:如何高效使用这份文档地图

docs/home.md 的价值不在于单篇内容的深度,而在于它是一张覆盖 Mesos 全生命周期的权威导航图。建议按角色规划阅读路径:

  1. 初次接触:先读 architecture.md 建立主从模型与 offer 机制的心智模型,再读 running-workloads.md 理解任务如何被调度运行;
  2. 构建部署者:走 building.md → configuration.md → binary-packages.md 的路线,并随时用 mesos-master --help / mesos-agent --help 获取权威 flag 清单;
  3. 集群运维者:围绕 high-availability.md、agent-recovery.md、monitoring.md、operational-guide.md 与 upgrades.md/downgrades.md 建立运维手册;
  4. 框架开发者:以 app-framework-development-guide.md 为基础,结合 scheduler-http-api.md、executor-http-api.md 与 api-client-libraries.md 动手实践;
  5. 深入源码:每条文档链路都能落到具体源码目录——master 侧 src/master、agent 侧 src/slave、容器化 src/slave/containerizer、API protobuf include/mesos/v1、测试 src/tests,实现“文档 — 源码 — 测试”三位一体对照阅读。

借助这份文档地图,你可以在最短时间内从“知道 Mesos 是什么”进阶到“能够部署、运维并开发基于 Mesos 的分布式框架”。

登录后查看全文
mesos