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 和宿主机残留检查。 |
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 承载策略、上游地址和凭证引用。Agent Pod eth0(Fake IP)→ 默认路由→ agentcni0 网桥→ 宿主机 iptables PREROUTING├── UDP/53 → REDIRECT 到 ZeroProxy DNS :18053├── Service CIDR → fwmark 后交回 kube-proxy / 主 CNI└── TCP → REDIRECT 到 ZeroProxy :18080→ 策略匹配、身份校验、凭证注入、审计→ 目标服务
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 策略处理。 |
维度 | 普通 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,必须严格按灰度和回滚流程操作 |
Authorization 请求头。apiVersion: agent.tke.cloud.tencent.com/v1alpha1kind: AgentNetworkPolicymetadata:name: coding-agent-networknamespace: tke-agent-network-realspec:podSelector: {}priority: 100egress:allow:- name: public-githost: git.example.comprotocol: tcpport: 443credential:- name: private-githost: git.internal.example.comheader: AuthorizationvalueFrom:name: zeroproxy-credentialskey: REPO_TOKENdeny:- name: production-dbhost: prod-db.internaldirectBypass:defaultAction: deny
tke-agent-network-real)。业务 Pod 可以位于其他命名空间,但 AgentNetworkPolicy 需创建在 Controller 的监听命名空间。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"
169.254.169.254/32100.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、内存、网络和日志存储资源。 |
SO_ORIGINAL_DST。agentCNI.installerEnabled 默认启用;只有带 Canary 标签的节点才会调度 Installer 并发生 CNI 变更。agentCNI.installerEnabled=true 时,agentCNI.serviceCIDRs 是必填安装参数;未提供时 Chart 将拒绝渲染。仅安装控制面且显式关闭 Installer 时可不配置。agentCNI.fakeIPCIDR 的 Chart 默认值为 169.254.77.0/24,但当前不会作为 Installer 的实际 CIDR 下发参数;未配置 AgentNetworkClass 覆盖时,Installer 按节点名派生节点级 /24 CIDR。实际分配地址必须避免与节点、Pod、Service、VPC 和其他基础设施网段冲突。18080/TCP,DNS Proxy 使用 18053/UDP;安装前应确认目标节点端口没有冲突。AgentNetworkPolicy 使用 valueFrom.name/key 引用已挂载到 ZeroProxy 的 Secret;Controller 会将其转换为运行时策略中的 valueFromFile。不支持 valueFromEnv。zeroproxy.tls.allowUnverifiedSNI 默认关闭;无可信 DNS 或身份校验能力时不建议启用。podSelector / workloadSelector 不是 Pod 级 CNI 接入开关,因此 Canary 节点应保持为专用节点。AgentNetworkPolicy.spec.podSelector 与 AgentNetworkClass.spec.workloadSelector 已进入 API,但当前不作为 Pod 级选择性 CNI 接入开关;现阶段以专用 Canary 节点作为工作负载隔离边界。AgentNetworkClass.spec.proxy.failMode 与 spec.cni.defaultConnectivity 当前为 API/下发字段;v0.3.0 数据面仍按 Fail-Close / ZeroConnectivity 运行,不能依赖 FailOpen 自动直连。0.3.0 / v0.3.0;当前 Agent CNI 节点版本记录可能仍显示 v0.2.5。该问题不影响已验证的数据面功能,但会影响版本追踪和升级诊断,需后续修复并复验。kubectl get node -o widekubectl get pod -A -o wide
kubectl label node <第一台-worker节点名> \\tke-agent-network.io/agent-cni-canary=true
kubectl label node <第二台-worker节点名> \\tke-agent-network.io/agent-cni-canary=true
kubectl get svc -A \\-o jsonpath='{range .items[*]}{.spec.clusterIP}{"\\n"}{end}' \\| grep -v -E '^(None|<none>|)$' \\| sort -u \\| head
192.168.x.x 时,常见 Service CIDR 为:192.168.0.0/16
agent-network。0.3.0。agentCNI:serviceCIDRs:- <真实 Service CIDR>
InstallAddon 接口。基础安装 JSON 示例:{"Region": "ap-<region>","ClusterId": "cls-xxxxxxxx","AddonName": "agent-network","AddonVersion": "0.3.0","RawValues": "{\\"agentCNI\\":{\\"serviceCIDRs\\":[\\"<真实 Service CIDR>\\"]}}"}
image.registry、image.tag 或组件 repository。credentialUpstream.enabled=true。credentials.repoToken 与 credentials.ragToken。zeroproxy.reload.enabled=true,并必须设置非空的 zeroproxy.reload.token。zeroproxy.upstreams 的测试映射。credentials.* 和 reload token 渲染为组件 Secret,因此完整 demo/e2e 的 token 只能在隔离测试环境中通过受控 API 请求传入;不得将生产凭证写入 RawValues、命令行、示例文件或终端历史。启用 credential-upstreams 后,该测试组件会从 Secret 读取期望 token 以验证注入结果;这不改变“业务 Agent Pod 不挂载凭证”的产品边界。tke-agent-network-real 为例:kubectl get ds,deploy,pod -n tke-agent-network-real -o wide
agent-cni-installer 1/1 Readyzeroproxy 1/1 Readyagent-network-controller 1/1 Ready
credential-upstreams 1/1 Ready
agent-cni-installer、zeroproxy、credential-upstreams 三个 DaemonSet 均预期为 2/2 Ready;默认安装时检查前两个 DaemonSet 为 2/2 Ready。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 \\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
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
验证层次 | 验证内容 |
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 可访问 |
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
EGRESS_ALLOWED_BY_POLICYCODING_AGENT_DEMO_PASSEDRAG_AGENT_DEMO_PASSEDDIRECT_BYPASS_DENIED_BY_ZEROPROXY
MAIN_CNI_DNS_PASSEDMAIN_CNI_SERVICE_PASSEDMAIN_CNI_COMPAT_CHECKS_PASSED
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 策略代理
deny → credential → allow → 默认拒绝
AgentNetworkPolicy 使用 Secret valueFrom.name/key 引用;Controller 将其转换为运行时 valueFromFile,不写入 Agent Pod;policy:directBypass:defaultAction: deny
停止 agent-cni-installer→ 在 Canary 节点执行 rollback-agent-cni→ 检查宿主机残留→ 移除 Canary 标签→ 再卸载 Addon 或清理剩余组件
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 widekubectl 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 是否创建。 |
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 是否正常。AgentNetworkPolicy 长时间不是 Activekubectl 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
409 policy version not yet projected。Controller 应重试并最终使 Policy 进入:phase=ActiveobservedGeneration=<当前 generation>
hostNetwork Job 直接访问本机 ZeroProxy,验证策略、凭证注入和代理逻辑。真实 CNI e2e 使用非 hostNetwork Pod,验证 Fake IP、agentcni0、节点 iptables REDIRECT 和 ZeroProxy 的完整数据面链路。两者都应通过。参数 | 类型 | 默认值 | 说明 |
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 数据面。 |
フィードバック