argocd-agent Agent映射模式解析:Namespace路由与Destination路由深度对比

原创2026-11-14 18:59:041,763 阅读

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"关系:

argocd-agent 多集群架构与控制平面路由总览

理解了"一个 principal 管多个 agent"这个前提,映射模式就是"把 Application 投递到正确 agent 的那把钥匙"。

2. Namespace 路由(默认模式)

Namespace 路由用 Application 所在的命名空间来决定目标 agent,规则极其简单:

principal 上的命名空间名 = agent 名

例如 agent 名为 agent-prod,那么放在 agent-prod 命名空间里的所有 Application 都会被同步给这个 agent。它开箱即用、无需额外配置,因此是默认模式。

argocd-agent 独立工作集群的同步与路由集成

工作流程

  1. 在 principal 上创建 Application,放入与目标 agent 同名的命名空间。
  2. principal 依据命名空间路由事件给对应 agent。
  3. 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 的同学可以无缝复用原有心智模型。

工作流程

  1. 在 argocd 命名空间(默认)创建 Application,把 spec.destination.name 设为目标 agent 名。
  2. principal 维护一张 appToAgent 查找表,依据 destination.name 路由。
  3. 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 路由。
  • 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 模式应用同步

登录后查看全文
argocd-agent