argocd-agent Agent映射模式解析:Namespace路由与Destination路由深度对比
argocd-agent Agent映射模式解析:Namespace路由与Destination路由深度对比
argocd-agent Agent 映射模式(Agent Mapping Modes) 决定了 Application 在控制平面(principal)创建后,究竟被路由给哪一个工作集群上的 agent。它支持两种模式:Namespace 路由(默认)与 Destination 路由。这篇文章面向新手,用最少的配置对比两者的工作原理、优缺点与选型场景,帮你为多集群 Argo CD 选对路由方式。
1. 为什么需要 Agent 映射?
先理解 argocd-agent 解决的核心问题:传统 Argo CD 控制平面需要直连每一个远程集群,规模化后资源与连接管理压力巨大。argocd-agent 把它反转成"拉取模型"——每个工作集群里的 agent 主动连回控制平面的 principal,配置在两者间同步,对账(reconciliation)则本地化执行。
控制平面集群 工作集群 × N
┌─────────────────┐ ┌──────────┐
│ principal ──────────► │ agent │ ← 由 agent 发起连接
└─────────────────┘ └──────────┘
映射模式回答的是:同一个 principal 同时挂着 N 个 agent 时,一个 Application 到底发给谁?
下面这张官方架构图直观展示了控制平面与多个工作集群的"hub-and-spoke"关系:
理解了"一个 principal 管多个 agent"这个前提,映射模式就是"把 Application 投递到正确 agent 的那把钥匙"。
2. Namespace 路由(默认模式)
Namespace 路由用 Application 所在的命名空间来决定目标 agent,规则极其简单:
principal 上的命名空间名 = agent 名
例如 agent 名为 agent-prod,那么放在 agent-prod 命名空间里的所有 Application 都会被同步给这个 agent。它开箱即用、无需额外配置,因此是默认模式。
工作流程
- 在 principal 上创建
Application,放入与目标 agent 同名的命名空间。 - principal 依据命名空间路由事件给对应 agent。
- agent 收到后,在其本地固定命名空间(通常是
argocd)中创建该Application。
主要限制
- 一个命名空间只能对应一个 agent:同一命名空间无法把应用分发给不同 agent。
- 命名空间管理成本高:每新增一个 agent,就要在主集群新建一个命名空间。
- 多租户能力弱:共享同一 agent 的团队只能共用命名空间或各自申请 agent。
- 命名空间被改写:应用最终都落在 agent 的
argocd命名空间,丢失了原始命名空间信息。
⚠️ 重要提示:Namespace 路由目前仍为默认,但已被标记为弃用,未来版本将移除,新部署推荐 Destination 路由。详见 agent-mapping.md。
3. Destination 路由(推荐模式)
Destination 路由改用 Application 的 spec.destination.name 字段来决定目标 agent,与 Agent 命名空间完全解耦。这正是传统 Argo CD 用 cluster secret 定位集群时一直沿用的 destination.name 模型——用过传统 Argo CD 的同学可以无缝复用原有心智模型。
工作流程
- 在
argocd命名空间(默认)创建Application,把spec.destination.name设为目标 agent 名。 - principal 维护一张
appToAgent查找表,依据destination.name路由。 - agent 在与主集群相同的命名空间中创建应用(不再强制改写到
argocd)。
关键优势
- 真正的多租户:多个团队、多个命名空间可以同时指向同一个 agent。
- 命名空间保留:应用保留原始命名空间,隔离与 RBAC 更清晰。
- 灵活的分组:可按团队、环境等任意维度组织应用,而不必绑定到 agent。
- 兼容 apps-in-any-namespace:与 Argo CD 的任意命名空间特性天然契合。
注意:Destination 路由仅适用于 managed 模式的 agent。Autonomous(自主)agent 本身就是事实来源,无需该特性。
4. Namespace 路由 vs Destination 路由深度对比
| 维度 | Namespace 路由 | Destination 路由 |
|---|---|---|
| 路由依据 | Application 的命名空间 | spec.destination.name |
| 每个 agent 的应用命名空间 | 单一 | 多个 |
| 多租户支持 | 有限 | 完整 |
| 配置成本 | 默认(免配置) | 需开启开关 |
| agent 侧应用命名空间 | 固定为 agent 命名空间(常为 argocd) |
保留原始命名空间 |
| 支持的 agent 模式 | managed + autonomous | 仅 managed |
| Argo CD 用户熟悉度 | argocd-agent 特有概念 | 与传统 destination.name 一致 |
| 状态 | 已弃用(仍为默认) | 推荐用于新部署 |
一句话总结:小规模、单命名空间、追求零配置 → Namespace 路由;多团队、多租户、需要按业务维度组织 → Destination 路由。
5. Destination 路由如何启用?
Destination 路由需要在 principal 和 agent 两侧同时开启 --destination-based-mapping 开关,二者必须一致,否则会出现路由与缓存不一致。
Principal 侧
# 命令行
argocd-agent principal --destination-based-mapping
# 或环境变量
ARGOCD_PRINCIPAL_DESTINATION_BASED_MAPPING=true
Agent 侧
# 命令行(--create-namespace 可自动创建缺失的命名空间)
argocd-agent agent --destination-based-mapping --create-namespace
# 或环境变量
ARGOCD_AGENT_DESTINATION_BASED_MAPPING=true
ARGOCD_AGENT_CREATE_NAMESPACE=true
完整参数说明见 principal.md 与 agent.md。
两个配套细节
--create-namespace:Destination 路由下 agent 会在与主集群相同的命名空间创建应用。若该命名空间尚不存在,此开关允许 agent 自动创建,免去手工操作。--allowed-namespaces:principal 与 agent 都支持该参数,用通配符(如agent-*)限制各自可管理的命名空间范围,兼顾灵活与安全。
6. 选型建议
-
选 Namespace 路由:
- 简单部署,每个 agent 仅一个应用命名空间
- 无多租户隔离需求
- 希望配置最简、与既有部署向后兼容
-
选 Destination 路由(推荐新部署):
- 使用 managed 模式
- 多团队共享 agent 且需要命名空间隔离
- 希望按团队 / 项目而非 agent 来组织应用
- 依赖 apps-in-any-namespace 特性
- 熟悉传统 Argo CD 的
destination.name/ cluster-secret 模型,想直接复用
7. 常见排查要点
- 应用没出现在 agent 上
- Namespace 路由:确认
Application命名空间与 agent 名完全一致。 - Destination 路由:确认
spec.destination.name等于 agent 名,且 principal 与 agent 都已启用 destination 路由。
- Namespace 路由:确认
- Redis 缓存未命中(UI 报
error getting cached app managed resources)- 先确认 principal 与 agent 使用同一映射模式。
- 应用落在错误命名空间
- 确认 agent 侧已启用 destination 路由,且配置变更后已重启 agent,并核对目标命名空间在工作集群存在。
更完整的迁移步骤与故障排查见 Agent 映射模式指南。
8. 小结
argocd-agent 的两种 Agent 映射模式本质是"按命名空间路由"与"按目的地路由"的取舍:Namespace 路由胜在零配置、心智简单,但扩展性有限且已被弃用;Destination 路由通过 spec.destination.name 解耦了应用组织与 agent 拓扑,全面支持多租户与命名空间保留,是新部署的首选。理解二者的差异,是搭建可扩展多集群 Argo CD 的第一步。
延伸阅读:Agent 模式(managed vs autonomous) · 命名空间配置 · 架构概览 · managed 模式应用同步

