从0到1：Calico v3.31.5 在本地 Kubernetes 集群的部署实战

从0到1：Calico v3.31.5 在本地 Kubernetes 集群的部署实战

引言

在 Kubernetes 集群中，网络插件是确保 Pod 之间通信的关键组件。Calico 作为业界领先的 CNI 插件，不仅提供稳定可靠的网络连接，还具备强大的网络策略管理能力，是生产环境的理想选择。

本文将详细介绍如何在本地 Kubernetes 集群上安装 Calico v3.31.5 版本，包括环境要求、安装步骤、验证方法以及故障排查等内容。无论您是 Kubernetes 新手还是经验丰富的管理员，都能通过本文快速掌握 Calico 的部署和配置。

一、概述

本文档指导您在自管理的本地（On-Premises）Kubernetes 集群上安装 Calico v3.31.5 作为 CNI（容器网络接口）插件。Calico 提供 Pod 网络、网络策略（Network Policy）以及可选的 BGP 路由功能。

本文档基于 Calico v3.31.5 版本，该版本引入了简化的 eBPF 数据平面自动部署、NFTables 数据平面 GA 等新特性。

二、环境要求

2.1 系统要求

选择 Calico 作为 CNI 插件时，需要确保集群满足以下系统要求：

Kubernetes 要求
支持的版本

• 1.32
• 1.33
• 1.34
• 1.35

由于 Kubernetes API 的变更，Calico v3.31 将无法在 Kubernetes v1.20 或更低版本上运行。v1.21 可能可以运行，但已不再进行测试。更新的版本也可能可以运行，但建议升级到已针对新版 Kubernetes 进行过测试的 Calico 版本。

⚠️ 注意：如果系统安装了 Firewalld 或其他 iptables 管理器，建议禁用，以免与 Calico 的规则冲突 。

2.2 Kubernetes 集群要求

• 集群尚未安装任何 CNI 插件
• 初始化集群时指定的 --pod-network-cidr 不能与现有网络重叠
• 所有节点之间网络互通
• 具备 kubectl 集群管理员权限

2.3 网络端口要求

根据您的配置，确保以下端口开放 ：

三、安装前准备

3.1 确认 Kubernetes 集群状态

在安装 Calico 之前，首先需要确认 Kubernetes 集群的状态：

# 检查节点状态（此时应为 NotReady，因为尚未安装 CNI）
kubectl get nodes

# 检查 kube-system 命名空间中的核心组件
kubectl get pods -n kube-system

3.2 确认 Pod CIDR

确保集群初始化时使用的 Pod CIDR 与 Calico 配置一致。例如，如果使用 kubeadm 初始化：

kubeadm init --pod-network-cidr=192.168.0.0/16

默认的 Calico 配置使用 192.168.0.0/16 作为 Pod CIDR。如果您使用了不同的 CIDR，请在后续步骤中修改配置文件。

四、安装步骤

步骤 1：安装 Tigera Operator 和 CRD

Tigera Operator 是 Calico 的推荐安装方式，它提供生命周期管理和简化升级。执行以下命令安装：

# 安装自定义资源定义（CRD）
kubectl create -f https://raw.githubusercontent.com/projectcalico/calico/v3.31.5/manifests/operator-crds.yaml

# 安装 Tigera Operator
kubectl create -f https://raw.githubusercontent.com/projectcalico/calico/v3.31.5/manifests/tigera-operator.yaml

验证 Operator 是否正常运行：

kubectl get pods -n tigera-operator
kubectl wait --for=condition=Available deployment/tigera-operator -n tigera-operator --timeout=120s

步骤 2：下载并配置 Calico 自定义资源

Calico v3.31 支持两种数据平面模式：iptables（标准） 和 eBPF（高性能）。您可以根据需求选择 。

选项 A：iptables 数据平面（默认，兼容性最好）

# 下载标准配置模板
curl -O https://raw.githubusercontent.com/projectcalico/calico/v3.31.5/manifests/custom-resources.yaml

默认 custom-resources.yaml 内容如下 ：

# Calico 安装配置
apiVersion: operator.tigera.io/v1
kind: Installation
metadata:
  name: default
spec:
  calicoNetwork:
    ipPools:
    - name: default-ipv4-ippool
      blockSize: 26
      cidr: 192.168.0.0/16           ## 需要和初始化K8s 集群时候指定的配置一样
      encapsulation: VXLANCrossSubnet
      natOutgoing: Enabled
      nodeSelector: all()

---
# Calico API Server
apiVersion: operator.tigera.io/v1
kind: APIServer
metadata:
  name: default
spec: {}

---
# Goldmane 流量聚合器
apiVersion: operator.tigera.io/v1
kind: Goldmane
metadata:
  name: default

---
# Whisker 可观测性 UI
apiVersion: operator.tigera.io/v1
kind: Whisker
metadata:
  name: default

选项 B：eBPF 数据平面（高性能，推荐用于新集群）

eBPF 数据平面提供更低延迟、更高吞吐量，并支持源 IP 保留和 Direct Server Return (DSR) 。

# 下载 eBPF 配置模板
curl -O https://raw.githubusercontent.com/projectcalico/calico/v3.31.5/manifests/custom-resources-bpf.yaml

custom-resources-bpf.yaml 关键配置 ：

apiVersion: operator.tigera.io/v1
kind: Installation
metadata:
  name: default
spec:
  calicoNetwork:
    linuxDataplane: BPF          # 启用 eBPF 数据平面
    bpfNetworkBootstrap: Enabled  # 自动检测 API Server 端点（v3.31 新特性）
    kubeProxyManagement: Enabled  # 自动管理 kube-proxy
    ipPools:
    - name: default-ipv4-ippool
      blockSize: 26
      cidr: 192.168.0.0/16
      encapsulation: VXLANCrossSubnet
      natOutgoing: Enabled
      nodeSelector: all()
# ... 后续 APIServer、Goldmane、Whisker 配置与 iptables 版本相同

💡 v3.31 新特性：eBPF 安装现已支持自动引导（bpfNetworkBootstrap: Enabled），Operator 会自动检测 Kubernetes API Server 端点，无需手动配置 ConfigMap 。

自定义配置（可选）

如果您需要修改配置（如更改 Pod CIDR、封装模式等），请在本地编辑下载的 YAML 文件：

本地网络（L2 互通）推荐配置 ：

calicoNetwork:
  ipPools:
  - blockSize: 26
    cidr: 192.168.0.0/16
    encapsulation: None        # 同子网无封装，性能最优
    natOutgoing: true
    nodeSelector: all()

步骤 3：应用配置安装 Calico

# 如果使用 iptables 模式
kubectl create -f custom-resources.yaml

# 如果使用 eBPF 模式
kubectl create -f custom-resources-bpf.yaml

步骤 4：监控安装进度

# 实时监控 Calico 组件状态
watch kubectl get tigerastatus

预期输出（约 3-5 分钟后）：

NAME                  AVAILABLE   PROGRESSING   DEGRADED   SINCE
apiserver             True        False         False      4m9s
calico                True        False         False      3m29s
goldmane              True        False         False      3m39s
ippools               True        False         False      6m4s
kubeproxy-monitor     True        False         False      6m15s
whisker               True        False         False      3m19s

同时检查 Pod 状态：

kubectl get pods -n calico-system
kubectl get pods -n tigera-operator

五、安装验证

5.1 验证节点状态

kubectl get nodes

所有节点应从 NotReady 变为 Ready 状态。

5.2 验证 Calico 组件

# 查看 Calico 系统 Pod
kubectl get pods -n calico-system

# 查看 Tigera Operator
kubectl get pods -n tigera-operator

# 查看安装状态
kubectl get installation default -o yaml

5.3 验证 eBPF 模式（如适用）

# 检查 Felix 日志确认 eBPF 已启用
kubectl logs -n calico-system ds/calico-node -c calico-node | grep -i "BPF enabled"

# 查看当前数据平面模式
kubectl get installation default -o=jsonpath="{.spec.calicoNetwork.linuxDataplane}"
# 应返回 "BPF"

# 检查 BPF 程序是否已加载
kubectl exec -n calico-system ds/calico-node -c calico-node -- bpftool prog list | head -20

5.4 安装 calicoctl（可选，用于高级管理）

# 下载对应版本的 calicoctl
curl -L https://github.com/projectcalico/calico/releases/download/v3.31.5/calicoctl-linux-amd64 -o calicoctl
chmod +x calicoctl && sudo mv calicoctl /usr/local/bin/

# 验证版本
calicoctl version

# 查看节点 BGP 状态（如启用 BGP）
calicoctl node status

六、功能特性说明

6.1 数据平面对比

6.2 v3.31 新增特性

• NFTables 数据平面 GA：提供更高效的网络规则管理
• eBPF 自动安装：简化 eBPF 模式部署，自动检测 API Server
• QoS 策略：支持带宽、包速率和 DSCP 流量标记
• BGP 自定义 ASN：支持每个对等体配置本地 ASN
• Whisker 可观测性 UI：改进的策略追踪和流量可视化

七、故障排查

7.1 常见问题

7.2 查看日志

# Tigera Operator 日志
kubectl logs -n tigera-operator deploy/tigera-operator --tail=50

# calico-node 日志
kubectl logs -n calico-system -l k8s-app=calico-node --tail=50

# 查看所有 Tigerastatus
kubectl get tigerastatus -o yaml

7.3 多网卡环境 IP 自动检测

如果节点有多个网络接口，Calico 可能选择错误的 IP：

# 设置通过特定接口检测节点 IP
kubectl patch ds calico-node -n calico-system --type merge \
  -p '{"spec":{"template":{"spec":{"containers":[{"name":"calico-node","env":[{"name":"IP_AUTODETECTION_METHOD","value":"interface=bond0"}]}]}}}}'

八、使用Manifest方式安装

选项1：Kubernetes API数据存储，50个节点或更少

# 下载清单文件
curl https://raw.githubusercontent.com/projectcalico/calico/v3.31.5/manifests/calico.yaml -O

# 配置Pod CIDR（如果需要）
# 如果使用kubeadm且Pod CIDR不是192.168.0.0/16，Calico会自动检测
# 其他平台需要取消注释并设置CALICO_IPV4POOL_CIDR变量

# 应用清单
kubectl apply -f calico.yaml

选项2：Kubernetes API数据存储，超过50个节点

# 下载包含Typha的清单文件
curl https://raw.githubusercontent.com/projectcalico/calico/v3.31.5/manifests/calico-typha.yaml -o calico.yaml

# 配置Pod CIDR（同选项1）

# 修改Typha副本数
# 在calico-typha Deployment中设置replicas参数
# 建议：每200个节点至少1个副本，生产环境至少3个副本，最多不超过20个

# 应用清单
kubectl apply -f calico.yaml

选项3：etcd数据存储（不推荐用于新安装）

# 下载etcd清单文件
curl https://raw.githubusercontent.com/projectcalico/calico/v3.31.5/manifests/calico-etcd.yaml -o calico.yaml

# 配置Pod CIDR（同选项1）

# 配置etcd端点
# 在calico-config ConfigMap中设置etcd_endpoints为etcd服务器的IP和端口
# 支持多个端点，用逗号分隔

# 应用清单
kubectl apply -f calico.yaml

九、卸载 Calico

如需卸载 Calico：

# 删除 Installation 资源（Operator 会自动清理）
kubectl delete installation default

# 删除 Operator
kubectl delete -f https://raw.githubusercontent.com/projectcalico/calico/v3.31.5/manifests/tigera-operator.yaml

# 删除 CRD（谨慎操作）
kubectl delete -f https://raw.githubusercontent.com/projectcalico/calico/v3.31.5/manifests/operator-crds.yaml

十、参考文档

• Calico 官方文档：https://docs.tigera.io/calico/latest/about
• Calico 系统要求：https://docs.tigera.io/calico/latest/getting-started/kubernetes/requirements
• Calico v3.31 新特性：https://docs.tigera.io/calico/latest/release-notes/
• Calico eBPF 数据平面：https://docs.tigera.io/calico/latest/about/kubernetes-training/about-ebpf
• Calico GitHub Releases：https://github.com/projectcalico/calico

总结

通过本文的指导，您应该已经成功在本地 Kubernetes 集群上安装并配置了 Calico v3.31.5。Calico 作为一个功能强大的 CNI 插件，不仅提供了稳定的网络连接，还具备丰富的网络策略管理能力，能够满足各种复杂场景的需求。

在安装过程中，您可以根据实际需求选择合适的数据平面模式：

• iptables 模式：兼容性最好，适合大多数环境
• eBPF 模式：性能更高，适合对网络性能要求较高的场景

如果在安装过程中遇到问题，可以参考本文的故障排查部分，或查阅官方文档获取更多帮助。

希望本文对您的 Calico 安装和配置有所帮助！