简介面向 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状态死死停在ContainerCreatingkubectl 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 网卡名写死 eth0failed 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 appovn-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 级 QoSQoS 部分给了明确命令kubectl annotate --overwrite pod perf-n5jhn -n ls1 ovn.kubernetes.io/ingress_rate30。这类注解改完不生效通常卡在两个隐藏条件上。第一注解必须打在 Pod 上且 Pod 已由 Kube-OVN 接管打在 Deployment 模板上不会自动同步到已运行的 Pod。第二QoS 的入口和出口是分开的注解只改ingress_rate不影响出方向# 入口限速单位 Mbps kubectl annotate --overwrite pod pod-name -n ns ovn.kubernetes.io/ingress_rate30 # 出口限速需要单独设置 kubectl annotate --overwrite pod pod-name -n ns ovn.kubernetes.io/egress_rate30 # 确认注解已写入 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: eth0Pod 卡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确认实际走向重新规划不重叠的 CIDRjoin 子网尤其要单独规划。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 showContainerCreating且事件含 macvlanNAD 未就绪或接口残留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 内访问外部地址验证 NATiperf验证 QoS抓包验证流量镜像。原文 4.6 节流量镜像的验证方式就是“向容器内发包、在网卡上抓包”这个思路适用于所有网络功能——功能是否生效以抓到的包为准不以状态为准。提示流量镜像会带来约 5%~10% 的额外 CPU 消耗验证完记得关掉别留在生产环境里长期跑。从那以后我每次装完 Kube-OVN都强制先跑一遍“起 Pod → 节点访问 Pod → Pod 出网 → 抓包”四步验证再往上叠 LoadBalancer 和子网功能配置类报错基本在第一步就暴露了。希望帮到你。本文还有配套的精品资源点击获取
