简介：面向 Kubernetes 运维与云原生网络学习者，这份 docx 文档系统梳理了 CNCF 沙盒项目 Kube-OVN 的整体架构与落地要点，适合希望从 SDN 视角理解容器网络、或计划在生产环境部署 Kube-OVN 的中高级读者参考。资源包共 1 个 docx 文件，约 1.77MB，内容围绕项目介绍、安装流程、组件详解与功能验证展开。文档先说明 Kube-OVN 在子网管理、静态 IP 分配、VPC 多租户、跨集群互联、QoS 与 ACL 等方面的丰富能力，再介绍其数据面与控制面的性能优化思路，以及一键安装脚本和监控运维工具。组件部分重点拆解 ovn-central、ovn-nb、ovn-sb、ovn-northd 等上游 OVN/OVS 组件，kube-ovn-controller、kube-ovn-cni 等核心控制器与 Agent，以及 speaker、pinger、monitor、kubectl-ko 等扩展工具，并给出 LoadBalancer、EIP/SNAT、集中式网关、Pod 级 QoS 等验证项。已有 433 人学习，便于快速建立组件认知与排错思路。
1. 装完就翻车：Pod 卡在 ContainerCreating，报错指向网卡名对不上
Kube-OVN 装完那一刻往往是最容易让人误判的时刻：kubectl get pod -A一片 Running，你以为网络已经就绪，结果随手起一个业务 Pod，状态死死停在ContainerCreating，kubectl describe pod里翻来覆去就是那几行 CNI 报错。这类故障在 Kubernetes 集群里极其常见，折腾人的地方在于它不报“网络不通”，而是报“配置找不到”，新手容易往镜像、调度、kubelet 上猜，熟手则知道要先看 CNI 插件到底卡在哪一步。这篇笔记面向正在被 Kube-OVN 安装后各类报错卡住的开发者，把 LoadBalancer、子网、多网卡这几条高频故障线拆开，每条都落到能直接抄的命令和配置上。
2. ContainerCreating 卡死：三类 CNI 报错与根因定位
Kube-OVN 的 Pod 创建链路比普通 CNI 长：kubelet 调 CNI 二进制，二进制把请求转给节点上的 kube-ovn-cni，后者再去操作 OVS、写 iptables、配 ovn0。链路上任何一环配置对不上，Pod 就停在ContainerCreating。下面三类报错是安装后最常撞上的，现象相似但根因完全不同，必须分开定位。
2.1 网卡名写死 eth0：failed to find interface eth0的根因
原文里问题三描述得很典型：创建子网需要部署 config-map，其中Master字段指定物理网卡，而虚拟机网卡实际是ens33，配置里却写了eth0，于是 Pod 直接报错。根因是 Kube-OVN 在 Underlay 或需要绑定物理网卡的场景下，会按配置里的网卡名去宿主机上找对应设备，找不到就拒绝继续，因为后续的 vlan、underlay、EIP 都依赖这块真实网卡。
先确认宿主机上到底有哪些网卡，别凭记忆写：
# 在目标节点上执行，列出所有物理网卡名 ip -o link show | awk -F': ' '{print $2}' | grep -v -E 'lo|veth|ovs|br-|ovn' # 确认默认路由走的是哪块网卡 ip route show default拿到真实网卡名后，改 config-map 里的Master字段：
apiVersion: v1 kind: ConfigMap metadata: name: ovn-vpc-nat-config namespace: kube-system data: # 关键：必须与宿主机实际网卡名一致，CentOS 7 常见为 ens33 / ens192 Master: "ens33"改完不是立刻生效，需要让相关组件重新读取配置。常见做法是重启对应 Deployment 或删除重建相关 Pod，让 kube-ovn-controller 重新下发。参数说明：Master只填网卡名，不要带/sys/class/net/前缀；如果节点有多块网卡，选承载业务流量的那块，选错会导致出网流量走错路径，表现为“能创建但访问外网不通”。
2.2 LoadBalancer 的 test-pod 卡在 ContainerCreating：镜像与 macvlan 依赖
原文问题二写得很清楚：LoadBalancer 安装后会自动拉起一个 test-pod，初次安装是 Running，把 LB 配置 delete 再重新部署，pod 就变成ContainerCreating，报错与创建 LB 时相似。这类“第一次好、重建就坏”的现象最容易让人怀疑玄学，实际根因通常有两个方向。
第一个方向是依赖没就绪。原文明确写了 LoadBalancer 依赖 multus-cni 和 macvlan cni 提供多网卡能力，还依赖 vpc-nat-gw 镜像。重建时如果 macvlan 的 NetworkAttachmentDefinition 还没建好，或者镜像在节点上被清理、拉取失败，test-pod 就会卡住。先查事件和镜像：
# 看 test-pod 到底卡在哪一步 kubectl describe pod -n kube-system -l app=ovn-lb | tail -30 # 确认节点上 vpc-nat-gw 镜像是否存在 docker images | grep vpc-nat-gw # 确认 multus 与 macvlan 的 NAD 是否就绪 kubectl get network-attachment-definitions -A第二个方向是配置残留。delete 再部署时，旧的 macvlan 网卡、旧的 OVS 端口可能没清干净，新 pod 绑定时冲突。我一般会先删干净再重建：
# 删除 LB 相关资源后，确认节点上没有残留的 macvlan 接口 ip link show type macvlan # 如有残留，手动清理（示例名，按实际输出替换） ip link delete net1参数说明：ip link show type macvlan只列 macvlan 类型接口，避免误删业务网卡；清理前务必确认该接口确实属于已删除的 LB，不要对正在运行的 Pod 网卡动手。判断标准很简单——重建后describe里如果报的是镜像拉取失败，走第一个方向；如果报的是接口已存在或绑定失败，走第二个方向。
2.3 多网卡地址管理报错：网卡名与 CNI 配置不一致
原文 4.8 节的问题 1 和问题 2 是同一类故障的两次翻车：部署后容器状态ContainerCreating，报错与创建 LB 相似；把配置里的网卡改成当前网卡后，又报另一个错。根因是多网络插件地址管理场景下，Kube-OVN 为 macvlan、vlan、host-device 等插件提供集群级 IPAM，但每个附加网络的配置里都写死了网卡名和子网，任何一处与实际环境不符都会让 Pod 创建中断。
排查顺序建议固定下来，别跳步：
# 第一步：看 Pod 的完整事件，定位是哪个附加网络失败 kubectl describe pod <pod-name> -n <namespace> | grep -A5 -i "failed\|error" # 第二步：列出该 Pod 声明的所有网络附件 kubectl get pod <pod-name> -n <namespace> -o jsonpath='{.metadata.annotations}' # 第三步：核对 NAD 里的网卡名与子网是否与节点实际一致 kubectl get network-attachment-definition <nad-name> -n <namespace> -o yaml参数说明：jsonpath取 annotations 是为了看 multus 实际注入了哪些网络；NAD 里的master字段对应宿主机网卡，subnet对应 Kube-OVN 子网 CIDR，两者任一写错都会复现原文的报错。改完 NAD 后，已存在的 Pod 不会自动更新，必须删除重建，这一点原文没展开，但实际排查中十有八九是漏了重建。
3. 子网与网关配置：从默认子网到集中式网关的踩坑路径
子网是 Kube-OVN 的核心使用单元，Namespace 归属哪个子网，Pod 就从哪个子网拿 IP 并继承 CIDR、网关类型、NAT 控制等配置。原文特别强调它和“每节点绑一个子网”的 CNI 不同，子网是全局虚拟网络配置，同一子网地址可以分布在任意节点。这个设计带来灵活性的同时，也让配置错误的传播范围变大——一个子网配错，挂在上面的所有 Namespace 一起出问题。
3.1 默认子网与 join 子网：ovn0 不通导致节点访问 Pod 失败
原文说得很清楚：Overlay 模式下 Kube-OVN 创建 join 子网，并在每个节点建一块ovn0虚拟网卡接入 join 子网，用来完成节点和 Pod 的互通。Kubernetes 网络规范要求 Node 能直接访问所有 Pod，这条链路断了，表现就是节点上curlPod IP 不通，但 Pod 之间互访正常。
先确认 ovn0 是否存在、是否有地址：
# 每个节点上都应有 ovn0，且带 join 子网地址 ip addr show ovn0 # 从节点直接访问某个 Pod IP，验证 join 链路 curl -s --max-time 3 <pod-ip>:<port>如果ovn0不存在，说明 kube-ovn-cni 没完成初始化，去看该节点 DaemonSet Pod 的日志；如果存在但地址不对，检查 join 子网的 CIDR 是否与节点其他网段冲突。常见做法是给 join 子网单独规划一个不与物理网络重叠的网段，冲突时表现为路由表里出现两条指向不同设备的同网段路由，ip route get <pod-ip>能直接看出走了哪条。
3.2 集中式网关：natOutgoing 为 true 时出网 IP 为何不是预期
原文 4.3 节描述：希望子网内流量访问外网使用固定 IP 以便审计和白名单，就把子网网关类型设为集中式网关。此时 Pod 出网数据包先路由到特定节点的ovn0，再走主机路由出网；natOutgoing为 true 时，Pod 访问外部网络使用特定宿主机的 IP。翻车点在于——很多人以为设了集中式网关就自动固定 IP，实际还要确认natOutgoing和网关节点选择。
apiVersion: kubeovn.io/v1 kind: Subnet metadata: name: centralized-subnet spec: cidrBlock: "10.16.0.0/16" # 集中式网关：出网流量汇聚到指定节点 gatewayType: centralized gatewayNode: "node-a" # 关键开关：为 true 才会对出网流量做 SNAT natOutgoing: true vpc: "ovn-cluster"参数说明：gatewayNode必须是集群内真实节点名，写错会导致子网一直处于未就绪；natOutgoing为 false 时 Pod 出网不带源地址转换，外部看到的是 Pod IP，多数物理网络不会回程，表现为“能出去、回不来”。验证方式是在 Pod 内访问外部地址，同时在网关节点抓包看源 IP 是否为该节点地址。原文的 yaml 示例和运行结果就是按这个逻辑验证的，照做即可。
3.3 静态 IP 与 QoS 注解：改完不生效的两个隐藏条件
原文 4.4 和 4.5 节分别验证静态路由和 Pod 级 QoS，QoS 部分给了明确命令：kubectl annotate --overwrite pod perf-n5jhn -n ls1 ovn.kubernetes.io/ingress_rate=30。这类注解改完不生效，通常卡在两个隐藏条件上。
第一，注解必须打在 Pod 上且 Pod 已由 Kube-OVN 接管，打在 Deployment 模板上不会自动同步到已运行的 Pod。第二，QoS 的入口和出口是分开的注解，只改ingress_rate不影响出方向：
# 入口限速，单位 Mbps kubectl annotate --overwrite pod <pod-name> -n <ns> ovn.kubernetes.io/ingress_rate=30 # 出口限速，需要单独设置 kubectl annotate --overwrite pod <pod-name> -n <ns> ovn.kubernetes.io/egress_rate=30 # 确认注解已写入 kubectl get pod <pod-name> -n <ns> -o jsonpath='{.metadata.annotations}'参数说明：--overwrite不能省，否则重复设置会报已存在；数值单位按 Kube-OVN 约定为 Mbps，写 30 表示 30Mbps 而非 30MB/s，验证时用iperf测出的吞吐要和这个单位对齐，否则会误判“没生效”。原文的验证方式是改接收 Pod 的入口速率后对比请求结果，这个思路可以直接复用。
4. 避坑清单：五条血泪经验对应的现象与解法
4.1 网卡名照抄文档，换环境就报错
现象：按文档配好Master: eth0，Pod 卡ContainerCreating，报找不到接口。原因：文档环境网卡名与你的虚拟机或物理机不一致，CentOS 7 常见ens33、ens192。解决：先ip -o link show确认真实网卡名再改 config-map，改完重建相关组件，别只改不重启。
4.2 LB 重建后 test-pod 起不来，误判为镜像问题
现象：首次安装正常，delete 再部署后 test-pod 一直ContainerCreating。原因：多数是 macvlan NAD 未就绪或旧接口残留，不一定是镜像拉不到。解决：先kubectl describe看事件，再ip link show type macvlan查残留，清理后重建；确认 multus 与 macvlan 已安装再部署 LB。
4.3 子网 CIDR 与物理网段重叠，路由打架
现象：Pod 能创建，但访问某些地址时通时不通。原因：子网 CIDR 与宿主机物理网段重叠，路由表出现歧义。解决：ip route get <目标IP>确认实际走向，重新规划不重叠的 CIDR；join 子网尤其要单独规划。
4.4 注解改了 QoS 没反应，以为功能坏了
现象：kubectl annotate执行成功，限速不生效。原因：只设了入口没设出口，或注解打在模板而非运行中的 Pod 上。解决：入口出口分别设置，确认注解落在 Pod 的 annotations 里，用iperf按 Mbps 单位核对。
4.5 多网卡场景只改一处配置
现象：多网络插件地址管理报错，改完网卡名又冒出新错误。原因：NAD、子网、Pod 注解多处配置需同时一致，改一处不够。解决：按“Pod 事件 → annotations → NAD → 子网”顺序逐层核对，改完删除重建 Pod，已运行 Pod 不会自动继承新配置。
5. 快速定位：把排查顺序固化成习惯
Kube-OVN 的报错有个共同特征：表面看都是ContainerCreating，实际根因分散在网卡、镜像、NAD、子网、注解五个层面。想快速定位，核心不是背命令，而是固定一条从外到内的排查顺序，每次故障都走一遍，别凭感觉跳步。
我一般按这个顺序走：第一步kubectl describe pod看事件，确认卡在 CNI 的哪个动作；第二步看节点侧ip link、ip addr show ovn0，确认物理网卡和 join 网卡状态；第三步核对 NAD 与子网配置是否与实际环境一致；第四步才去看镜像和组件日志。这个顺序的价值在于，前两步能覆盖大部分配置类故障，避免一上来就翻组件日志浪费时间。
下面这张对照表可以贴在排查笔记里，遇到报错先对号入座：
| 报错关键词 | 最可能根因 | 首个排查命令 |
|---|---|---|
failed to find interface | 网卡名与宿主机不符 | ip -o link show |
ContainerCreating且事件含 macvlan | NAD 未就绪或接口残留 | kubectl get network-attachment-definitions -A |
| 节点访问 Pod 不通 | ovn0 缺失或 join 子网冲突 | ip addr show ovn0 |
| 出网源 IP 不是预期 | natOutgoing未开或网关节点错 | kubectl get subnet <name> -o yaml |
| 限速不生效 | 注解方向或对象错误 | kubectl get pod -o jsonpath='{.metadata.annotations}' |
验证环节同样要固化。改完配置后，别只看 Pod 是否 Running，要实际验证链路：节点curlPod IP 验证 join 子网，Pod 内访问外部地址验证 NAT，iperf验证 QoS，抓包验证流量镜像。原文 4.6 节流量镜像的验证方式就是“向容器内发包、在网卡上抓包”，这个思路适用于所有网络功能——功能是否生效，以抓到的包为准，不以状态为准。
提示：流量镜像会带来约 5%~10% 的额外 CPU 消耗，验证完记得关掉，别留在生产环境里长期跑。
从那以后我每次装完 Kube-OVN，都强制先跑一遍“起 Pod → 节点访问 Pod → Pod 出网 → 抓包”四步验证，再往上叠 LoadBalancer 和子网功能，配置类报错基本在第一步就暴露了。希望帮到你。
本文还有配套的精品资源，点击获取
