容器服务 agent-network 组件说明

组件介绍
在 AI Agent 场景中，工作负载通常需要访问代码仓库、对象存储、向量数据库、内部 API 或其他 Agent 服务。与普通应用相比，Agent 能够自主生成代码、发起网络请求并使用业务凭证；如果缺少统一网络治理，可能出现访问生产数据库、绕过受控入口、凭证直接暴露给 Pod、调用身份伪造和审计缺失等风险。
传统 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
访问过程可审计
节点变更可灰度
数据面故障可回滚
特点
说明
真实 CNI 接入
Agent CNI 为 Canary 节点上后续新建、使用主 CNI 的 Pod 配置 veth、agentcni0 网桥、Fake IP、默认路由和节点侧 iptables 规则。
强制流量收敛
UDP/53 流量重定向到节点 DNS Proxy；除命中 Service CIDR 并被标记旁路的流量外，TCP 流量重定向到 ZeroProxy。
默认拒绝
Egress、Ingress 和 Direct Bypass 支持默认拒绝；敏感 Metadata/CGNAT 地址具备内置拒绝保护。
凭证隔离
业务 Agent Pod 不挂载凭证；凭证保存在 Kubernetes Secret 中，由 ZeroProxy 在转发时读取和注入。
动态策略
AgentNetworkPolicy 支持策略声明；Controller 更新 ConfigMap 并触发 ZeroProxy 热加载。
Service 兼容
Service CIDR 流量使用 fwmark 交回 kube-proxy 和主 CNI，避免影响 Kubernetes ClusterIP Service。
灰度与回滚
仅带 Canary 标签的节点会安装 CNI；提供节点级 rollback 和宿主机残留检查。
与 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 残留检查”的灰度流程。
核心概念
概念
说明
Agent 工作负载
调度到启用 Agent CNI 的 Canary 节点、需要纳入网络治理的新建 Pod。当前以专用 Canary 节点为隔离边界，而非 Pod Label 选择器。
Canary 节点
带有 tke-agent-network.io/agent-cni-canary=true 标签、明确授权安装 Agent CNI 的 Worker 节点。
Agent CNI
负责 Fake IP、Pod 网络命名空间、veth、agentcni0、路由、状态文件与 iptables 规则的真实 CNI 插件。
Fake IP
Agent CNI 分配给 Agent Pod 的专用地址，不等同于主 CNI Pod IP；用于流量收敛和来源身份映射。
ZeroProxy
节点本地策略代理，监听 :18080，负责 Egress、Ingress、凭证注入、Direct Bypass、审计和指标。
DNS Proxy
ZeroProxy 的 UDP DNS 代理，默认监听 :18053，接收 Fake-IP Pod 的 DNS 请求。
Service CIDR
集群 Kubernetes Service 的地址范围。安装时必须提供，用于避免 ClusterIP Service 流量进入 HTTP 策略代理。
AgentNetworkPolicy
Namespaced CRD，声明 Egress Allow/Credential/Deny、Ingress 和 Direct Bypass 策略。
AgentNetworkClass
Cluster-scoped CRD，声明 Fake IP CIDR、Service CIDR、代理端口等节点基础网络参数；部分 API 字段当前仅下发记录，不触发数据面模式切换。
CNI State
Agent CNI 持久化的 Pod 网络/身份状态，ZeroProxy 可据此将 Fake IP 映射回 Pod 身份。
Direct Bypass
Agent Pod 直接访问 Agent Fake-IP CIDR 内目标地址、试图绕过受控入口的行为；默认拒绝。其他 TCP 出站请求仍由 Egress 策略处理。
产品优势
对比普通 Kubernetes Pod 网络
维度
普通 Pod 网络
agent-network
出站访问
应用可直接访问网络可达目标
由 ZeroProxy 统一执行 Allow、Credential、Deny
凭证管理
常将 Secret 注入业务 Pod
凭证仅挂载给 ZeroProxy，按规则转发时注入
DNS
使用主 CNI/集群默认 DNS 路径
Fake-IP Pod 的 DNS 经节点本地 DNS Proxy 统一处理
Agent 间调用
依赖业务自行鉴权
支持 Caller/Target 规则及 Fake-IP 来源身份校验
绕过控制
Pod 可能尝试直连目标
节点 iptables 强制收敛，Direct Bypass 默认拒绝
审计
日志分散在业务系统
ZeroProxy 统一输出策略命中与访问审计
节点变更
无 CNI 变更
CNI 变更需 Canary 和可验证 rollback
对比 Sidecar 代理
维度
Sidecar 代理
agent-network
接入方式
每个 Pod 注入代理容器
节点级 Agent CNI + ZeroProxy
业务改造
可能需要改造 Deployment/Pod 模板
Agent 应用无需感知本地代理地址
资源占用
每个 Pod 一份代理资源
每个 Canary 节点一份 ZeroProxy
流量接管
多依赖 Pod 内重定向和注入逻辑
由 CNI 和节点 iptables 在网络路径中强制接管
凭证位置
可能同时存在于业务 Pod 和 Sidecar
凭证仅保留在 ZeroProxy 所挂载 Secret
风险范围
主要影响单个工作负载
涉及节点 CNI，必须严格按灰度和回滚流程操作
典型使用场景
Coding Agent 访问代码仓库
Coding Agent 需要访问公开依赖或私有代码仓库，但不应持有长期 Token。可以允许公开仓库访问，并针对私有仓库配置 Credential 规则，由 ZeroProxy 注入 Authorization 请求头。
apiVersion: agent.tke.cloud.tencent.com/v1alpha1
kind: AgentNetworkPolicy
metadata:
  name: coding-agent-network
  namespace: tke-agent-network-real
spec:
  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/32
100.64.0.0/10
产品状态与支持范围
项目
说明
当前版本
Addon / Chart 0.3.0
发布形态
TKE Addon / Helm Chart
发布状态
灰度发布阶段；实际可安装地域和版本以 TKE Addon 控制台展示为准。
支持集群类型
TKE 托管集群（MANAGED_CLUSTER）
Kubernetes 版本
Chart 声明 >= 1.20.0-0
节点系统
Linux
节点架构
当前 Chart 面向 amd64 节点。
主 CNI 兼容性
已在 TKE ENI / Multus 环境完成真实集群验证；安装必须提供实际 Service CIDR。
策略协议
HTTP；TLS SNI 透传能力默认关闭，未配置可信 DNS/身份校验时不建议开启。
是否计费
组件不单独收费，但会占用目标节点 CPU、内存、网络和日志存储资源。
使用限制
部署前请确认以下限制：
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 wide
kubectl 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 节点，或允许在验证期间重建。
安装 agent-network
方式一：控制台安装
1. 登录 TKE 控制台并进入目标集群。
2. 进入“组件管理”，选择新建组件。
3. 选择 agent-network。
4. 选择 Addon 版本 0.3.0。
5. 在参数中提供真实 Service CIDR。
6. 提交安装并等待组件运行。
基础安装至少需要：
agentCNI:
  serviceCIDRs:
    - <真实 Service CIDR>
方式二：通过 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 不挂载凭证”的产品边界。
安装后验证
1. 查看组件状态
以下命令以默认 namespace tke-agent-network-real 为例：
kubectl get ds,deploy,pod -n tke-agent-network-real -o wide
单节点 Canary 的预期：
agent-cni-installer  1/1 Ready
zeroproxy            1/1 Ready
agent-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。
2. 查看真实 CNI 安装状态
在目标 Worker 上检查：
ip addr show agentcni0
ls -l /opt/cni/bin/agent-cni
ls -l /etc/cni/net.d/00-agent-cni.conf
ls -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 = 1
rp_filter = 0
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
4. 验证 HTTP e2e 与真实 CNI e2e
完整验证应至少覆盖：
验证层次
验证内容
HTTP e2e
ZeroProxy 的 Allow、Credential、Deny、Ingress allow/deny、Coding/RAG/Gateway demo
真实 CNI e2e
Fake-IP Pod、iptables REDIRECT、Coding、RAG、Direct Bypass deny
主 CNI 兼容
DNS、ClusterIP Service
控制面
双 ZeroProxy ConfigMap projection/reload、AgentNetworkPolicy 最终 Active
安全与可观测
审计日志不泄露凭证、metrics 可访问
完整验证中的成功标记按验证层次区分如下。
HTTP e2e（策略、凭证与 ingress）应包含：
EGRESS_ALLOWED_BY_POLICY
CREDENTIAL_INJECTED_BY_ZEROPROXY
EGRESS_DENIED_BY_POLICY
INGRESS_ALLOWED_BY_ZEROPROXY
INGRESS_DENIED_BY_ZEROPROXY
CODING_AGENT_DEMO_PASSED
RAG_AGENT_DEMO_PASSED
MULTI_AGENT_GATEWAY_DEMO_PASSED
真实 CNI e2e（Fake IP、iptables REDIRECT 和节点数据面）应包含：
EGRESS_ALLOWED_BY_POLICY
CODING_AGENT_DEMO_PASSED
RAG_AGENT_DEMO_PASSED
DIRECT_BYPASS_DENIED_BY_ZEROPROXY
DNS 与 ClusterIP Service 为独立的主 CNI 兼容性检查，应包含：
MAIN_CNI_DNS_PASSED
MAIN_CNI_SERVICE_PASSED
MAIN_CNI_COMPAT_CHECKS_PASSED
网络与安全配置
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 策略代理
出口治理与审计
ZeroProxy 对出站流量按以下优先级处理：
deny → credential → allow → 默认拒绝
建议：
默认只允许业务真正需要访问的域名；
AgentNetworkPolicy 使用 Secret valueFrom.name/key 引用；Controller 将其转换为运行时 valueFromFile，不写入 Agent Pod；
对数据库、客户数据服务、Metadata 等敏感目标显式拒绝；
保留审计日志，并对异常 deny/credential 命中建立告警。
Direct Bypass
默认配置：
policy:
  directBypass:
    defaultAction: deny
建议保持默认拒绝，避免 Agent Pod 直连 Agent Fake-IP CIDR 内目标。其他 TCP 出站请求由 Egress 策略处理，未命中 Allow 或 Credential 规则时默认拒绝。
升级、卸载与回滚
升级
升级应遵循与安装相同的节点灰度原则：
1. 先在单节点 Canary 验证目标镜像和组件状态；
2. 运行 HTTP e2e 和真实 CNI e2e；
3. 再扩展到第二节点；
4. 确认双节点策略 reload、DNS/Service 与 rollback；
5. 再进入更多节点或更多地域。
升级前应记录当前 Addon 参数、策略 CR、AgentNetworkClass 和节点标签。
卸载
不能直接卸载 Addon 代替 CNI rollback。
正确顺序：
停止 agent-cni-installer
→ 在 Canary 节点执行 rollback-agent-cni
→ 检查宿主机残留
→ 移除 Canary 标签
→ 再卸载 Addon 或清理剩余组件
回滚残留检查
每个参与过 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 状态文件
故障排查
安装后 agent-cni-installer 未就绪
检查：
kubectl get pod -n tke-agent-network-real -o wide
kubectl describe pod -n tke-agent-network-real <installer-pod>
kubectl logs -n tke-agent-network-real <installer-pod>
常见原因：
现象
可能原因
处理方式
DaemonSet 为 0/0
节点未打 Canary 标签
仅对选定 Worker 添加 tke-agent-network.io/agent-cni-canary=true
Chart 渲染失败
未提供 serviceCIDRs
在 Installer 启用时传入集群真实 Service CIDR
ImagePullBackOff
镜像地址、公开权限或节点网络异常
核对团队镜像地址与节点拉取事件
preflight 失败
CNI 路径、端口或主机环境不满足要求
查看 Installer preflight 日志
Pod 创建提示 PriorityClass 不存在
资源创建顺序短暂竞态
等待 DaemonSet 自动重试；持续失败时检查 PriorityClass 是否创建。
DNS 或 ClusterIP Service 不通
检查：
iptables -t nat -S
iptables -t mangle -S
kubectl 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 是否正常。
AgentNetworkPolicy 长时间不是 Active
检查：
kubectl get agentnetworkpolicy -A -o wide
kubectl logs -n tke-agent-network-real deploy/agent-network-controller --tail=200
kubectl logs -n tke-agent-network-real ds/zeroproxy --tail=200
双 ZeroProxy 场景中，ConfigMap volume 投影可能短暂返回 409 policy version not yet projected。Controller 应重试并最终使 Policy 进入：
phase=Active
observedGeneration=<当前 generation>
rollback 后仍有节点残留
不要仅删除 Addon。重新执行 rollback 并分别登录每个 Canary Worker 检查网桥、iptables、CNI 二进制、CNI 配置和 state 目录。
常见问题
Q1：agent-network 会替换整个集群的主 CNI 吗？
不会。组件只在带 Canary 标签的目标 Worker 上为后续新建并调度到该节点的 Pod 接入 Agent CNI；当前不按 Pod Label 选择性接入，因此应使用专用 Canary 节点。Service 流量仍交由 kube-proxy 和主 CNI 处理。跳板机节点和未打标签的 Worker 不参与替换。
Q2：为什么必须提供 Service CIDR？
Agent CNI 会将除 Service 旁路外的 TCP 流量重定向到 ZeroProxy。如果无法识别 ClusterIP Service 地址，Service 流量可能被错误送入 HTTP 策略路径，影响 Kubernetes 服务通信。因此安装前必须提供真实 Service CIDR。
Q3：为什么需要单节点和双节点 Canary？
单节点用于先验证安装、CNI 接管和最小数据面；双节点用于验证不同 Fake IP CIDR 分配、跨节点组件运行、Service 兼容，以及多 ZeroProxy Pod 的策略 reload 恢复能力。
Q4：HTTP e2e 和真实 CNI e2e 的区别是什么？
HTTP e2e 使用 hostNetwork Job 直接访问本机 ZeroProxy，验证策略、凭证注入和代理逻辑。真实 CNI e2e 使用非 hostNetwork Pod，验证 Fake IP、agentcni0、节点 iptables REDIRECT 和 ZeroProxy 的完整数据面链路。两者都应通过。
Q5：卸载 Addon 后节点会自动恢复吗？
不保证。CNI 会修改宿主机网络状态，必须先执行 rollback 并完成残留检查；直接卸载 Addon 不可替代节点级回滚。
Q6：可以把测试用 token 和 upstream 直接用于生产吗？
不可以。完整 demo/e2e 使用的是测试 token、测试域名和本地测试 upstream。生产环境应接入真实业务上游、使用受控 Secret，并按最小权限配置策略。
参数与内部组件参考
常用安装参数
参数
类型
默认值
说明
canaryLabel.key
string
tke-agent-network.io/agent-cni-canary
选择 Canary 节点的标签 Key
canaryLabel.value
string
true
选择 Canary 节点的标签 Value
agentCNI.installerEnabled
bool
true
是否创建真实 CNI Installer DaemonSet
agentCNI.serviceCIDRs
string array
[]
集群真实 Service CIDR；Installer 启用时必填
agentCNI.fakeIPCIDR
string
169.254.77.0/24
当前仅参与 Chart 参数校验；未配置 NetworkClass 覆盖时，实际节点 CIDR 按节点名派生
agentCNI.zeroProxyPort
int
18080
TCP 重定向目标端口
zeroproxy.dnsProxy.listen
string
:18053
DNS Proxy 监听地址
zeroproxy.reload.enabled
bool
false
是否启用 Controller 到 ZeroProxy 的策略热加载认证接口
credentialUpstream.enabled
bool
false
是否部署测试用凭证验证上游
controller.enabled
bool
true
是否启用 CRD Controller
rollback.enabled
bool
false
是否渲染临时 CNI rollback DaemonSet
内部组件说明
层次
组件
职责
节点数据面
agent-cni-installer
安装/运行 Agent CNI，配置网桥、iptables、sysctl 和 CNI 状态。
节点数据面
agent-cni
由 kubelet 调用的真实 CNI 二进制，处理 Pod ADD/DEL/CHECK。
节点代理
zeroproxy
Egress、Ingress、Credential、DNS、Direct Bypass、审计和 metrics。
控制面
agent-network-controller
调和 AgentNetworkPolicy / AgentNetworkClass，更新 ConfigMap 并协调 reload。
测试依赖
credential-upstreams
完整 e2e 中验证凭证注入的受保护测试上游。
验证工具
agent-network-e2e
HTTP、真实 CNI、DNS/Service 和 Agent demo 验证 Job。
临时回滚组件
rollback-agent-cni
仅在 rollback.enabled=true 时运行，用于清理节点 CNI 数据面。
 
﻿

特点	说明
真实 CNI 接入	Agent CNI 为 Canary 节点上后续新建、使用主 CNI 的 Pod 配置 veth、`agentcni0` 网桥、Fake IP、默认路由和节点侧 iptables 规则。
强制流量收敛	UDP/53 流量重定向到节点 DNS Proxy；除命中 Service CIDR 并被标记旁路的流量外，TCP 流量重定向到 ZeroProxy。
默认拒绝	Egress、Ingress 和 Direct Bypass 支持默认拒绝；敏感 Metadata/CGNAT 地址具备内置拒绝保护。
凭证隔离	业务 Agent Pod 不挂载凭证；凭证保存在 Kubernetes Secret 中，由 ZeroProxy 在转发时读取和注入。
动态策略	`AgentNetworkPolicy` 支持策略声明；Controller 更新 ConfigMap 并触发 ZeroProxy 热加载。
Service 兼容	Service CIDR 流量使用 fwmark 交回 kube-proxy 和主 CNI，避免影响 Kubernetes ClusterIP Service。
灰度与回滚	仅带 Canary 标签的节点会安装 CNI；提供节点级 rollback 和宿主机残留检查。

概念	说明
Agent 工作负载	调度到启用 Agent CNI 的 Canary 节点、需要纳入网络治理的新建 Pod。当前以专用 Canary 节点为隔离边界，而非 Pod Label 选择器。
Canary 节点	带有 `tke-agent-network.io/agent-cni-canary=true` 标签、明确授权安装 Agent CNI 的 Worker 节点。
Agent CNI	负责 Fake IP、Pod 网络命名空间、veth、`agentcni0`、路由、状态文件与 iptables 规则的真实 CNI 插件。
Fake IP	Agent CNI 分配给 Agent Pod 的专用地址，不等同于主 CNI Pod IP；用于流量收敛和来源身份映射。
ZeroProxy	节点本地策略代理，监听 `:18080`，负责 Egress、Ingress、凭证注入、Direct Bypass、审计和指标。
DNS Proxy	ZeroProxy 的 UDP DNS 代理，默认监听 `:18053`，接收 Fake-IP Pod 的 DNS 请求。
Service CIDR	集群 Kubernetes Service 的地址范围。安装时必须提供，用于避免 ClusterIP Service 流量进入 HTTP 策略代理。
AgentNetworkPolicy	Namespaced CRD，声明 Egress Allow/Credential/Deny、Ingress 和 Direct Bypass 策略。
AgentNetworkClass	Cluster-scoped CRD，声明 Fake IP CIDR、Service CIDR、代理端口等节点基础网络参数；部分 API 字段当前仅下发记录，不触发数据面模式切换。
CNI State	Agent CNI 持久化的 Pod 网络/身份状态，ZeroProxy 可据此将 Fake IP 映射回 Pod 身份。
Direct Bypass	Agent Pod 直接访问 Agent Fake-IP CIDR 内目标地址、试图绕过受控入口的行为；默认拒绝。其他 TCP 出站请求仍由 Egress 策略处理。

维度	普通 Pod 网络	agent-network
出站访问	应用可直接访问网络可达目标	由 ZeroProxy 统一执行 Allow、Credential、Deny
凭证管理	常将 Secret 注入业务 Pod	凭证仅挂载给 ZeroProxy，按规则转发时注入
DNS	使用主 CNI/集群默认 DNS 路径	Fake-IP Pod 的 DNS 经节点本地 DNS Proxy 统一处理
Agent 间调用	依赖业务自行鉴权	支持 Caller/Target 规则及 Fake-IP 来源身份校验
绕过控制	Pod 可能尝试直连目标	节点 iptables 强制收敛，Direct Bypass 默认拒绝
审计	日志分散在业务系统	ZeroProxy 统一输出策略命中与访问审计
节点变更	无 CNI 变更	CNI 变更需 Canary 和可验证 rollback

维度	Sidecar 代理	agent-network
接入方式	每个 Pod 注入代理容器	节点级 Agent CNI + ZeroProxy
业务改造	可能需要改造 Deployment/Pod 模板	Agent 应用无需感知本地代理地址
资源占用	每个 Pod 一份代理资源	每个 Canary 节点一份 ZeroProxy
流量接管	多依赖 Pod 内重定向和注入逻辑	由 CNI 和节点 iptables 在网络路径中强制接管
凭证位置	可能同时存在于业务 Pod 和 Sidecar	凭证仅保留在 ZeroProxy 所挂载 Secret
风险范围	主要影响单个工作负载	涉及节点 CNI，必须严格按灰度和回滚流程操作

项目	说明
当前版本	Addon / Chart `0.3.0`
发布形态	TKE Addon / Helm Chart
发布状态	灰度发布阶段；实际可安装地域和版本以 TKE Addon 控制台展示为准。
支持集群类型	TKE 托管集群（MANAGED_CLUSTER）
Kubernetes 版本	Chart 声明 `>= 1.20.0-0`
节点系统	Linux
节点架构	当前 Chart 面向 amd64 节点。
主 CNI 兼容性	已在 TKE ENI / Multus 环境完成真实集群验证；安装必须提供实际 Service CIDR。
策略协议	HTTP；TLS SNI 透传能力默认关闭，未配置可信 DNS/身份校验时不建议开启。
是否计费	组件不单独收费，但会占用目标节点 CPU、内存、网络和日志存储资源。

验证层次	验证内容
HTTP e2e	ZeroProxy 的 Allow、Credential、Deny、Ingress allow/deny、Coding/RAG/Gateway demo
真实 CNI e2e	Fake-IP Pod、iptables REDIRECT、Coding、RAG、Direct Bypass deny
主 CNI 兼容	DNS、ClusterIP Service
控制面	双 ZeroProxy ConfigMap projection/reload、`AgentNetworkPolicy` 最终 `Active`
安全与可观测	审计日志不泄露凭证、metrics 可访问

现象	可能原因	处理方式
DaemonSet 为 `0/0`	节点未打 Canary 标签	仅对选定 Worker 添加 `tke-agent-network.io/agent-cni-canary=true`
Chart 渲染失败	未提供 `serviceCIDRs`	在 Installer 启用时传入集群真实 Service CIDR
ImagePullBackOff	镜像地址、公开权限或节点网络异常	核对团队镜像地址与节点拉取事件
preflight 失败	CNI 路径、端口或主机环境不满足要求	查看 Installer preflight 日志
Pod 创建提示 PriorityClass 不存在	资源创建顺序短暂竞态	等待 DaemonSet 自动重试；持续失败时检查 PriorityClass 是否创建。

参数	类型	默认值	说明
`canaryLabel.key`	string	`tke-agent-network.io/agent-cni-canary`	选择 Canary 节点的标签 Key
`canaryLabel.value`	string	`true`	选择 Canary 节点的标签 Value
`agentCNI.installerEnabled`	bool	`true`	是否创建真实 CNI Installer DaemonSet
`agentCNI.serviceCIDRs`	string array	`[]`	集群真实 Service CIDR；Installer 启用时必填
`agentCNI.fakeIPCIDR`	string	`169.254.77.0/24`	当前仅参与 Chart 参数校验；未配置 NetworkClass 覆盖时，实际节点 CIDR 按节点名派生
`agentCNI.zeroProxyPort`	int	`18080`	TCP 重定向目标端口
`zeroproxy.dnsProxy.listen`	string	`:18053`	DNS Proxy 监听地址
`zeroproxy.reload.enabled`	bool	`false`	是否启用 Controller 到 ZeroProxy 的策略热加载认证接口
`credentialUpstream.enabled`	bool	`false`	是否部署测试用凭证验证上游
`controller.enabled`	bool	`true`	是否启用 CRD Controller
`rollback.enabled`	bool	`false`	是否渲染临时 CNI rollback DaemonSet

层次	组件	职责
节点数据面	`agent-cni-installer`	安装/运行 Agent CNI，配置网桥、iptables、sysctl 和 CNI 状态。
节点数据面	`agent-cni`	由 kubelet 调用的真实 CNI 二进制，处理 Pod ADD/DEL/CHECK。
节点代理	`zeroproxy`	Egress、Ingress、Credential、DNS、Direct Bypass、审计和 metrics。
控制面	`agent-network-controller`	调和 `AgentNetworkPolicy` / `AgentNetworkClass`，更新 ConfigMap 并协调 reload。
测试依赖	`credential-upstreams`	完整 e2e 中验证凭证注入的受保护测试上游。
验证工具	`agent-network-e2e`	HTTP、真实 CNI、DNS/Service 和 Agent demo 验证 Job。
临时回滚组件	`rollback-agent-cni`	仅在 `rollback.enabled=true` 时运行，用于清理节点 CNI 数据面。

agent-network 组件说明

本页目录：

组件介绍

与 Kubernetes 的结合

核心概念

产品优势

对比普通 Kubernetes Pod 网络

对比 Sidecar 代理

典型使用场景

Coding Agent 访问代码仓库

RAG Agent 访问向量数据库

Multi-Agent 调用治理

防止访问敏感地址

产品状态与支持范围

使用限制

安装前准备

1. 规划节点角色

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

3. 确认 Service CIDR

4. 准备回滚窗口

安装 agent-network

方式一：控制台安装

方式二：通过 API 安装

安装后验证

1. 查看组件状态

2. 查看真实 CNI 安装状态

3. 运行内置诊断

4. 验证 HTTP e2e 与真实 CNI e2e

网络与安全配置

Fake IP 与 Service CIDR

出口治理与审计

Direct Bypass

升级、卸载与回滚

升级

卸载

回滚残留检查

故障排查

安装后 agent-cni-installer 未就绪

DNS 或 ClusterIP Service 不通

AgentNetworkPolicy 长时间不是 Active

rollback 后仍有节点残留

常见问题

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

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

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

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

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

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

参数与内部组件参考

常用安装参数

内部组件说明

安装后 `agent-cni-installer` 未就绪

`AgentNetworkPolicy` 长时间不是 `Active`