企业官网建设流程全解析

kubeasz 安装 Calico 网络插件全指南：从证书签发到 BGP 路由验证

【免费下载链接】kubeasz使用Ansible脚本安装K8S集群，介绍组件交互原理，方便直接，不受国内网络环境影响项目地址: https://gitcode.com/GitHub_Trending/ku/kubeasz

kubeasz 项目使用 Ansible 脚本快速部署生产级 Kubernetes 集群，而 Calico 是其默认网络插件（同时也是 k8s-conformance test 默认使用的网络插件）。本文以 docs/setup/network-plugin/calico.md 为核心骨架，结合 roles/calico 角色的真实源码与 example/config.yml 配置示例，完整讲解 Calico 网络组件的安装原理、关键配置项与验证手段。读完本文，你将掌握如何在 kubeasz 集群中一键安装 Calico、理解其证书体系与 etcd 数据存储方式，并能独立排查网络问题。

一、Calico 在 kubeasz 中的定位

Calico 是 Kubernetes 社区最流行的网络插件之一，功能丰富，原生支持 NetworkPolicy（网络策略），这也是 kubeasz 选择它作为默认网络插件的主要原因。在 kubeasz 中，网络插件属于独立安装阶段，对应 playbook playbooks/06.network.yml：

# to install network plugin, only one can be choosen - hosts: - kube_master - kube_node roles: - { role: calico, when: "CLUSTER_NETWORK == 'calico'" } - { role: cilium, when: "CLUSTER_NETWORK == 'cilium'" } - { role: flannel, when: "CLUSTER_NETWORK == 'flannel'" } - { role: kube-router, when: "CLUSTER_NETWORK == 'kube-router'" } - { role: kube-ovn, when: "CLUSTER_NETWORK == 'kube-ovn'" }

从源码结构看，同一时间只能选择一种网络插件，各插件通过CLUSTER_NETWORK变量进行条件分发。因此启用 Calico 只需要在集群配置的hosts文件中设置变量CLUSTER_NETWORK="calico"（具体配置位置参考 config_guide.md），随后执行ezctl setup <集群名> 06即可。

Calico 角色的目录结构

roles/calico/ ├── tasks │ ├── main.yml # 主流程：证书、secret、yaml渲染、分发、轮询 │ └── calico-rr.yml # 可选：BGP Route Reflector 配置 ├── templates │ ├── calico-csr.json.j2 # 证书申请文件模板 │ ├── calicoctl.cfg.j2 # calicoctl 客户端配置模板 │ ├── calico-v3.26.yaml.j2 # v3.26 清单模板 │ ├── calico-v3.28.yaml.j2 # v3.28 清单模板（源码注释丰富） │ ├── calico-v3.32.yaml.j2 # v3.32 清单模板 │ ├── bgp-default.yaml.j2 # BGPConfiguration 模板 │ └── bgp-rr.yaml.j2 # BGPPeer 模板 └── vars └── main.yml # etcd endpoints 与 AS 号变量

注意：当前仓库实际提供的版本模板为v3.26 / v3.28 / v3.32三个，安装时由calico_ver_main变量（即calico_ver的主版本号）动态选择对应模板，见 tasks/main.yml：

- name: 配置 calico DaemonSet yaml文件 template: src=calico-{{ calico_ver_main }}.yaml.j2 dest={{ cluster_dir }}/yml/calico.yaml

二、创建 Calico 证书申请（客户端证书）

Calico 组件与 etcd 之间通过 TLS 客户端证书认证，其证书申请文件模板为 calico-csr.json.j2，渲染后内容如下：

{ "CN": "calico", "hosts": [], "key": { "algo": "rsa", "size": 2048 }, "names": [ { "C": "CN", "ST": "HangZhou", "L": "XS", "O": "k8s", "OU": "System" } ] }

关键点：hosts字段为空。因为 Calico 使用的是客户端证书（client certificate），证书中不需要包含任何服务端 IP 或域名；它只需要证明"我是 calico"，从而获得访问 etcd 的权限。

在 tasks/main.yml 中，证书由 cfssl 工具基于集群已有的 CA 签发：

- name: 创建calico 证书请求 template: src=calico-csr.json.j2 dest={{ cluster_dir }}/ssl/calico-csr.json - name: 创建 calico证书和私钥 shell: "cd {{ cluster_dir }}/ssl && {{ base_dir }}/bin/cfssl gencert \ -ca=ca.pem \ -ca-key=ca-key.pem \ -config=ca-config.json \ -profile=kubernetes calico-csr.json|{{ base_dir }}/bin/cfssljson -bare calico"

profile=kubernetes说明它复用了集群 CA 配置（deploy/templates/ca-config.json.j2）中 kubernetes profile 的用途与过期时间设置。签发完成后会得到calico.pem（证书）、calico-key.pem（私钥）以及 CA 证书ca.pem。

证书的四个使用场景

后续可以看到这份证书被用在四个地方，全部与"访问 etcd"相关：

这四个场景在 calico-v3.28.yaml.j2 与 calicoctl.cfg.j2 中均有体现：calico-configConfigMap 通过 Secret 卷把证书挂载进calico-node与calico-kube-controllers容器，CNI 插件则在cni_network_config中直接引用主机路径/etc/calico/ssl/下的证书文件。

证书打包为 Kubernetes Secret

tasks 主流程还会将证书打包为 kube-system 命名空间下的calico-etcd-secrets（见 tasks/main.yml），供 DaemonSet/Deployment 以 Secret 卷方式挂载：

- name: 创建 calico-etcd-secrets shell: "cd {{ cluster_dir }}/ssl && \ {{ base_dir }}/bin/kubectl create secret generic -n kube-system calico-etcd-secrets \ --from-file=etcd-ca=ca.pem \ --from-file=etcd-key=calico-key.pem \ --from-file=etcd-cert=calico.pem"

在 calico-v3.28.yaml.j2 中，该 Secret 以defaultMode: 0400挂载到/calico-secrets目录，保证证书只读且权限最小化。

证书分发到节点

除了打包 Secret，证书还会直接分发到每个节点的/etc/calico/ssl目录，供 calicoctl 客户端与 CNI 插件使用（tasks/main.yml）：

- name: 在节点创建相关目录 file: name={{ item }} state=directory with_items: - /etc/calico/ssl - name: 分发calico证书相关 copy: src={{ cluster_dir }}/ssl/{{ item }} dest=/etc/calico/ssl/{{ item }} with_items: - ca.pem - calico.pem - calico-key.pem

三、生成 calico DaemonSet 清单与 RBAC 文件

证书就绪后，Ansible 会将calico-v{{ 主版本 }}.yaml.j2渲染为集群实际使用的清单{{ cluster_dir }}/yml/calico.yaml，并通过kubectl apply一次性创建全部资源（DaemonSet、Deployment、RBAC、ConfigMap、PDB 等），见 tasks/main.yml。

渲染后的清单由以下几类对象组成（以 calico-v3.28.yaml.j2 为例）：

1. calico-config ConfigMap：网络核心配置载体，包括 etcd 地址、证书路径、backend、MTU、CNI 网络配置；
2. calico-node DaemonSet：每个节点一个 Pod，负责路由学习（bird）、策略下发（Felix）与数据面编程；
3. calico-kube-controllers Deployment：单副本控制器，负责把 Kubernetes 的 NetworkPolicy、Namespace、ServiceAccount 等对象同步到 Calico 数据模型；
4. RBAC 资源：calico-node、calico-kube-controllers、calico-cni-plugin三个 ServiceAccount 及对应的 ClusterRole/ClusterRoleBinding；
5. PodDisruptionBudget：保护 calico-kube-controllers 在集群缩容时不被强制驱逐。

3.1 关键环境变量与 {{ }} 变量映射

清单模板中所有{{ }}变量均与 Ansible hosts / config 文件中的设置一一对应，需要重点理解的有：

其中ETCD_ENDPOINTS的生成逻辑在 roles/calico/vars/main.yml 中：

# etcd 集群服务地址列表, 根据etcd组成员自动生成 TMP_ENDPOINTS: "{% for h in groups['etcd'] %}https://{{ h }}:2379,{% endfor %}" ETCD_ENDPOINTS: "{{ TMP_ENDPOINTS.rstrip(',') }}" # calico AS number CALICO_AS_NUMBER: 64512

它遍历 inventory 中[etcd]组的所有主机，自动拼接出https://ip1:2379,https://ip2:2379,...形式的多端点地址，并在末尾去除多余的逗号——这意味着新增 etcd 节点后，重新执行网络安装即可自动刷新 endpoints。

3.2 数据面 backend 与 Overlay 的选择逻辑

模板中使用 Jinja2 条件渲染根据 backend 类型注入不同的环境变量（calico-v3.28.yaml.j2）：

{% if CALICO_NETWORKING_BACKEND == "bird" %} - name: CALICO_IPV4POOL_IPIP value: "{{ CALICO_ENABLE_OVERLAY }}" {% endif %} {% if CALICO_NETWORKING_BACKEND == "vxlan" %} - name: CALICO_IPV4POOL_VXLAN value: "{{ CALICO_ENABLE_OVERLAY }}" - name: CALICO_IPV6POOL_VXLAN value: "{{ CALICO_ENABLE_OVERLAY }}" {% endif %}

• bird：默认 backend，使用 BIRD 守护进程负责 BGP 路由，Pod 间流量默认走三层路由；配合CALICO_IPV4POOL_IPIP决定是否启用 IPIP 隧道封装；
• vxlan：适合少数不支持 IPIP 封包的公有云（如 Azure）或私有云环境，改用 VXLAN 隧道；
• none：仅下发策略、不做路由分发。

同时，CALICO_ENABLE_OVERLAY的取值语义在 example/config.yml 中有明确注释：

# 模式可选项有: [Always, CrossSubnet, Never],跨子网可以配置为Always与CrossSubnet # CrossSubnet为隧道+BGP路由混合模式可以提升网络性能，同子网配置为Never即可. # 公有云建议使用always比较省事，其他的话需要修改各自公有云的网络配置，具体可以参考各个公有云说明 CALICO_ENABLE_OVERLAY: "Always"

• Always：所有跨节点流量都走隧道封装，公有云上最省事；
• CrossSubnet：仅跨子网流量走隧道，同子网走 BGP 直连，性能更好；
• Never：完全不用隧道，依赖底层网络可达（同子网适用）。

IP_AUTODETECTION_METHOD默认使用can-reach={{ groups['kube_master'][0] }}，即通过探测第一个 master 节点 IP 来反推本机对外通信使用的网卡地址，从而避免在多网卡机器上选错 BGP 对等地址。

3.3 CNI 网络配置

calico-config中的cni_network_config定义了每个节点要写入/etc/cni/net.d/的 CNI 插件链（calico-v3.28.yaml.j2），包含三个插件：

{ "name": "k8s-pod-network", "cniVersion": "0.3.1", "plugins": [ { "type": "calico", "log_level": "info", "etcd_endpoints": "{{ ETCD_ENDPOINTS }}", "etcd_key_file": "/etc/calico/ssl/calico-key.pem", "etcd_cert_file": "/etc/calico/ssl/calico.pem", "etcd_ca_cert_file": "{{ ca_dir }}/ca.pem", "mtu": "__CNI_MTU__", "ipam": { "type": "calico-ipam" }, "policy": { "type": "k8s" }, "kubernetes": { "kubeconfig": "/etc/cni/net.d/calico-kubeconfig" } }, { "type": "portmap", "snat": true, "capabilities": {"portMappings": true} }, { "type": "bandwidth", "capabilities": {"bandwidth": true} } ] }

• calico 主插件：负责创建 veth 对、通过calico-ipam从 etcd 分配 IP；
• portmap 插件：实现hostPort端口映射与 SNAT；
• bandwidth 插件：支持 Pod 的带宽限制（配合 NetworkPolicy / QoS）。

__CNI_MTU__与__CNI_MTU__是占位符，由install-cniinit 容器根据节点实际 MTU 自动替换（模板中veth_mtu: "0"表示自动探测，无需手工指定）。

3.4 安装 CNI 二进制的 init 容器

calico-nodePod 通过两个 init 容器完成前置工作（calico-v3.28.yaml.j2）：

• install-cni：把 CNI 二进制与网络配置安装到宿主机/opt/cni/bin与/etc/cni/net.d；
• mount-bpffs：以 best-effort 方式挂载 eBPF 所需的/sys/fs/bpf与 cgroup2 文件系统，为 eBPF 数据面做准备；失败不会阻塞 iptables 模式下的 Pod 创建。

主容器calico-node使用hostNetwork: true直接共享宿主机网络命名空间，并设置了system-node-critical优先级与NoSchedule/NoExecute/CriticalAddonsOnly容忍，确保其在任何节点（包括被打了污点的控制面节点）上都能调度。

四、安装 Calico 网络（执行顺序与前置条件）

kubeasz 通过 tasks/main.yml 串联整个安装流程，其完整执行顺序为：

1. 创建证书请求并签发证书（cfssl）；
2. 创建/删除 calico-etcd-secrets（kubectl delete兼容旧证书场景，CHANGE_CA变量控制强制轮换）；
3. 渲染并 apply calico.yaml 清单；
4. 在节点创建/etc/calico/ssl并分发证书；
5. 删除默认 CNI 配置/etc/cni/net.d/10-default.conf；
6. 下发 calicoctl 客户端与配置文件；
7. 轮询等待 calico-node 达到 Running；
8. （可选）启用 BGP Route Reflector。

4.1 安装前置条件（务必检查）

原文档强调以下三点，缺一不可：

• 主机名合法性：安装前检查主机名不能有大写字母，只能由小写字母、-、.组成，即匹配正则[a-z0-9](https://link.gitcode.com/i/bf2eab795ff7f639b6e4776d5c1c2b10)?(\.[a-z0-9](https://link.gitcode.com/i/bf2eab795ff7f639b6e4776d5c1c2b10)?)*。原因：calico node 名称由主机名派生，主机名非法会导致节点无法注册（注：calico-node v3.0.6 以上版本已解决主机大写字母问题）；
• 主机名全局唯一：各节点主机名不能重复。calico node name 由节点主机名决定，若重复，重复节点在 etcd 中只存储一份配置，BGP 邻居也不会建立；
• 依赖组件先行：安装之前必须确保kube_master和kube_node节点已经成功部署（因为 calico 依赖 kube-apiserver、kubelet 及 etcd）。

4.2 删除默认 CNI 配置

kube-node 角色在节点初始化时会写入默认 CNI 配置（/etc/cni/net.d/10-default.conf），Calico 安装时需先删除它，避免与 Calico 的10-calico.conflist冲突（见 tasks/main.yml）：

- name: 删除默认cni配置 file: path=/etc/cni/net.d/10-default.conf state=absent

4.3 轮询等待安装完成

由于镜像下载需要时间（即便配置了 Docker 国内加速，仍可能较慢），kubeasz 采用轮询机制等待本节点calico-nodePod 变为 Running（tasks/main.yml）：

- name: 轮询等待calico-node 运行 shell: "{{ base_dir }}/bin/kubectl get pod -n kube-system -o wide|grep 'calico-node'|grep ' {{ K8S_NODENAME }} '|awk '{print $3}'" register: pod_status until: pod_status.stdout == "Running" retries: 15 delay: 15

即每 15 秒检查一次，最多重试 15 次（约 3.75 分钟），匹配以本节点名命名的 calico-node Pod 的状态列。安装成功后应看到每个节点一个calico-nodePod（2/2 Running）以及一个calico-kube-controllersPod：

kubectl get pod --all-namespaces NAMESPACE NAME READY STATUS RESTARTS AGE kube-system calico-kube-controllers-5c6b98d9df-xj2n4 1/1 Running 0 1m kube-system calico-node-4hr52 2/2 Running 0 1m kube-system calico-node-8ctc2 2/2 Running 0 1m kube-system calico-node-9t8md 2/2 Running 0 1m

提示：请确认以上容器全部 Running 后再执行后续验证步骤，避免因镜像未就绪而误判。

五、配置 calicoctl 工具（可选）

calicoctl 是 Calico 的官方运维客户端，kubeasz 会自动将其下发到每个节点的${bin_dir}（如/opt/kube/bin）并生成配置文件/etc/calico/calicoctl.cfg（tasks/main.yml）。模板内容见 calicoctl.cfg.j2：

apiVersion: projectcalico.org/v3 kind: CalicoAPIConfig metadata: spec: datastoreType: "etcdv3" etcdEndpoints: {{ ETCD_ENDPOINTS }} etcdKeyFile: /etc/calico/ssl/calico-key.pem etcdCertFile: /etc/calico/ssl/calico.pem etcdCACertFile: {{ ca_dir }}/ca.pem

该配置声明数据存储类型为etcdv3，并指定 etcd 端点与 TLS 客户端证书。配置就绪后，即可在任意节点执行calicoctl node status、calicoctl get node、calicoctl patch node等管理命令。

六、验证 Calico 网络

6.1 查看网卡与路由信息

先在集群创建几个测试 Pod：

kubectl run test --image=busybox --replicas=3 sleep 30000

然后在节点上执行ip a查看网卡：

• 可以看到包含类似cali1cxxx的网卡，这是 Calico 为测试 Pod 生成的 veth 对（一端在宿主机，另一端在 Pod 网络命名空间内）；
• tunl0网卡此时可以忽略，它是默认生成的，仅在开启 IPIP 特性时作为隧道设备使用。

再执行route -n查看路由：

Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 0.0.0.0 192.168.1.1 0.0.0.0 UG 0 0 0 ens3 192.168.1.0 0.0.0.0 255.255.255.0 U 0 0 0 ens3 172.17.0.0 0.0.0.0 255.255.0.0 U 0 0 0 docker0 172.20.3.64 192.168.1.34 255.255.255.192 UG 0 0 0 ens3 172.20.33.128 0.0.0.0 255.255.255.192 U 0 0 0 * 172.20.33.129 0.0.0.0 255.255.255.255 UH 0 0 0 caliccc295a6d4f 172.20.104.0 192.168.1.35 255.255.255.192 UG 0 0 0 ens3 172.20.166.128 192.168.1.63 255.255.255.192 UG 0 0 0 ens3

路由表解读：

• 172.20.33.129 ... caliccc295a6d4f：本机 Pod 的路由，下一跳直接指向 veth 对；
• 172.20.33.128/26 ... *：本机 Pod 网段；
• 172.20.3.64/26 → 192.168.1.34、172.20.104.0/26 → 192.168.1.35、172.20.166.128/26 → 192.168.1.63：远端节点上 Pod 网段的路由，下一跳是各节点物理 IP——这正是 BGP 路由学习的结果，说明 Calico 已经把各节点分配的 Pod 网段通过 BGP 广播到了全网。

6.2 查看所有 Calico 节点状态（BGP Peer）

calicoctl node status Calico process is running. IPv4 BGP status +--------------+-------------------+-------+----------+-------------+ | PEER ADDRESS | PEER TYPE | STATE | SINCE | INFO | +--------------+-------------------+-------+----------+-------------+ | 192.168.1.34 | node-to-node mesh | up | 12:34:00 | Established | | 192.168.1.35 | node-to-node mesh | up | 12:34:00 | Established | | 192.168.1.63 | node-to-node mesh | up | 12:34:01 | Established | +--------------+-------------------+-------+----------+-------------+

输出显示当前节点与其余 3 个节点均建立了node-to-node mesh（节点间全互联）模式的 BGP 对等关系，状态为Established。

6.3 用 netstat 验证 BGP Peer（TCP 179 端口）

BGP 协议通过 TCP 连接建立邻居，端口号为179。因此可以用 netstat 直接验证：

netstat -antlp|grep ESTABLISHED|grep 179 tcp 0 0 192.168.1.66:179 192.168.1.35:41316 ESTABLISHED 28479/bird tcp 0 0 192.168.1.66:179 192.168.1.34:40243 ESTABLISHED 28479/bird tcp 0 0 192.168.1.66:179 192.168.1.63:48979 ESTABLISHED 28479/bird

可以看到本机（192.168.1.66）的bird进程（PID 28479）监听 179 端口，并与其余 3 个节点建立了 ESTABLISHED 连接——与calicoctl node status的结果一一对应。

6.4 查看 etcd 中 Calico 相关数据

因为 Calico 使用etcd v3存储网络数据，可以登录集群的任一 etcd 节点直接查看：

# 查看所有calico相关数据 ETCDCTL_API=3 etcdctl --endpoints="http://127.0.0.1:2379" get --prefix /calico # 查看 calico网络为各节点分配的网段 ETCDCTL_API=3 etcdctl --endpoints="http://127.0.0.1:2379" get --prefix /calico/ipam/v2/host

第二条命令会列出各节点被分配的 Pod 网段（与前面route -n中看到的172.20.x.0/26对应），可以交叉验证 IPAM 分配结果是否正确。

七、规模化演进：BGP Route Reflector（可选）

原文档的最后一步指向 calico-bgp-rr.md。当集群规模较大时，默认的 node-to-node mesh（IBGP 全互联）会导致连接数随节点数平方级增长。此时建议启用 Calico 内建的路由反射器（Route Reflector，RR）：

• 无 RR 时，所有节点两两建立连接（IBGP 全互联），连接数剧增；
• 引入 RR 后，普通节点只需与 RR 建立连接，连接数线性增长；
• calico-node v3.3 起支持内建 RR；建议集群节点数大于 50 时启用。

kubeasz 已将该能力封装进 calico-rr.yml，启用方式只需两步：

1. 在clusters/xxx/config.yml中设置CALICO_RR_ENABLED: true（example/config.yml 中默认false，另有CALICO_RR_NODES可手工指定 RR 节点，为空时默认取所有 master 节点）；
2. 重新执行dk ezctl setup xxx 07。

其底层执行逻辑（calico-rr.yml）包括：为 RR 节点 patchrouteReflectorClusterID: 244.0.0.1、打上route-reflector=true标签，然后应用两个资源：

bgp-rr.yaml.j2（定义普通节点与 RR 的 peer 规则）：

kind: BGPPeer apiVersion: projectcalico.org/v3 metadata: name: peer-with-route-reflectors spec: nodeSelector: all() peerSelector: route-reflector == 'true'

bgp-default.yaml.j2（关闭全局全互联，AS 号由CALICO_AS_NUMBER控制，默认 64512）：

apiVersion: projectcalico.org/v3 kind: BGPConfiguration metadata: name: default spec: logSeverityScreen: Info nodeToNodeMeshEnabled: false asNumber: {{ CALICO_AS_NUMBER }}

执行完毕后，所有普通节点都只与 RR 节点建立 BGP 连接（peer type 变为node specific），RR 节点之间也建立连接；对大规模集群建议配置 2～3 个 RR 节点以冗余。详细原理与手动配置过程可阅读 calico-bgp-rr.md。

八、常见问题与排查建议

• calico-node 长时间 Pending：多为镜像拉取慢导致，等待并确认镜像下载完成后 Pod 会自动 Running；同时检查主机名是否合法且全局唯一（参见前置条件）。
• calico-node 无法访问 etcd：检查/etc/calico/ssl下证书是否齐全、calico-etcd-secrets是否存在于 kube-system，以及ETCD_ENDPOINTS是否与 etcd 集群实际地址一致。
• Pod 间跨节点不通：在节点上执行calicoctl node status确认 BGP 邻居均为 Established；再用netstat -antlp | grep 179确认 TCP 连接；最后对照route -n检查远端 Pod 网段路由是否通过 BGP 下发。
• 主机名重复导致部分节点不工作：重复节点在 etcd 中只存储一份配置，BGP 邻居不会建立，务必保证节点主机名全局唯一。
• 公有云环境隧道不通：部分公有云（如 Azure）不支持 IPIP 封包，可将CALICO_NETWORKING_BACKEND改为vxlan。

总结

在 kubeasz 中启用 Calico 网络插件的完整链路是：设置CLUSTER_NETWORK="calico"→ 执行06网络安装 playbook → 角色自动完成证书签发、Secret 创建、清单渲染与 apply、CNI 配置清理、calicoctl 下发与状态轮询。其数据面核心是"etcd 存储 + BGP 路由分发 + veth 直连"，通过CALICO_NETWORKING_BACKEND、CALICO_ENABLE_OVERLAY、IP_AUTODETECTION_METHOD等变量即可适配裸机、公有云等多种环境，并通过 BGP Route Reflector 支撑大规模集群。相关源码均可继续深入 roles/calico 目录、example/config.yml 与 playbooks/06.network.yml 进行研读。

【免费下载链接】kubeasz使用Ansible脚本安装K8S集群，介绍组件交互原理，方便直接，不受国内网络环境影响项目地址: https://gitcode.com/GitHub_Trending/ku/kubeasz