容器服务 agent-network 组件说明

一、组件介绍

传统 Kubernetes 网络默认关注“连通”，通常不负责把 Agent Pod 的 TCP 流量和 UDP/53 DNS 流量收敛到统一策略点，也无法在不改造业务 Pod 的前提下完成凭证注入和访问审计。其他协议不属于当前 HTTP 策略治理范围。Sidecar 方案能够提供一定的代理能力，但需要为每个工作负载注入额外容器，接入和运维成本较高，且绕过控制依赖 Pod 内网络配置。

agent-network 是面向 AI Agent 工作负载的云原生网络执行面组件，以 TKE Addon 形式交付。它在明确授权的 Canary Worker 节点上安装 Agent CNI；当前以节点而非 Pod Label 作为接入边界，Canary 节点上后续新建且使用主 CNI 的非 hostNetwork Pod 会进入 Agent CNI 路径并获得 Fake IP。宿主机 iptables 将 DNS 和 TCP 流量强制收敛到节点本地 ZeroProxy，由 ZeroProxy 执行访问策略、凭证注入、调用身份校验、直连旁路拦截和统一审计。

核心目标：

默认拒绝流量必经代理凭证不进入 Agent Pod访问过程可审计节点变更可灰度数据面故障可回滚

二、与 Kubernetes 的结合

agent-network 利用 Kubernetes 的调度、DaemonSet、Deployment、CRD、ConfigMap 和 Secret 管理能力：

·agent-cni-installer 以特权 DaemonSet 运行，仅调度到 Canary 节点，负责安装 CNI 二进制、CNI 配置、网桥、sysctl 和 iptables。

·zeroproxy 以 hostNetwork DaemonSet 运行，在每个 Canary 节点提供本地代理。

·credential-upstreams 为完整功能验证提供测试用受保护上游，生产业务可替换为真实上游。

·agent-network-controller 以 Deployment 运行，监听 AgentNetworkPolicy、AgentNetworkClass 并协调策略和 CNI 基础配置。

·AgentNetworkPolicy、ConfigMap 与 Secret 承载策略、上游地址和凭证引用。

·TKE Addon 通过 Chart 统一完成组件资源创建、镜像拉取和默认参数下发。

完整流量路径如下：

Agent Pod eth0（Fake IP） → 默认路由 → agentcni0 网桥 → 宿主机 iptables PREROUTING ├── UDP/53 → REDIRECT 到 ZeroProxy DNS :18053 ├── Service CIDR → fwmark 后交回 kube-proxy / 主 CNI └── TCP → REDIRECT 到 ZeroProxy :18080 → 策略匹配、身份校验、凭证注入、审计 → 目标服务

TKE 将 agent-network 封装为 Addon 后，用户通过控制台或 InstallAddon API 安装；但由于组件会修改目标节点 CNI、网桥和 iptables，仍必须遵循“单节点 Canary → 双节点 Canary → rollback 残留检查”的灰度流程。

三、核心概念

五、对比普通 Kubernetes Pod 网络

六、对比 Sidecar 代理

八、Coding Agent 访问代码仓库

Coding Agent 需要访问公开依赖或私有代码仓库，但不应持有长期 Token。可以允许公开仓库访问，并针对私有仓库配置 Credential 规则，由 ZeroProxy 注入 Authorization 请求头。

apiVersion: agent.tke.cloud.tencent.com/v1alpha1kind: AgentNetworkPolicymetadata: name: coding-agent-network namespace: tke-agent-network-realspec: podSelector: {} priority: 100 egress: allow: – name: public-git host: git.example.com protocol: tcp port: 443 credential: – name: private-git host: git.internal.example.com header: Authorization valueFrom: name: zeroproxy-credentials key: REPO_TOKEN deny: – name: production-db host: prod-db.internal directBypass: defaultAction: deny

注意：说明：

注意：当前 Controller 默认仅监听 Addon 所在命名空间（默认 tke-agent-network-real）。业务 Pod 可以位于其他命名空间，但 AgentNetworkPolicy 需创建在 Controller 的监听命名空间。

九、RAG Agent 访问向量数据库

可配置为允许 RAG Agent 访问对象存储和指定向量数据库；对向量数据库的访问由 ZeroProxy 注入检索 Token，其余数据库或高敏数据服务默认拒绝。

十、Multi-Agent 调用治理

多个 Agent 相互调用时，可基于 Caller 和 Target 定义 Ingress 规则。对于 Agent CNI 管理的 Fake-IP Pod，ZeroProxy 会将 X-Agent-Caller 中的调用方身份声明与来源 Pod 身份进行校验，并依据 X-Agent-Target 匹配目标规则，降低仅伪造请求头绕过授权的风险。

spec: podSelector: {} ingress: allow: – caller: "sa:agent-workloads:planner" target: "agent-server" deny: – caller: "sa:agent-workloads:untrusted-agent" target: "agent-server"

十一、防止访问敏感地址

ZeroProxy 内置拒绝以下敏感地址范围；即使业务策略显式 Allow，内置拒绝仍优先：

169.254.169.254/32100.64.0.0/10

十二、产品状态与支持范围

十三、使用限制

部署前请确认以下限制：

1. 仅支持 Linux 节点；Direct Bypass 的原始目标恢复依赖 Linux SO_ORIGINAL_DST。

2. Agent CNI 会修改目标节点的 CNI 配置、网桥、sysctl 和 iptables；必须先在专用 Canary Worker 上验证。

3. 不要在跳板机节点、控制节点或承载关键生产业务的节点上启用 Agent CNI。

4. agentCNI.installerEnabled 默认启用；只有带 Canary 标签的节点才会调度 Installer 并发生 CNI 变更。

5. 当 agentCNI.installerEnabled=true 时，agentCNI.serviceCIDRs 是必填安装参数；未提供时 Chart 将拒绝渲染。仅安装控制面且显式关闭 Installer 时可不配置。

6. agentCNI.fakeIPCIDR 的 Chart 默认值为 169.254.77.0/24，但当前不会作为 Installer 的实际 CIDR 下发参数；未配置 AgentNetworkClass 覆盖时，Installer 按节点名派生节点级 /24 CIDR。实际分配地址必须避免与节点、Pod、Service、VPC 和其他基础设施网段冲突。

7. ZeroProxy 使用 18080/TCP，DNS Proxy 使用 18053/UDP；安装前应确认目标节点端口没有冲突。

8. AgentNetworkPolicy 使用 valueFrom.name/key 引用已挂载到 ZeroProxy 的 Secret；Controller 会将其转换为运行时策略中的 valueFromFile。不支持 valueFromEnv。

9. zeroproxy.tls.allowUnverifiedSNI 默认关闭；无可信 DNS 或身份校验能力时不建议启用。

10. 已存在的 Pod 不会自动迁移到 Agent CNI；需按业务计划重建并调度新的 Pod 到 Canary 节点。当前 podSelector / workloadSelector 不是 Pod 级 CNI 接入开关，因此 Canary 节点应保持为专用节点。

11. 卸载 Addon 前必须执行 CNI rollback；仅卸载 Helm Release 或 Addon 不能替代宿主机数据面清理。

12. AgentNetworkPolicy.spec.podSelector 与 AgentNetworkClass.spec.workloadSelector 已进入 API，但当前不作为 Pod 级选择性 CNI 接入开关；现阶段以专用 Canary 节点作为工作负载隔离边界。

13. AgentNetworkClass.spec.proxy.failMode 与 spec.cni.defaultConnectivity 当前为 API/下发字段；v0.3.0 数据面仍按 Fail-Close / ZeroConnectivity 运行，不能依赖 FailOpen 自动直连。

14. Addon / Chart / 团队镜像发布版本为 0.3.0 / v0.3.0；当前 Agent CNI 节点版本记录可能仍显示 v0.2.5。该问题不影响已验证的数据面功能，但会影响版本追踪和升级诊断，需后续修复并复验。

十五、1. 规划节点角色

至少选择两台可中断、非关键业务的 Worker 节点：

·第一台用于单节点 Canary 验证；

·第二台用于双节点验证；

·跳板机节点和关键业务节点不得参与 CNI 替换。

查看节点：

kubectl get node -o widekubectl get pod -A -o wide

十六、2. 为第一台 Canary 节点打标签

kubectl label node <第一台-worker节点名> \\ tke-agent-network.io/agent-cni-canary=true

验证完成并准备做双节点验证时，再给第二台 Worker 打同样的标签：

kubectl label node <第二台-worker节点名> \\ tke-agent-network.io/agent-cni-canary=true

十七、3. 确认 Service CIDR

必须确认集群真实 Service CIDR。可通过 TKE 集群配置获取，也可通过现有 ClusterIP 辅助判断：

kubectl get svc -A \\ -o jsonpath='{range .items[*]}{.spec.clusterIP}{"\\n"}{end}' \\ | grep -v -E '^(None|<none>|)$' \\ | sort -u \\ | head

例如，ClusterIP 位于 192.168.x.x 时，常见 Service CIDR 为：

192.168.0.0/16

注意：说明：

注意：Service CIDR 必须以集群实际配置为准，不能仅凭示例猜测。

十八、4. 准备回滚窗口

在安装前确认：

·可以登录到目标 Worker。

·已记录节点当前状态。

·具备执行 rollback 和节点残留检查的窗口。

·生产业务已避开 Canary 节点，或允许在验证期间重建。

20、方式一：控制台安装

1. 登录 TKE 控制台并进入目标集群。

2. 进入“组件管理”，选择新建组件。

3. 选择 agent-network。

4. 选择 Addon 版本 0.3.0。

5. 在参数中提供真实 Service CIDR。

6. 提交安装并等待组件运行。

基础安装至少需要：

agentCNI: serviceCIDRs: – <真实 Service CIDR>

21、方式二：通过 API 安装

调用 TKE InstallAddon 接口。基础安装 JSON 示例：

{ "Region": "ap-<region>", "ClusterId": "cls-xxxxxxxx", "AddonName": "agent-network", "AddonVersion": "0.3.0", "RawValues": "{\\"agentCNI\\":{\\"serviceCIDRs\\":[\\"<真实 Service CIDR>\\"]}}"}

默认 Chart 已使用团队组件镜像，不需要在 RawValues 重复设置 image.registry、image.tag 或组件 repository。

完整 demo/e2e 验证时，才额外配置测试专用的：

·credentialUpstream.enabled=true。

·credentials.repoToken 与 credentials.ragToken。

·zeroproxy.reload.enabled=true，并必须设置非空的 zeroproxy.reload.token。

·zeroproxy.upstreams 的测试映射。

·Credential 策略规则。

这些测试 token 和测试 upstream 不应直接复用于真实生产业务。当前 Chart 会将 credentials.* 和 reload token 渲染为组件 Secret，因此完整 demo/e2e 的 token 只能在隔离测试环境中通过受控 API 请求传入；不得将生产凭证写入 RawValues、命令行、示例文件或终端历史。启用 credential-upstreams 后，该测试组件会从 Secret 读取期望 token 以验证注入结果；这不改变“业务 Agent Pod 不挂载凭证”的产品边界。

23、1. 查看组件状态

以下命令以默认 namespace tke-agent-network-real 为例：

kubectl get ds,deploy,pod -n tke-agent-network-real -o wide

单节点 Canary 的预期：

agent-cni-installer 1/1 Readyzeroproxy 1/1 Readyagent-network-controller 1/1 Ready

完整 demo/e2e 模式还会运行：

credential-upstreams 1/1 Ready

启用完整 demo/e2e 时，双节点 Canary 扩展后 agent-cni-installer、zeroproxy、credential-upstreams 三个 DaemonSet 均预期为 2/2 Ready；默认安装时检查前两个 DaemonSet 为 2/2 Ready。

24、2. 查看真实 CNI 安装状态

在目标 Worker 上检查：

ip addr show agentcni0ls -l /opt/cni/bin/agent-cnils -l /etc/cni/net.d/00-agent-cni.confls -la /var/lib/tke-agent-network/agent-cni/

检查 sysctl：

sysctl \\ net.ipv4.ip_forward \\ net.ipv4.conf.all.rp_filter \\ net.ipv4.conf.default.rp_filter \\ net.ipv4.conf.agentcni0.rp_filter

预期：

net.ipv4.ip_forward = 1rp_filter = 0

25、3. 运行内置诊断

kubectl exec -n tke-agent-network-real ds/agent-cni-installer — \\ /agent-cni –doctor \\ –doctor-state-dir=/host/var/lib/tke-agent-network/agent-cni \\ –doctor-host-cni-bin=/host/opt/cni/bin \\ –doctor-host-cni-conf=/host/etc/cni/net.d \\ –doctor-zeroproxy-url=http://127.0.0.1:18080/healthz

预期输出：

AGENT_CNI_DOCTOR_PASSED

26、4. 验证 HTTP e2e 与真实 CNI e2e

完整验证应至少覆盖：

完整验证中的成功标记按验证层次区分如下。

HTTP e2e（策略、凭证与 ingress）应包含：

EGRESS_ALLOWED_BY_POLICYCREDENTIAL_INJECTED_BY_ZEROPROXYEGRESS_DENIED_BY_POLICYINGRESS_ALLOWED_BY_ZEROPROXYINGRESS_DENIED_BY_ZEROPROXYCODING_AGENT_DEMO_PASSEDRAG_AGENT_DEMO_PASSEDMULTI_AGENT_GATEWAY_DEMO_PASSED

真实 CNI e2e（Fake IP、iptables REDIRECT 和节点数据面）应包含：

EGRESS_ALLOWED_BY_POLICYCODING_AGENT_DEMO_PASSEDRAG_AGENT_DEMO_PASSEDDIRECT_BYPASS_DENIED_BY_ZEROPROXY

DNS 与 ClusterIP Service 为独立的主 CNI 兼容性检查，应包含：

MAIN_CNI_DNS_PASSEDMAIN_CNI_SERVICE_PASSEDMAIN_CNI_COMPAT_CHECKS_PASSED

28、Fake IP 与 Service CIDR

Agent CNI 使用节点级 Fake IP CIDR 为 Pod 分配地址。未配置 AgentNetworkClass 覆盖时，Installer 会按节点名派生不同的节点级 /24 CIDR；agentCNI.fakeIPCIDR 当前仅参与 Chart 参数校验，不作为 Installer 的有效 CIDR 下发参数。Service CIDR 流量必须 bypass ZeroProxy，交由 kube-proxy 和主 CNI 转发。

Fake-IP Pod ├── DNS（UDP/53）→ ZeroProxy DNS Proxy ├── ClusterIP Service → fwmark bypass → kube-proxy / 主 CNI └── 其他 TCP → ZeroProxy 策略代理

29、出口治理与审计

ZeroProxy 对出站流量按以下优先级处理：

deny → credential → allow → 默认拒绝

建议：

·默认只允许业务真正需要访问的域名；

·AgentNetworkPolicy 使用 Secret valueFrom.name/key 引用；Controller 将其转换为运行时 valueFromFile，不写入 Agent Pod；

·对数据库、客户数据服务、Metadata 等敏感目标显式拒绝；

·保留审计日志，并对异常 deny/credential 命中建立告警。

30、Direct Bypass

默认配置：

policy: directBypass: defaultAction: deny

建议保持默认拒绝，避免 Agent Pod 直连 Agent Fake-IP CIDR 内目标。其他 TCP 出站请求由 Egress 策略处理，未命中 Allow 或 Credential 规则时默认拒绝。

32、升级

升级应遵循与安装相同的节点灰度原则：

1. 先在单节点 Canary 验证目标镜像和组件状态；

2. 运行 HTTP e2e 和真实 CNI e2e；

3. 再扩展到第二节点；

4. 确认双节点策略 reload、DNS/Service 与 rollback；

5. 再进入更多节点或更多地域。

升级前应记录当前 Addon 参数、策略 CR、AgentNetworkClass 和节点标签。

33、卸载

不能直接卸载 Addon 代替 CNI rollback。

正确顺序：

停止 agent-cni-installer→ 在 Canary 节点执行 rollback-agent-cni→ 检查宿主机残留→ 移除 Canary 标签→ 再卸载 Addon 或清理剩余组件

34、回滚残留检查

每个参与过 CNI 替换的 Worker 都必须确认以下项目不存在：

agentcni0 网桥AGENT-CNI iptables 规则/opt/cni/bin/agent-cni/etc/cni/net.d/00-agent-cni.conf/var/lib/tke-agent-network/agent-cni 状态文件

36、安装后 agent-cni-installer 未就绪

检查：

kubectl get pod -n tke-agent-network-real -o widekubectl describe pod -n tke-agent-network-real <installer-pod>kubectl logs -n tke-agent-network-real <installer-pod>

常见原因：

37、DNS 或 ClusterIP Service 不通

检查：

iptables -t nat -Siptables -t mangle -Skubectl get svc -A -o wide

重点确认：

·agentCNI.serviceCIDRs 是否为真实 Service CIDR；

·AGENT-CNI-MANGLE 是否包含 Service CIDR 的 0x77 标记规则；

·AGENT-CNI-PREROUTING 是否在 mark 命中后 RETURN；

·agentcni0、ip_forward 和 rp_filter 是否正常。

38、AgentNetworkPolicy 长时间不是 Active

检查：

kubectl get agentnetworkpolicy -A -o widekubectl logs -n tke-agent-network-real deploy/agent-network-controller –tail=200kubectl logs -n tke-agent-network-real ds/zeroproxy –tail=200

双 ZeroProxy 场景中，ConfigMap volume 投影可能短暂返回 409 policy version not yet projected。Controller 应重试并最终使 Policy 进入：

phase=ActiveobservedGeneration=<当前 generation>

39、rollback 后仍有节点残留

不要仅删除 Addon。重新执行 rollback 并分别登录每个 Canary Worker 检查网桥、iptables、CNI 二进制、CNI 配置和 state 目录。

41、Q1：agent-network 会替换整个集群的主 CNI 吗？

不会。组件只在带 Canary 标签的目标 Worker 上为后续新建并调度到该节点的 Pod 接入 Agent CNI；当前不按 Pod Label 选择性接入，因此应使用专用 Canary 节点。Service 流量仍交由 kube-proxy 和主 CNI 处理。跳板机节点和未打标签的 Worker 不参与替换。

42、Q2：为什么必须提供 Service CIDR？

Agent CNI 会将除 Service 旁路外的 TCP 流量重定向到 ZeroProxy。如果无法识别 ClusterIP Service 地址，Service 流量可能被错误送入 HTTP 策略路径，影响 Kubernetes 服务通信。因此安装前必须提供真实 Service CIDR。

43、Q3：为什么需要单节点和双节点 Canary？

单节点用于先验证安装、CNI 接管和最小数据面；双节点用于验证不同 Fake IP CIDR 分配、跨节点组件运行、Service 兼容，以及多 ZeroProxy Pod 的策略 reload 恢复能力。

44、Q4：HTTP e2e 和真实 CNI e2e 的区别是什么？

HTTP e2e 使用 hostNetwork Job 直接访问本机 ZeroProxy，验证策略、凭证注入和代理逻辑。真实 CNI e2e 使用非 hostNetwork Pod，验证 Fake IP、agentcni0、节点 iptables REDIRECT 和 ZeroProxy 的完整数据面链路。两者都应通过。

45、Q5：卸载 Addon 后节点会自动恢复吗？

不保证。CNI 会修改宿主机网络状态，必须先执行 rollback 并完成残留检查；直接卸载 Addon 不可替代节点级回滚。

46、Q6：可以把测试用 token 和 upstream 直接用于生产吗？

不可以。完整 demo/e2e 使用的是测试 token、测试域名和本地测试 upstream。生产环境应接入真实业务上游、使用受控 Secret，并按最小权限配置策略。

48、常用安装参数

49、内部组件说明