kubeasz 安装 Calico 网络插件全指南从证书签发到 BGP 路由验证【免费下载链接】kubeasz使用Ansible脚本安装K8S集群介绍组件交互原理方便直接不受国内网络环境影响项目地址: https://gitcode.com/GitHub_Trending/ku/kubeaszkubeasz 项目使用 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_NETWORKcalico具体配置位置参考 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: srccalico-{{ 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: srccalico-csr.json.j2 dest{{ cluster_dir }}/ssl/calico-csr.json - name: 创建 calico证书和私钥 shell: cd {{ cluster_dir }}/ssl {{ base_dir }}/bin/cfssl gencert \ -caca.pem \ -ca-keyca-key.pem \ -configca-config.json \ -profilekubernetes calico-csr.json|{{ base_dir }}/bin/cfssljson -bare calicoprofilekubernetes说明它复用了集群 CA 配置deploy/templates/ca-config.json.j2中 kubernetes profile 的用途与过期时间设置。签发完成后会得到calico.pem证书、calico-key.pem私钥以及 CA 证书ca.pem。证书的四个使用场景后续可以看到这份证书被用在四个地方全部与访问 etcd相关使用方用途calico/node 容器容器运行时访问 etcd 读写网络配置CNI 配置文件cni 插件cni 插件在创建 Pod 时访问 etcd 分配 IPcalicoctl 工具运维人员操作集群网络时访问 etcdcalico/kube-controllers同步 Kubernetes NetworkPolicy 等策略数据时访问 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 Secrettasks 主流程还会将证书打包为 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-fileetcd-caca.pem \ --from-fileetcd-keycalico-key.pem \ --from-fileetcd-certcalico.pem在 calico-v3.28.yaml.j2 中该 Secret 以defaultMode: 0400挂载到/calico-secrets目录保证证书只读且权限最小化。证书分发到节点除了打包 Secret证书还会直接分发到每个节点的/etc/calico/ssl目录供 calicoctl 客户端与 CNI 插件使用tasks/main.yml- name: 在节点创建相关目录 file: name{{ item }} statedirectory 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 为例calico-config ConfigMap网络核心配置载体包括 etcd 地址、证书路径、backend、MTU、CNI 网络配置calico-node DaemonSet每个节点一个 Pod负责路由学习bird、策略下发Felix与数据面编程calico-kube-controllers Deployment单副本控制器负责把 Kubernetes 的 NetworkPolicy、Namespace、ServiceAccount 等对象同步到 Calico 数据模型RBAC 资源calico-node、calico-kube-controllers、calico-cni-plugin三个 ServiceAccount 及对应的 ClusterRole/ClusterRoleBindingPodDisruptionBudget保护 calico-kube-controllers 在集群缩容时不被强制驱逐。3.1 关键环境变量与 {{ }} 变量映射清单模板中所有{{ }}变量均与 Ansible hosts / config 文件中的设置一一对应需要重点理解的有模板变量 / 环境变量含义配置来源ETCD_ENDPOINTSetcd 集群地址列表https 格式由 vars/main.yml 根据 etcd 组成员自动生成CALICO_IPV4POOL_CIDR→CALICO_IPV4POOL_CIDRPod 网段即{{ CLUSTER_CIDR }}hosts 文件中的CLUSTER_CIDR默认192.168.0.0/16见 config_guide.mdFELIX_DEFAULTENDPOINTTOHOSTACTIONACCEPT默认允许 Pod 到 Node 的网络流量硬编码于模板CALICO_NETWORKING_BACKEND数据面 backendbird/vxlan/noneexample/config.ymlCALICO_ENABLE_OVERLAYIPIP/VXLAN 隧道启用模式Always/CrossSubnet/Neverexample/config.ymlIP_AUTODETECTION_METHOD自动探测节点 BGP IP 的方法example/config.yml其中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: AlwaysAlways所有跨节点流量都走隧道封装公有云上最省事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 分配 IPportmap 插件实现hostPort端口映射与 SNATbandwidth 插件支持 Pod 的带宽限制配合 NetworkPolicy / QoS。__CNI_MTU__与__CNI_MTU__是占位符由install-cniinit 容器根据节点实际 MTU 自动替换模板中veth_mtu: 0表示自动探测无需手工指定。3.4 安装 CNI 二进制的 init 容器calico-nodePod 通过两个 init 容器完成前置工作calico-v3.28.yaml.j2install-cni把 CNI 二进制与网络配置安装到宿主机/opt/cni/bin与/etc/cni/net.dmount-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 串联整个安装流程其完整执行顺序为创建证书请求并签发证书cfssl创建/删除 calico-etcd-secretskubectl delete兼容旧证书场景CHANGE_CA变量控制强制轮换渲染并 apply calico.yaml 清单在节点创建/etc/calico/ssl并分发证书删除默认 CNI 配置/etc/cni/net.d/10-default.conf下发 calicoctl 客户端与配置文件轮询等待 calico-node 达到 Running可选启用 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.confCalico 安装时需先删除它避免与 Calico 的10-calico.conflist冲突见 tasks/main.yml- name: 删除默认cni配置 file: path/etc/cni/net.d/10-default.conf stateabsent4.3 轮询等待安装完成由于镜像下载需要时间即便配置了 Docker 国内加速仍可能较慢kubeasz 采用轮询机制等待本节点calico-nodePod 变为 Runningtasks/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-nodePod2/2 Running以及一个calico-kube-controllersPodkubectl 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.cfgtasks/main.yml。模板内容见 calicoctl.cfg.j2apiVersion: 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 查看网卡与路由信息先在集群创建几个测试 Podkubectl run test --imagebusybox --replicas3 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 Peercalicoctl 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 PeerTCP 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_API3 etcdctl --endpointshttp://127.0.0.1:2379 get --prefix /calico # 查看 calico网络为各节点分配的网段 ETCDCTL_API3 etcdctl --endpointshttp://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 meshIBGP 全互联会导致连接数随节点数平方级增长。此时建议启用 Calico 内建的路由反射器Route ReflectorRR无 RR 时所有节点两两建立连接IBGP 全互联连接数剧增引入 RR 后普通节点只需与 RR 建立连接连接数线性增长calico-node v3.3 起支持内建 RR建议集群节点数大于 50 时启用。kubeasz 已将该能力封装进 calico-rr.yml启用方式只需两步在clusters/xxx/config.yml中设置CALICO_RR_ENABLED: trueexample/config.yml 中默认false另有CALICO_RR_NODES可手工指定 RR 节点为空时默认取所有 master 节点重新执行dk ezctl setup xxx 07。其底层执行逻辑calico-rr.yml包括为 RR 节点 patchrouteReflectorClusterID: 244.0.0.1、打上route-reflectortrue标签然后应用两个资源bgp-rr.yaml.j2定义普通节点与 RR 的 peer 规则kind: BGPPeer apiVersion: projectcalico.org/v3 metadata: name: peer-with-route-reflectors spec: nodeSelector: all() peerSelector: route-reflector truebgp-default.yaml.j2关闭全局全互联AS 号由CALICO_AS_NUMBER控制默认 64512apiVersion: projectcalico.org/v3 kind: BGPConfiguration metadata: name: default spec: logSeverityScreen: Info nodeToNodeMeshEnabled: false asNumber: {{ CALICO_AS_NUMBER }}执行完毕后所有普通节点都只与 RR 节点建立 BGP 连接peer type 变为node specificRR 节点之间也建立连接对大规模集群建议配置 23 个 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_NETWORKcalico→ 执行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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
kubeasz 安装 Calico 网络插件全指南：从证书签发到 BGP 路由验证
kubeasz 安装 Calico 网络插件全指南从证书签发到 BGP 路由验证【免费下载链接】kubeasz使用Ansible脚本安装K8S集群介绍组件交互原理方便直接不受国内网络环境影响项目地址: https://gitcode.com/GitHub_Trending/ku/kubeaszkubeasz 项目使用 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_NETWORKcalico具体配置位置参考 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: srccalico-{{ 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: srccalico-csr.json.j2 dest{{ cluster_dir }}/ssl/calico-csr.json - name: 创建 calico证书和私钥 shell: cd {{ cluster_dir }}/ssl {{ base_dir }}/bin/cfssl gencert \ -caca.pem \ -ca-keyca-key.pem \ -configca-config.json \ -profilekubernetes calico-csr.json|{{ base_dir }}/bin/cfssljson -bare calicoprofilekubernetes说明它复用了集群 CA 配置deploy/templates/ca-config.json.j2中 kubernetes profile 的用途与过期时间设置。签发完成后会得到calico.pem证书、calico-key.pem私钥以及 CA 证书ca.pem。证书的四个使用场景后续可以看到这份证书被用在四个地方全部与访问 etcd相关使用方用途calico/node 容器容器运行时访问 etcd 读写网络配置CNI 配置文件cni 插件cni 插件在创建 Pod 时访问 etcd 分配 IPcalicoctl 工具运维人员操作集群网络时访问 etcdcalico/kube-controllers同步 Kubernetes NetworkPolicy 等策略数据时访问 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 Secrettasks 主流程还会将证书打包为 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-fileetcd-caca.pem \ --from-fileetcd-keycalico-key.pem \ --from-fileetcd-certcalico.pem在 calico-v3.28.yaml.j2 中该 Secret 以defaultMode: 0400挂载到/calico-secrets目录保证证书只读且权限最小化。证书分发到节点除了打包 Secret证书还会直接分发到每个节点的/etc/calico/ssl目录供 calicoctl 客户端与 CNI 插件使用tasks/main.yml- name: 在节点创建相关目录 file: name{{ item }} statedirectory 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 为例calico-config ConfigMap网络核心配置载体包括 etcd 地址、证书路径、backend、MTU、CNI 网络配置calico-node DaemonSet每个节点一个 Pod负责路由学习bird、策略下发Felix与数据面编程calico-kube-controllers Deployment单副本控制器负责把 Kubernetes 的 NetworkPolicy、Namespace、ServiceAccount 等对象同步到 Calico 数据模型RBAC 资源calico-node、calico-kube-controllers、calico-cni-plugin三个 ServiceAccount 及对应的 ClusterRole/ClusterRoleBindingPodDisruptionBudget保护 calico-kube-controllers 在集群缩容时不被强制驱逐。3.1 关键环境变量与 {{ }} 变量映射清单模板中所有{{ }}变量均与 Ansible hosts / config 文件中的设置一一对应需要重点理解的有模板变量 / 环境变量含义配置来源ETCD_ENDPOINTSetcd 集群地址列表https 格式由 vars/main.yml 根据 etcd 组成员自动生成CALICO_IPV4POOL_CIDR→CALICO_IPV4POOL_CIDRPod 网段即{{ CLUSTER_CIDR }}hosts 文件中的CLUSTER_CIDR默认192.168.0.0/16见 config_guide.mdFELIX_DEFAULTENDPOINTTOHOSTACTIONACCEPT默认允许 Pod 到 Node 的网络流量硬编码于模板CALICO_NETWORKING_BACKEND数据面 backendbird/vxlan/noneexample/config.ymlCALICO_ENABLE_OVERLAYIPIP/VXLAN 隧道启用模式Always/CrossSubnet/Neverexample/config.ymlIP_AUTODETECTION_METHOD自动探测节点 BGP IP 的方法example/config.yml其中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: AlwaysAlways所有跨节点流量都走隧道封装公有云上最省事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 分配 IPportmap 插件实现hostPort端口映射与 SNATbandwidth 插件支持 Pod 的带宽限制配合 NetworkPolicy / QoS。__CNI_MTU__与__CNI_MTU__是占位符由install-cniinit 容器根据节点实际 MTU 自动替换模板中veth_mtu: 0表示自动探测无需手工指定。3.4 安装 CNI 二进制的 init 容器calico-nodePod 通过两个 init 容器完成前置工作calico-v3.28.yaml.j2install-cni把 CNI 二进制与网络配置安装到宿主机/opt/cni/bin与/etc/cni/net.dmount-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 串联整个安装流程其完整执行顺序为创建证书请求并签发证书cfssl创建/删除 calico-etcd-secretskubectl delete兼容旧证书场景CHANGE_CA变量控制强制轮换渲染并 apply calico.yaml 清单在节点创建/etc/calico/ssl并分发证书删除默认 CNI 配置/etc/cni/net.d/10-default.conf下发 calicoctl 客户端与配置文件轮询等待 calico-node 达到 Running可选启用 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.confCalico 安装时需先删除它避免与 Calico 的10-calico.conflist冲突见 tasks/main.yml- name: 删除默认cni配置 file: path/etc/cni/net.d/10-default.conf stateabsent4.3 轮询等待安装完成由于镜像下载需要时间即便配置了 Docker 国内加速仍可能较慢kubeasz 采用轮询机制等待本节点calico-nodePod 变为 Runningtasks/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-nodePod2/2 Running以及一个calico-kube-controllersPodkubectl 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.cfgtasks/main.yml。模板内容见 calicoctl.cfg.j2apiVersion: 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 查看网卡与路由信息先在集群创建几个测试 Podkubectl run test --imagebusybox --replicas3 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 Peercalicoctl 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 PeerTCP 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_API3 etcdctl --endpointshttp://127.0.0.1:2379 get --prefix /calico # 查看 calico网络为各节点分配的网段 ETCDCTL_API3 etcdctl --endpointshttp://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 meshIBGP 全互联会导致连接数随节点数平方级增长。此时建议启用 Calico 内建的路由反射器Route ReflectorRR无 RR 时所有节点两两建立连接IBGP 全互联连接数剧增引入 RR 后普通节点只需与 RR 建立连接连接数线性增长calico-node v3.3 起支持内建 RR建议集群节点数大于 50 时启用。kubeasz 已将该能力封装进 calico-rr.yml启用方式只需两步在clusters/xxx/config.yml中设置CALICO_RR_ENABLED: trueexample/config.yml 中默认false另有CALICO_RR_NODES可手工指定 RR 节点为空时默认取所有 master 节点重新执行dk ezctl setup xxx 07。其底层执行逻辑calico-rr.yml包括为 RR 节点 patchrouteReflectorClusterID: 244.0.0.1、打上route-reflectortrue标签然后应用两个资源bgp-rr.yaml.j2定义普通节点与 RR 的 peer 规则kind: BGPPeer apiVersion: projectcalico.org/v3 metadata: name: peer-with-route-reflectors spec: nodeSelector: all() peerSelector: route-reflector truebgp-default.yaml.j2关闭全局全互联AS 号由CALICO_AS_NUMBER控制默认 64512apiVersion: projectcalico.org/v3 kind: BGPConfiguration metadata: name: default spec: logSeverityScreen: Info nodeToNodeMeshEnabled: false asNumber: {{ CALICO_AS_NUMBER }}执行完毕后所有普通节点都只与 RR 节点建立 BGP 连接peer type 变为node specificRR 节点之间也建立连接对大规模集群建议配置 23 个 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_NETWORKcalico→ 执行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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考