Calico v3.20.6 离线部署实战：镜像导入、yaml 调参与避坑指南-北京尧图网络

简介面向 Kubernetes 运维与云原生网络实践者的 Calico v3.20.6 离线部署资源包适合需要在内网或受限环境中快速搭建容器网络、实施网络策略的中高级用户。压缩包共 5 个文件约 96.68MB由 4 个 tar 镜像包与 1 个 yaml 配置文件组成镜像涵盖节点代理、CNI 插件、控制器及 FlexVol 插件分别承担 Pod IP 分配与 BGP 路由、网络接口配置、策略与地址管理、配置挂载等职责calico.yaml 则集中定义 DaemonSet、CNI 集成、策略控制器与 BGP 参数可直接用于集群部署。已有 1088 人学习下载说明其在离线安装场景中具备一定参考价值。读者可据此获得一套版本匹配、开箱即用的 Calico 组件集合省去逐个拉取镜像的麻烦并借助核心配置文件理解各组件协作关系为网络隔离与多租户安全策略落地提供基础。1. 装 Calico 前先想清楚为什么 v3.20.6 这个版本值得单独留一份镜像上周帮一个朋友救火他的 Kubernetes 集群节点全部 NotReadykubectl 一看calico-node 的 Pod 卡在 ImagePullBackOff 已经两天了。问题不在配置在于他用的镜像仓库地址在集群里根本拉不动而手上又没有一份能离线导入的镜像包。这种场景太常见了——Calico 作为 Kubernetes 最主流的 CNI 之一装的时候觉得一条 kubectl apply 就完事真出问题的时候才发现镜像拉不到、yaml 里的网段和实际环境对不上、版本和 K8s 对不齐每一个都能让整个集群瘫掉。calico-v3.20.6 这个版本配套的容器镜像加 calico.yaml 文件解决的就是这个落地问题把镜像和清单都攥在手里装的时候不依赖外网坏了能回滚迁移能复现。这篇笔记按我实际部署的顺序走一遍从版本选择、镜像导入、yaml 改参数到装完验证新手能照着跑通熟手能看到几个容易翻车的参数取舍。2. 环境准备与版本对齐calico v3.20.6 到底配什么2.1 先确认 K8s 版本和内核条件Calico v3.20.6 是 3.20 分支的补丁版本这个分支对应的 Kubernetes 兼容范围大致是 1.19 到 1.22。我一般不会拿它去配 1.24 以上的集群原因很实际1.24 之后 dockershim 被移除容器运行时切到 containerd而 Calico 的安装清单里对运行时 socket 路径、cni 配置目录的假设会变v3.20.6 的默认 yaml 没有覆盖这些新路径硬上就是给自己找事。所以第一步不是急着下载而是先把环境底账列清楚。检查项命令合格标准K8s 版本kubectl version --shortServer 在 v1.19–v1.22节点内核uname -r4.9 以上推荐 5.x容器运行时kubectl get nodes -o wide确认是 docker 还是 containerd网卡名ip addr记下主网卡名后面要填Pod 网段看 kube-controller-manager 启动参数记下--cluster-cidr的值这张表看着简单但每一项后面都对应一个坑。比如容器运行时这一项如果是 containerd那 calico-node 的 DaemonSet 里挂载的 socket 路径就得从/var/run/docker.sock改成/run/containerd/containerd.sockv3.20.6 的默认清单是按 docker 写的不改就是 CrashLoopBackOff。再比如 Pod 网段Calico 的CALICO_IPV4POOL_CIDR必须和 kube-controller-manager 的--cluster-cidr一致不一致的后果是新 Pod 拿到 IP 但跨节点不通排查起来非常费劲。2.2 镜像清单和文件结构先过一遍这份资源里核心是两部分一组容器镜像以及 calico.yaml 清单文件。镜像通常包括calico/node、calico/cni、calico/kube-controllers这几个v3.20.6 对应的镜像 tag 就是v3.20.6。我习惯在导入前先docker load或者ctr images import逐个过一遍确认镜像完整、tag 没被改过。清单文件方面calico.yaml 里包含 DaemonSet、Deployment、ServiceAccount、ClusterRole、CRD 等一整套对象装之前至少要知道它会在集群里创建哪些东西不然出了问题连删都删不干净。# 查看镜像包内容确认 tag 和架构 docker load -i calico-v3.20.6-images.tar docker images | grep calico # 如果是 containerd 运行时用 ctr 导入 ctr -n k8s.io images import calico-v3.20.6-images.tar ctr -n k8s.io images ls | grep calico这里的关键点是命名空间。用ctr导入时必须指定-n k8s.io因为 kubelet 是从这个命名空间里找镜像的导到 default 命名空间等于白导。这个坑我见过不止一次镜像明明导进去了Pod 还是 ImagePullBackOff最后发现是命名空间不对。docker 运行时没这个问题docker load之后 kubelet 直接能识别。2.3 节点预检别等装到一半才发现条件不满足正式动手前我会在每个节点上跑一遍预检。Calico 对内核模块有依赖尤其是ip_tables、ip6_tables、nf_conntrack这几个缺了会导致 calico-node 起不来或者网络规则下发失败。另外防火墙规则也要看一眼如果节点上开了 firewalld 或者 iptables 有 DROP 策略Calico 的 BGP 端口 179 和 VXLAN 端口 4789 可能被拦。# 检查内核模块 lsmod | grep -E ip_tables|nf_conntrack # 缺模块就加载 modprobe ip_tables modprobe nf_conntrack # 检查防火墙状态 systemctl status firewalld iptables -L -n | head -20如果 firewalld 是开着的常见做法是给 Calico 放行必要端口或者干脆在测试环境关掉。生产环境我一般倾向于放行而不是关防火墙具体是firewall-cmd --add-port179/tcp、4789/udp这几条。这一步不做装完之后节点之间 ping 不通 Pod IP你会以为是 Calico 配错了其实是防火墙在中间挡着。3. 导入镜像与改 calico.yaml参数一个都不能想当然3.1 镜像导入的两种路径和验证方法镜像导入分两种情况取决于集群用的是 docker 还是 containerd。docker 环境下docker load就够了containerd 环境下必须用ctr -n k8s.io images import。导入完之后不要急着 apply先验证一下 kubelet 能不能看到这些镜像。最直接的办法是在节点上跑crictl images如果列表里有 calico 相关镜像且 tag 是 v3.20.6说明导入成功。# 验证镜像是否对 kubelet 可见 crictl images | grep calico # 预期输出类似 # docker.io/calico/node v3.20.6 xxxxx xxxMB # docker.io/calico/cni v3.20.6 xxxxx xxxMB如果crictl images里没有但ctr images ls里有八成是命名空间问题回到上一步检查-n k8s.io。如果两个都没有那就是 tar 包本身有问题重新解压或者重新获取。这里提醒一句镜像 tar 包在传输过程中损坏是常有的事尤其是跨网络拷贝大文件导入前先tar -tf看一眼结构能省不少时间。3.2 calico.yaml 里必须改的四个参数calico.yaml 拿过来不能直接 apply默认值只适合最标准的场景。我每次至少改四个地方每一个都对应实际环境里的一个变量。第一个是CALICO_IPV4POOL_CIDR这个值必须和集群的--cluster-cidr一致。默认是192.168.0.0/16如果你的集群用的是10.244.0.0/16不改的话新 Pod 的 IP 段和集群预期对不上跨节点通信直接断。第二个是网卡名在IP_AUTODETECTION_METHOD附近。默认是first-found多网卡机器上这个策略很危险可能选到一张不该用的网卡。我一般改成interfaceeth0或者can-reach某个稳定地址明确指定。第三个是镜像地址。如果你的集群不能直连默认仓库要把 yaml 里所有image:字段改成你本地仓库的地址或者确保导入的镜像 tag 和 yaml 里写的一致。第四个是容器运行时 socket 路径前面提过containerd 环境要把/var/run/docker.sock改成/run/containerd/containerd.sock。# calico.yaml 关键片段改之前先备份 - name: CALICO_IPV4POOL_CIDR value: 10.244.0.0/16 # 必须和 --cluster-cidr 一致 - name: IP_AUTODETECTION_METHOD value: interfaceeth0 # 多网卡环境必须指定 # 镜像地址按实际仓库改 image: calico/node:v3.20.6改完 yaml 之后我习惯用kubectl apply --dry-runclient -f calico.yaml先跑一遍确认语法没问题再正式 apply。这个 dry-run 只能查语法查不出参数逻辑错误但至少能挡住低级失误。3.3 应用清单和观察启动过程正式 apply 之后不要马上走开盯着 Pod 的启动过程看。Calico 的启动顺序有讲究先是calico-node的 DaemonSet 在每个节点起来然后是calico-kube-controllers的 Deployment。如果 calico-node 起不来kube-controllers 大概率也起不来因为后者依赖前者建立的网络。kubectl apply -f calico.yaml # 持续观察 Pod 状态 kubectl get pods -n kube-system -l k8s-appcalico-node -w # 看某个节点的 calico-node 日志 kubectl logs -n kube-system calico-node-pod -c calico-node观察的时候重点看两个信号一是 Pod 是否从 Init 走到 Running二是日志里有没有BIRD is ready或者Calico node started这类标志。如果卡在 Init 阶段多半是镜像或者 CNI 配置的问题如果 Running 但节点还是 NotReady去看 kubelet 日志里有没有 CNI plugin 相关的报错。这一步的耐心很值钱早发现早处理比装完一堆 Pod 起不来再回头查要省事得多。4. 避坑与排查calico v3.20.6 装挂了的五种典型现场4.1 现象calico-node 一直 ImagePullBackOff原因基本就三类镜像没导入、导入到了错误的命名空间、yaml 里的镜像地址和实际导入的 tag 对不上。排查顺序是先crictl images确认镜像在不在再看 yaml 里image:字段写的是什么最后确认运行时是 docker 还是 containerd。解决方式就是按实际运行时重新导入并把 yaml 里的镜像地址改成和本地一致。我一般会在导入后统一打一个本地 tagyaml 里直接引用本地 tag避免仓库地址来回改。4.2 现象节点 NotReadykubelet 报 CNI plugin not initialized这个通常是 calico-node 还没完全就绪kubelet 就急着初始化 Pod 网络了。先看 calico-node 的日志如果里面有failed to set up netlink或者cannot find device多半是网卡名配错了。回到IP_AUTODETECTION_METHOD改成明确的interfacexxx。另一种可能是 CNI 配置文件没生成检查/etc/cni/net.d/目录下有没有10-calico.conflist没有的话说明 calico-node 的 init 容器没跑完看 init 容器日志。4.3 现象Pod 跨节点不通同节点正常这是最典型的网段或 BGP 问题。先确认CALICO_IPV4POOL_CIDR和--cluster-cidr是否一致不一致就改 yaml 重新 apply。如果一致检查节点之间的 179 端口通不通telnet 对端IP 179试一下。不通就是防火墙或者安全组挡了。还有一种情况是节点有多张网卡BGP 选错了源地址这时候要在 calico-node 的环境变量里加IP_AUTODETECTION_METHOD明确指定或者用calicoctl看 BGP peer 的状态。4.4 现象calico-kube-controllers 反复重启看日志如果是connection refused连不上 apiserver检查 ServiceAccount 和 ClusterRoleBinding 有没有正确创建kubectl get clusterrolebinding | grep calico看一眼。如果是failed to sync之类的可能是 CRD 没装全v3.20.6 的 yaml 里 CRD 是单独一段apply 的时候如果中途报错CRD 可能只建了一半。解决方式是先把 CRD 单独 apply 一遍再 apply 其余部分。4.5 现象装完想重装发现删不干净Calico 卸载不彻底是出了名的。kubectl delete -f calico.yaml之后节点上的 CNI 配置文件、路由规则、iptables 规则都还在。重装之前必须清理删/etc/cni/net.d/下的 calico 相关文件ip link delete cali0之类的虚拟网卡还有iptables -t nat -L里残留的规则。我一般会写一个清理脚本把这几步串起来重装前跑一遍不然新旧配置混在一起问题更难查。5. 装完怎么验证三步确认 Calico 真的跑通了装完不等于跑通这一步很多人会跳过结果过了几天才发现网络有问题。我的验证分三层从组件到网络到实际连通性一层层往下走。第一层看组件状态。kubectl get pods -n kube-system -l k8s-appcalico-node全部 Running 且 READY 是 1/1kubectl get pods -n kube-system -l k8s-appcalico-kube-controllers也是 Running。再看节点状态kubectl get nodes全部 Ready。这一层过了说明 Calico 的控制面是活的。# 第一层组件和节点状态 kubectl get pods -n kube-system | grep calico kubectl get nodes # 第二层确认 IP Pool 和 BGP 状态 kubectl get ippools.crd.projectcalico.org -o wide第二层看 IP 池和 BGP。kubectl get ippools应该能看到一个 CIDR 和你配置一致的池子。如果集群是多节点还要确认 BGP peer 建立成功这个用calicoctl node status看每个节点应该显示和其他节点的 peer 状态是up。这一步能提前发现跨节点通信的隐患。第三层是实际连通性测试也是最实在的。起两个测试 Pod分别调度到不同节点互相 ping 和 curl。我一般用kubectl run起一个 nginx 和一个 busyboxbusybox 里wget一下 nginx 的 Pod IP 和 Service IP两个都通才算真的跑通。# 起测试 Pod kubectl run nginx-test --imagenginx --port80 kubectl run busybox-test --imagebusybox -- sleep 3600 # 拿到 nginx 的 Pod IP在 busybox 里测试 kubectl get pod nginx-test -o wide kubectl exec -it busybox-test -- wget -qO- nginx-pod-ip kubectl exec -it busybox-test -- wget -qO- nginx-service-ipPod IP 通说明容器网络正常Service IP 通说明 kube-proxy 和 Calico 配合没问题。两个都通这套环境才算真正交付。从那以后我每次装完 Calico 都强制走一遍这三层验证哪怕看起来一切正常也不跳过——血泪经验告诉我Calico 的问题往往不是装的时候暴露而是跑起来几天后才冒出来那时候再查成本高得多。希望这套流程帮到你少走几个我踩过的坑。本文还有配套的精品资源点击获取

Calico v3.20.6 离线部署实战：镜像导入、yaml 调参与避坑指南

相关推荐

CTF比赛入门指南：从零基础到实战精进

JavaWeb运动健康管理系统源码：Servlet+JSP+JDBC全栈实战

Navicat简化SQL功能解析与应用实践

更多资讯

Struts 2学习笔记：OGNL

Maven 依赖导入失败

Nginx安装方法和反向代理配置

Windows Mysql 版本更新

【前端】移动端布局基础

一键开关机电源管理芯片选型四大核心维度

今日更新

GUI自动化测试中的ScreenLayout：从硬编码坐标到声明式画面地图

LLC谐振变换器12V25A 300W开关电源设计与调试全攻略

ESP32多应用Flash数据隔离：分区表与NVS namespace实战

本周精选

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

本月热门

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

读完文章，想聊聊您的网站？