Kubernetes 1.29.2 环境下用Tigera Operator安装Calico的避坑指南(含镜像替换方案)
在Kubernetes 1.29.2这个相对较新的版本上部署网络插件,尤其是选择Calico作为CNI时,很多朋友可能会直接想到使用官方的calico.yaml清单文件。但如果你深入了解一下,会发现官方现在更推荐使用Tigera Operator来管理Calico的生命周期。这不仅仅是安装方式的改变,更是一种运维理念的升级——从静态的YAML文件部署,转向由Operator驱动的声明式、自动化管理。
然而,在实际操作中,尤其是在国内网络环境下,直接照搬官方文档的步骤往往会遇到镜像拉取失败这个“拦路虎”。默认的docker.io或quay.io仓库访问不稳定,导致Pod卡在ImagePullBackOff状态,整个集群的网络也就无法就绪。这篇文章,我就结合自己在多个生产及测试环境中的实战经验,为你梳理一套在Kubernetes 1.29.2上,通过Tigera Operator稳定、可靠地安装Calico的完整流程,并重点解决镜像拉取这个核心痛点。无论你是搭建本地开发集群,还是部署生产环境,这套方法都能帮你绕过那些常见的坑。
1. 环境准备与前置检查
在开始安装Calico之前,确保你的Kubernetes 1.29.2集群已经就绪且处于一个“干净”的状态,这能避免很多后续的诡异问题。如果你是用kubeadm初始化的集群,控制平面节点上通常会有一个污点(taint),阻止普通Pod调度。对于单节点或测试集群,我们通常需要移除这个污点。
首先,检查你的集群节点状态和污点情况:
kubectl get nodes -o wide
kubectl describe node <你的控制节点名称> | grep Taint
如果输出包含 node-role.kubernetes.io/control-plane:NoSchedule,你可以选择移除它,以便Calico的Pod可以调度到所有节点上:
kubectl taint nodes --all node-role.kubernetes.io/control-plane-
注意:在生产多节点集群中,通常不建议移除主节点的污点,而是通过给Calico的DaemonSet配置容忍(Tolerations)来实现调度。Tigera Operator默认已经为相关组件配置了必要的容忍度,所以这一步对于使用Operator的安装方式来说,很多时候不是必须的。这里操作主要是为了确保在单节点或学习环境中一切顺利。
另一个关键前置条件是确保你的节点满足Calico的运行要求。主要是内核模块和网络配置:
- 内核模块:Calico的
calico-node容器需要ip_tables、ip6_tables、netfilter等相关模块。现代Linux发行版通常都已加载。 - NetworkManager:如果系统使用了NetworkManager,需要配置其不要管理Calico使用的网络接口(通常是
cali*和tunl0)。可以创建一个配置文件:
cat <<EOF | sudo tee /etc/NetworkManager/conf.d/calico.conf
[keyfile]
unmanaged-devices=interface-name:cali*;interface-name:tunl0;interface-name:vxlan.calico
EOF
sudo systemctl reload NetworkManager
最后,确认你的kubectl能够正常与集群API Server通信,并且有足够的权限创建集群级别的资源(如CRD、ClusterRole等)。
2. 深入理解Tigera Operator与CRD
为什么官方推荐Operator?我们得先搞清楚它和传统calico.yaml方式的核心区别。传统方式是一次性应用一个庞大的YAML文件,里面定义了所有的Deployment、DaemonSet、Service等资源。升级或变更配置时,你需要手动修改这个文件并重新应用,过程繁琐且容易出错。
Tigera Operator则是一个遵循Kubernetes Operator模式的控制循环。它通过扩展Kubernetes API,引入了几个关键的Custom Resource Definition (CRD)。安装Operator后,你不再直接操作底层的Deployment或DaemonSet,而是通过声明一个Installation这样的自定义资源(CR)来“描述”你期望的Calico状态。Operator会持续监听这个CR,并自动驱动集群的实际状态向期望状态收敛。
这个过程带来了几个显著优势:
- 简化安装与配置:你只需要关注少数几个CR的配置(如
Installation),Operator负责生成和管理所有复杂的底层Kubernetes资源。 - 声明式升级:要升级Calico版本,通常只需更新Operator和
Installation资源中指定的镜像标签,Operator会以可控的方式执行滚动更新。 - 统一的生命周期管理:Operator处理配置验证、健康检查、故障恢复等运维任务。
- 高级功能集成:对于Calico Enterprise(商业版)的功能,Operator提供了更自然的集成方式。
让我们看看安装初期涉及的核心CRD。当你应用tigera-operator.yaml时,会创建一批CRD,其中与我们安装直接相关的主要包括:
| CRD 名称 | 作用描述 |
|---|---|
installations.operator.tigera.io | 定义Calico的核心安装配置,如网络模式、IP池、使用的数据平面(iptables/eBPF)等。这是我们配置的核心。 |
apiservers.operator.tigera.io | 配置Calico的API Server(如果启用)。 |
tigerastatuses.operator.tigera.io | 由Operator生成,用于报告Calico各个组件的运行状态,是检查安装是否成功的重要依据。 |
imagesets.operator.tigera.io | 可用于定义自定义的镜像集合,在离线或私有仓库环境中非常有用。 |
理解这些CRD的角色,能帮助你在安装和后续运维中,知道该去哪里查看和修改配置。例如,所有的网络配置几乎都在Installation CR里,而组件健康状态则看TigeraStatus。
3. 分步安装与核心配置详解
安装过程分为两个清晰的阶段:先部署Operator本身,再通过它来安装Calico实例。我们先处理第一个阶段。
3.1 部署Tigera Operator
官方推荐使用kubectl create来应用Operator的YAML,因为CRD资源较大,apply命令在某些环境下可能会遇到请求大小限制。
# 下载或直接应用Operator部署文件
kubectl create -f https://raw.githubusercontent.com/projectcalico/calico/v3.31.3/manifests/tigera-operator.yaml
应用成功后,检查Operator Pod是否正常运行:
kubectl get pods -n tigera-operator
你应该能看到一个名为tigera-operator-xxxxx的Pod状态为Running。这个Pod就是后续所有操作的“大脑”。
3.2 定制安装配置与镜像仓库替换
这是最关键也是最容易出错的步骤。我们需要创建一个Installation自定义资源。官方示例通常指向quay.io,但在国内,我们需要将其替换为可访问的镜像仓库。
这里我提供两种主流替换方案,并解释其原理。
方案一:使用阿里云等国内镜像仓库(推荐)
许多国内云厂商和社区维护了Kubernetes常用镜像的仓库。例如,阿里云镜像仓库同步了大部分Calico镜像。我们需要在Installation CR的spec中指定registry和imagePath字段。
创建一个名为calico-installation.yaml的文件,内容如下:
apiVersion: operator.tigera.io/v1
kind: Installation
metadata:
name: default
spec:
# 核心配置:镜像仓库替换
registry: registry.cn-hangzhou.aliyuncs.com
imagePath: google_containers # 注意:阿里云仓库中Calico镜像的路径可能不同,此处为示例,需核实
# Calico网络配置
calicoNetwork:
ipPools:
- cidr: 10.244.0.0/16 # Pod网络CIDR,必须与kubeadm init时设置的--pod-network-cidr一致!
encapsulation: VXLANCrossSubnet # 封装模式,CrossSubnet是较通用的选择
natOutgoing: Enabled # 出集群的NAT
blockSize: 26
nodeSelector: all()
nodeAddressAutodetection:
interface: "eth.*|en.*" # 节点IP自动检测的网卡模式
# 指定使用Linux iptables数据平面(稳定兼容)
linuxDataplane: Iptables
# 非必须:如果集群有Windows节点,可在此配置
# windowsDataplane: Iptables
---
apiVersion: operator.tigera.io/v1
kind: APIServer
metadata:
name: default
spec: {}
重要提示:
imagePath的值需要根据你选择的镜像仓库实际路径来填写。例如,对于阿里云,你可能需要先搜索确认calico/node等镜像的确切仓库路径。一个更可靠的方法是先手动docker pull测试一下镜像地址。例如:docker pull registry.cn-hangzhou.aliyuncs.com/google_containers/calico-node:v3.31.3。
方案二:使用私有镜像仓库(企业内网常用)
如果你在公司内网,通常会搭建私有的Docker Registry(如Harbor)。这时,除了指定registry和imagePath,还需要配置ImageSet来更精细地控制每个组件的镜像,并为私有仓库配置拉取密钥(ImagePullSecrets)。
首先,创建一个包含镜像拉取密钥的Secret(假设你的私有仓库需要认证):
kubectl create secret docker-registry my-private-registry-secret \
--docker-server=myregistry.example.com \
--docker-username=<your-username> \
--docker-password=<your-password> \
--docker-email=<your-email> \
-n tigera-operator
然后,创建一个ImageSet CR来定义镜像集合,并关联拉取密钥:
apiVersion: operator.tigera.io/v1
kind: ImageSet
metadata:
name: calico-v3.31.3
spec:
images:
- image: calico/node
digest: sha256:... # 可选,指定镜像摘要以确保一致性
- image: calico/cni
digest: sha256:...
# ... 列出所有需要的Calico组件镜像
# 引用之前创建的拉取密钥
pullSecrets:
- name: my-private-registry-secret
最后,在Installation CR中引用这个ImageSet:
apiVersion: operator.tigera.io/v1
kind: Installation
metadata:
name: default
spec:
variant: Calico # 明确指定变体
imageSet: calico-v3.31.3 # 引用上面定义的ImageSet
calicoNetwork:
# ... 网络配置同上
关于Pod网络CIDR的特别说明:
spec.calicoNetwork.ipPools[0].cidr的值必须与你在初始化Kubernetes集群时(例如kubeadm init --pod-network-cidr=10.244.0.0/16)设置的Pod网络CIDR完全一致。如果不一致,Calico分配的IP地址将无法与Kubernetes的预期匹配,导致Pod网络不通。如果你忘记了自己设置的CIDR,可以查看kubeadm-config ConfigMap:kubectl get cm -n kube-system kubeadm-config -o yaml。
3.3 应用配置并验证安装
配置好YAML文件后,使用kubectl create应用它:
kubectl create -f calico-installation.yaml
接下来就是耐心的等待和观察。Operator会开始创建一系列资源。你可以通过以下命令监控安装进度:
-
查看Calico系统命名空间下的Pod:
watch kubectl get pods -n calico-system等待所有Pod(如
calico-node-xxxxx,calico-kube-controllers-xxxxx等)的状态都变为Running。这个过程可能需要一两分钟,因为要拉取镜像、初始化容器。 -
使用TigeraStatus检查组件健康: Tigera Operator提供了一个非常好的状态查询资源
TigeraStatus。这是检查安装是否彻底成功的最佳方式。watch kubectl get tigerastatus当所有组件的
AVAILABLE列都显示为True时,说明Calico已完全就绪。 -
验证网络功能: 创建一个简单的测试Pod来验证网络是否正常工作。
kubectl run busybox --image=busybox:1.36 --restart=Never -- sleep 3600 kubectl exec busybox -- nslookup kubernetes.default如果能够解析内部服务域名,说明CoreDNS和网络策略基本正常。你还可以让这个Pod去ping其他节点的IP,或者部署一个多副本的Deployment来测试Pod间的通信。
4. 安装后的高级配置与故障排查
安装成功只是第一步。根据你的集群环境和需求,可能还需要进行一些调整。
4.1 网络模式选择与切换
Calico支持多种网络模式,我们在Installation CR中通过encapsulation字段指定。常见的模式有:
- VXLAN: 通用性强,能穿透大多数网络设备,性能稍逊于IPIP。
- IPIP: 性能略好于VXLAN,但某些网络环境(如某些云厂商的底层网络)可能不支持。
- VXLANCrossSubnet / IPIPCrossSubnet: 推荐。混合模式,同一子网内的Pod通信使用无封装的BGP路由(性能最佳),跨子网通信则自动降级为VXLAN或IPIP封装。这通常能提供最佳的性能和兼容性平衡。
- None (BGP): 无封装,性能最好,但要求所有节点在同一个二层网络或已配置BGP对等。
如果你安装后想切换模式,不要直接编辑calico-node的DaemonSet,而是应该修改Installation CR。因为Operator管理着这些资源,手动修改会被Operator覆盖。正确的方法是:
kubectl edit installation default -n calico-system
找到spec.calicoNetwork.ipPools.encapsulation字段,修改其值(例如改为IPIPCrossSubnet),保存退出。Operator会自动执行滚动更新,更新所有节点的calico-node。
4.2 常见安装失败问题排查
即使按照指南操作,也可能遇到问题。下面是一个快速排查清单:
-
Pod处于
ImagePullBackOff或ErrImagePull状态: 这是最常见的问题。首先检查Pod的描述信息:kubectl describe pod <pod-name> -n calico-system查看
Events部分,确认拉取镜像的错误信息。如果是因为仓库地址错误或不可访问,请回头检查InstallationCR中的registry和imagePath配置,并确保节点网络能访问该仓库。对于私有仓库,确认imagePullSecrets已正确配置并挂载。 -
Pod处于
CrashLoopBackOff状态: 查看Pod的日志:kubectl logs <pod-name> -n calico-system --previous # 查看上次崩溃的日志 kubectl logs <pod-name> -n calico-system # 查看当前日志常见原因包括:
- IP池CIDR与集群不匹配:日志中可能出现IPAM分配失败的错误。核对
Installation中的cidr与kubeadm init时设置的--pod-network-cidr。 - 节点IP检测失败:
calico-node无法检测到节点的正确IP。检查calico-nodePod的日志,并确认nodeAddressAutodetection配置的网卡模式(如eth.*|en.*)能匹配到你节点的实际IP所在网卡。你可以通过kubectl get node -o wide查看节点的INTERNAL-IP。
- IP池CIDR与集群不匹配:日志中可能出现IPAM分配失败的错误。核对
-
TigeraStatus一直不健康: 如果某个组件(如apiserver)长时间不健康,查看其对应Pod的状态和日志。也可能是资源(CPU/内存)不足,检查节点的资源使用情况。 -
使用
kubectl get tigerastatus命令报错“the server doesn‘t have a resource type ‘tigerastatus’”: 这说明Tigera Operator的CRD没有成功创建。重新检查第一步中Operator的部署日志:kubectl logs -n tigera-operator deployment/tigera-operator并确认CRD是否存在:
kubectl get crd | grep tigera。
4.3 关键运维命令与状态检查
掌握几个日常运维中常用的命令,能让你更从容:
-
查看Calico版本:
kubectl get deployment -n calico-system calico-kube-controllers -o jsonpath='{.spec.template.spec.containers[0].image}' kubectl get daemonset -n calico-system calico-node -o jsonpath='{.spec.template.spec.containers[0].image}' -
检查BGP对等状态(如果使用BGP模式):
# 需要先安装calicoctl calicoctl node status -
查看已分配的IP地址块:
kubectl get ipamblocks -o wide -
导出当前完整的Calico配置:
kubectl get installation default -n calico-system -o yaml kubectl get apiserver default -n calico-system -o yaml在升级或迁移前,备份这些配置是个好习惯。
5. 升级与卸载指南
5.1 升级Calico版本
使用Operator的一大好处就是简化升级。通常,升级Calico分为两步:
-
升级Tigera Operator:
# 假设要升级到v3.31.3对应的operator版本 kubectl apply --server-side --force-conflicts -f https://raw.githubusercontent.com/projectcalico/calico/v3.31.3/manifests/tigera-operator.yaml使用
--server-side --force-conflicts参数可以更好地处理CRD的更新。 -
更新
InstallationCR中的镜像版本: 修改InstallationCR,如果使用了ImageSet,则更新ImageSet中的镜像标签;如果直接在Installation中配置了registry,Operator通常会随着自身升级自动管理组件镜像版本到兼容的最新版,但为了保险,你也可以显式地通过imageSet字段指定版本。kubectl edit installations.operator.tigera.io default -n calico-system在
spec中添加或修改imageSet字段,例如imageSet: calico-v3.31.3(前提是你已定义对应的ImageSet)。
Operator会以滚动更新的方式,安全地升级各个组件。你可以通过kubectl get tigerastatus和观察Pod的滚动更新状态来监控升级过程。
5.2 彻底卸载Calico
如果需要卸载Calico,请按照以下顺序操作,确保清理干净:
-
删除Calico安装实例:
kubectl delete installation default -n calico-system kubectl delete apiserver default -n calico-system # 等待所有calico-system命名空间下的Pod被删除 kubectl wait --for=delete pod -l k8s-app=calico-node -n calico-system --timeout=300s -
删除Tigera Operator:
kubectl delete -f https://raw.githubusercontent.com/projectcalico/calico/v3.31.3/manifests/tigera-operator.yaml -
清理节点上的残留网络配置(在每个节点上执行):
# 删除CNI配置文件 sudo rm -rf /etc/cni/net.d/00-calico-* sudo rm -rf /etc/cni/net.d/calico-kubeconfig # 删除Calico生成的数据目录 sudo rm -rf /var/lib/calico/ # 卸载网络接口和模块(如果不再需要) sudo ip link delete cali0 2>/dev/null || true sudo ip link delete tunl0 2>/dev/null || true sudo modprobe -r ipip 2>/dev/null || true sudo modprobe -r vxlan 2>/dev/null || true # 重启kubelet让更改生效 sudo systemctl restart kubelet
警告:卸载网络插件会导致集群内所有Pod的网络中断。务必在维护窗口或非业务时间进行,并确保有回滚方案。在卸载前,最好备份你的
Installation和APIServer自定义资源。
523



被折叠的 条评论
为什么被折叠?



