Apache Mesos 1.3.0 版本发布深度解析：多角色框架、HTTP Executor 认证与滚动升级指南

• 集群管理
• 任务调度
• 后端

Apache Mesos 1.3.0 是该项目在 2017 年发布的里程碑式版本，核心亮点包括：为"多用户"（multi-user）框架引入多角色（multi-role）资源订阅能力、为 HTTP Executor API 提供认证与授权支持，以及框架可以动态修改订阅角色。本文基于 官方发布公告，并结合当前仓库源码与官方文档，系统梳理这三个核心特性的设计背景、实现原理、配置参数与从 1.2.x 升级到 1.3.x 的完整操作指南，帮助集群运维人员与框架开发者快速掌握新版本能力。

一、版本概览

Mesos 1.3.0 是继 1.2.0 之后的一次重要特性版本，可从 官方下载页 获取。除了下述三大核心特性外，该版本还包含140 多个其他缺陷修复与改进，完整清单见仓库根目录的 CHANGELOG。

本次发布由 Apache Mesos 社区 55 位贡献者共同完成，包括 Benjamin Mahler、Jie Yu、Vinod Kone、James Peach、Joseph Wu、Qian Zhang 等长期活跃的 Mesos Committer。如果你在使用中遇到问题，可通过社区邮件列表、IRC 或 Slack 反馈（详见 site 社区页面）。

二、核心特性一：框架多角色资源订阅（MESOS-1763）

2.1 背景：Mesos 的 role 机制

在 Mesos 中，角色（role）是资源分配的基本实体：集群的资源被分配给各个角色，主节点的分配器（allocator）确保资源在角色之间公平共享，并可通过配额（quota）、权重（weight）等机制调整各角色的资源份额。更完整的机制说明见 docs/roles.md。

在 1.3.0 之前，一个框架在注册时只能通过FrameworkInfo.role字段订阅一个角色。这意味着：

• 想要服务多个租户（团队、部门）的"多用户"框架，要么运行多个单角色框架实例，各自服务一个角色；
• 要么在框架内部自行实现多用户资源分配逻辑，例如把收到的资源再按用户二次切分。

两种方案都存在明显缺陷：前者导致资源被拆散、框架实例难以共享状态；后者则把复杂的分配逻辑重复实现到每个框架中。

2.2 解决方案：FrameworkInfo.roles+MULTI_ROLEcapability

1.3.0 起，框架可以通过FrameworkInfo.roles字段一次性订阅多个角色。在 include/mesos/mesos.proto 中可以看到该字段的定义与约束：

// Roles are the entities to which allocations are made. // The framework must have at least one role in order to // be offered resources. Note that `role` is deprecated // in favor of `roles` and only one of these fields must // be used. Since we cannot distinguish between empty // `roles` and the default unset `role`, we require that // frameworks set the `MULTI_ROLE` capability if // setting the `roles` field. optional string role = 6 [default = "*", deprecated=true]; repeated string roles = 12;

关键约束如下：

• 框架必须显式声明MULTI_ROLEcapability才能使用roles字段（否则无法区分"空 roles"与"未设置的 role"）；
• role字段自此被标记为deprecated，新旧字段只能二选一；
• 多角色框架在FrameworkInfo.Capability.Type枚举中对应的值是MULTI_ROLE = 6（见 include/mesos/mesos.proto），其语义说明中明确指出：框架应通过新增的roles字段表达"多租户"能力，并检查Offer.allocation_info以确定 offer 是分配给哪个角色的，同时预期单租户调度器最终也会迁移到roles字段并弃用role；
• Agent 侧同样需要具备MULTI_ROLE能力声明（AgentInfo.Capability.Type中的MULTI_ROLE = 1，见 include/mesos/mesos.proto），以支持启动多角色框架的任务。

2.3 收到 offer 时如何区分角色

当框架订阅了多个角色后，被 offer 的资源一定恰好关联其中一个角色。框架可以通过Offer.allocation_info.role字段（以及每个被 offer 的Resource上的allocation_info.role字段）来判断该 offer 面向哪个角色。在当前的实现中，一个 Offer 中的所有资源都分配给同一个角色，这一行为在 docs/roles.md 中有明确说明。

2.4 配套能力：REVIVE / SUPPRESS 支持按角色操作

多角色订阅还带动了 offer 控制原语的细化。在 include/mesos/scheduler/scheduler.proto 中，REVIVE调用新增了可选的roles字段：

// Revive offers for the specified roles. If `roles` is empty, // the `REVIVE` call will revive offers for all of the roles // the framework is currently subscribed to. message Revive { repeated string roles = 1; }

SUPPRESS调用同样支持按角色抑制 offer（见 include/mesos/scheduler/scheduler.proto）。这意味着多角色框架可以细粒度地控制每个角色的 offer 流量，例如在某个角色下暂时没有任务需求时只抑制该角色。

三、核心特性二：框架动态修改订阅角色（MESOS-6627）

多用户场景的另一个现实需求是：角色的集合会随时间动态变化——新员工入职、新团队成立会带来新角色，员工离职、团队解散则让旧角色失效。如果角色是静态写死的，多用户框架就无法跟随组织结构的演进。

MESOS-6627 为框架提供了修改已订阅角色集合的能力：框架通过**携带更新后的FrameworkInfo重新注册（reregister）**即可变更订阅的角色。这一能力是 MESOS-1763 多角色订阅的必备配套，两者共同构成完整的"多用户框架"支持。正如 docs/roles.md 所述：

A framework specifies which roles it would like to subscribe to when it subscribes with the master. This is done via therolesfield inFrameworkInfo. A framework can also change which roles it is subscribed to by reregistering with an updatedFrameworkInfo.

在实现上，一个多用户调度器可以从命令行接收--mesos-roles之类的参数，甚至与组织内部的 LDAP 系统同步，自动根据组织架构调整订阅的角色。

四、核心特性三：HTTP Executor 认证与授权（MESOS-6365）

4.1 新增的 Agent 配置参数

1.3.0 为 Agent 引入了两个与 HTTP Executor 安全相关的参数，定义于 src/slave/flags.cpp：

需要特别说明的是，在当前仓库中--executor_secret_key已被重命名：它现在作为--jwt_secret_key的已废弃别名（flags::DeprecatedName("executor_secret_key")）存在，其正式定义为"生成 JWT 密钥所用的密钥文件路径，仅当 Mesos 以 SSL 支持编译时可用"（见 src/slave/flags.cpp）。1.3.0 时代使用--executor_secret_key，后续版本建议使用--jwt_secret_key。对应字段在 src/slave/flags.hpp 与 src/slave/flags.hpp 中声明。

4.2 Agent 启动时的参数校验逻辑

从 src/slave/slave.cpp 的 Agent 初始化代码可以看到这两个参数的实际联动逻辑：

• 当--authenticate_http_executors为true且未显式指定--http_authenticators时，Agent 会自动加载默认的basic与jwt两类 HTTP 认证器；
• 如果--authenticate_http_executors为true但未提供--jwt_secret_key，Agent 会直接启动失败（EXIT(EXIT_FAILURE) << "--jwt_secret_key must be specified when --authenticate_http_executors is set to true"）；
• 密钥文件权限过宽（其他用户可读）时，Agent 会输出警告日志，建议密钥文件仅对运行 Agent 的用户可读；
• 随后通过initializeHttpAuthenticators(EXECUTOR_HTTP_AUTHENTICATION_REALM, ...)为 HTTP executor API 的认证域初始化认证器。

4.3 工作机制：JWT 令牌的生成与使用

根据 docs/authentication.md 的说明，当 Agent 通过--jwt_secret_key加载密钥后，会在每个 executor 启动前为其生成一个默认 JWT，并通过环境变量MESOS_EXECUTOR_AUTHENTICATION_TOKEN注入到 executor 的环境中。Executor 需要把这个令牌放到所有请求的Authorization头中：

Authorization: Bearer MESOS_EXECUTOR_AUTHENTICATION_TOKEN

需要认证的 HTTP executor 包括：

• 默认 executor（default executor）；
• HTTP command executor；
• 自定义 HTTP executor。

而未使用 HTTP API 的命令型与自定义 executor 仍然保持未认证状态。

另外，HTTP executor 还会调用 Agent 的 operator API 来发起嵌套容器操作（如LAUNCH_NESTED_CONTAINER）。因此官方文档特别提示：当 HTTP executor 认证未启用时，不要同时启用--authenticate_http_readwrite，否则 HTTP executor 将无法正常工作（见 docs/authentication.md）。

4.4 隐式授权规则

与认证配套，1.3.0 还引入了隐式授权规则，完整阐述见 docs/authorization.md：

• Executor API 方向：当 Agent 设置了--authenticate_http_executors后，HTTP executor 必须先通过认证。认证通过后适用一条简单的隐式规则——executor 只能对自己执行操作。具体而言，executor 的认证 principal 必须包含fid、eid、cid三个 claim，且其值分别等于当前运行中 executor 的框架 ID、executor ID 和容器 ID。默认情况下，包含这些 claim 的认证令牌会被注入到 executor 环境（即上文的环境变量）。
• Operator API 方向：当 Agent 设置了--authenticate_http_readwrite后，HTTP executor 在调用LAUNCH_NESTED_CONTAINER等 operator API 时也需要认证。此时由已加载的授权模块执行授权；默认的 Mesos 本地授权器应用一条隐式规则，要求 executor 的 principal 包含值为当前 executor 容器 ID 的cidclaim。

4.5 启用后的升级破坏性说明

官方发布公告明确警告：在升级后启用这些参数，会对升级前已启动的 HTTP executor 造成破坏。因此推荐按照 docs/authentication.md 中的三步流程执行：

1. 先升级所有 Agent，并通过--jwt_secret_key为每个 Agent 提供密钥（用于以 HMAC-SHA256 算法签发 executor 认证令牌），此时暂不启用强制认证；
2. 确保所有运行中的 HTTP executor 都带有认证令牌且支持认证——升级前已在运行的 executor 必须重启。既可以一次性全部重启，也可以让集群停留在中间状态、随 executor 自然换新逐步完成；
3. 当所有默认/HTTP command executor 都由升级后的 Agent 启动、且自定义 HTTP executor 均已升级后，再以--authenticate_http_executors重启 Agent 进程，强制开启 HTTP executor 认证。由于此时所有 executor 都已具备令牌并支持认证，它们的请求将顺利通过。

五、从 1.2.x 滚动升级到 1.3.x

5.1 总体结论

官方公告确认：从 Mesos 1.2.0 集群滚动升级到 1.3.0 是直接的（straightforward），详细说明见 docs/upgrades.md。在 docs/upgrades.md 中给出了通用升级步骤：

1. 重新构建并安装任何自定义模块（确保升级后的 master/agent/scheduler 可用）；
2. 安装新的 master 二进制并重启 master；
3. 安装新的 agent 二进制并重启 agent；
4. 链接最新的原生库 / jar / egg 来升级 scheduler（如需要）；
5. 重启 scheduler；
6. 链接最新的原生库 / jar / egg 来升级 executor（如需要）。

5.2 需要注意的破坏性变更

升级到 1.3.x 时，docs/upgrades.md 记录了以下必须注意的变更：

• 不再接受 0.x Agent 注册：主节点将忽略 0.x agent 的注册请求（1.1+ master 与 0.x agent 的互通本就从未支持过，此前只是未显式禁止）；
• 废弃 ACL 移除：本地授权器中已移除set_quotas/remove_quotas（请改用替代 ACLupdate_quotas）以及shutdown_frameworks（请改用新 ACLteardown_frameworks）。务必在替换 Mesos 二进制之前完成 ACL 的合并与替换；
• FrameworkInfo.role字段废弃：多角色框架支持使得role字段被roles字段取代。使用新字段的框架可以继续只使用单个角色，但解析 master/agent 端点信息、依赖role字段的工具需要在集群安全运行多角色框架前完成更新；
• 分配器模块接口变更：实现 allocator 模块的开发者需要新增满足MULTI_ROLE框架能力的功能实现；
• 新增authenticate_http_executors与executor_secret_key参数：用于启用 HTTP executor 强制认证与设置令牌密钥文件，启用时机按上文 4.5 节的三步流程执行。

六、测试与验证参考

当前仓库的测试代码为上述特性提供了直接验证：

• src/tests/slave_tests.cpp 在 Agent 相关测试中分别以authenticate_http_executors = false与= true两种配置运行，覆盖了启用/关闭 HTTP executor 认证两种场景；
• src/tests/executor_http_api_tests.cpp 在 HTTP executor API 测试中显式关闭认证（flags.authenticate_http_executors = false），验证未认证路径下的 API 行为；
• src/tests/mesos.cpp 的测试基础设施在启动测试集群时默认开启authenticate_http_executors = true，即默认测试路径本身就覆盖了认证开启状态。

这些测试与 docs/authentication.md、docs/authorization.md、docs/roles.md 共同构成了 1.3.0 新特性的完整证据链。

七、小结

Apache Mesos 1.3.0 围绕"多租户框架"这一主线完成了三项关键能力：

1. 多角色订阅（MESOS-1763）——框架通过FrameworkInfo.roles+MULTI_ROLEcapability 一次订阅多个角色，借助Offer.allocation_info.role区分 offer 归属，并以REVIVE/SUPPRESS按角色精细控制 offer；
2. 动态角色调整（MESOS-6627）——框架通过携带更新后的FrameworkInfo重新注册来变更订阅角色，使多用户框架能跟随组织结构演进；
3. HTTP Executor 认证授权（MESOS-6365）——通过--authenticate_http_executors与--executor_secret_key/--jwt_secret_key实现基于 JWT 的强制认证，并辅以"executor 只能操作自己"的隐式授权规则。

对于计划升级的集群，1.2.x → 1.3.x 的滚动升级路径清晰，但务必先处理废弃 ACL、FrameworkInfo.role字段及 0.x agent 兼容性等问题；对于希望启用 HTTP executor 认证的集群，则必须严格遵守先注入令牌、再开启强制的三步升级流程。

• 集群管理
• 任务调度
• 后端