Skip to main content

集群初始化 · kubeadm 与 Calico

前置操作已完成(见 02-安装前置操作.md),三台节点:

  • K8S-Master 192.168.10.12(控制平面)
  • K8S-Node01 192.168.10.13(工作节点)
  • K8S-Node02 192.168.10.14(工作节点)
  • 软件版本:kubeadm/kubelet/kubectl v1.36.3,containerd v2.3.3
  • CNI 方案:Calico v3.29.1(用户偏好)
  • ✅ 2026-08-09 集群搭建完成:三节点 Ready,Calico + CoreDNS + 控制面全部 Running

〇、K8S 网络网段体系(重要概念)​

四个网段的关系​

只有节点网段是物理的,Pod/Service 网段全是集群内部虚拟网段。

网段参数作用是否物理
节点网段 Node Network无(物理网络)节点间通信、kubeadm join、kubectl 访问 apiserver✅ 物理
Pod 网段--pod-network-cidr给每个 Pod 分配独立 IP❌ 虚拟
Service 网段--service-cidr给每个 Service 分配 VIP(ClusterIP)❌ 虚拟
CNI 落地层-把 Pod 网段切分给各节点并建立 Overlay 隧道❌ 逻辑

网段如何限制集群规模​

  • Pod 网段是一个地址池(如 10.244.0.0/16),init 时一次定死,之后不可改
  • 节点加入时按需分配:CNI 从池中取一个空闲子网段(Flannel 固定 /24,Calico 可配置 IPPool),分配记录持久化在 etcd,永不重划、不复用
  • 扩容节点 = 从池里继续取空闲段,老节点完全不受影响
  • 节点数上限 = 池子能切出的子网段数(10.244.0.0/16 按 /24 → 最多 256 节点)
  • 单节点 Pod 上限 = 每节点分到的子网段容量(Calico 可用 IPPool 掩码控制)
  • Pod 网段必须与 CNI 插件默认网段一致:Flannel 默认 10.244.0.0/16,Calico 默认 192.168.0.0/16

超过 256 节点怎么办(扩容规划)​

节点上限 = 池子大小 ÷ 每节点分配粒度,两条路:

  1. 扩大 Pod 网段:/16=256节点、/12=4096节点、/8=6.5万节点,init 时一次定死
  2. 减小分配粒度:Flannel 固定 /24/节点;Calico IPPool 可配 /26 甚至 /28(默认 /26=64IP),同样池子节点上限 ×4

K8S 官方规模上限(网段之外的瓶颈)​

  • 单集群 ≤5000 节点、≤15 万 Pod、≤30 万容器、每节点 ≤110 Pod
  • 更大规模时瓶颈在 etcd(写入压力)、kube-apiserver(请求压力)、controller-manager(watch 数量)
  • 规划经验:网段先设足(生产常用 /12 或 /8),实际先撞性能墙而非 IP 墙

本项目网段决策​

  • Pod 网段:10.244.0.0/16(自定义,方案2,改 Calico IPPool 匹配)
  • Service 网段:10.96.0.0/12(kubeadm 默认)

常见疑问:为什么 Service 网段(/12)比 Pod 网段(/16)还大?​

  • CIDR 中 /12 比 /16 大 16 倍:/12≈100万地址,/16≈6.5万地址
  • 这是历史默认值:10.96.0.0/12 是 kubeadm 沿用默认,10.244.0.0/16 是 Flannel 默认,不是配套设计
  • 使用量上 Pod 通常远多于 Service,但 Service 网段有结构性预留(前10个IP、系统服务),且实际 Service 数量远少于 Pod
  • 生产建议:可反过来配(Pod 网段更大),如 pod=/12 service=/16;学习环境用默认即可

一、kubeadm init(Master 上执行)​

会做什么​

  1. 生成集群 TLS 证书(CA、apiserver、etcd 等)
  2. 部署 etcd(集群状态存储)
  3. 把控制平面组件(kube-apiserver / controller-manager / scheduler)作为静态 Pod 跑起来
  4. 生成 kubeconfig(/etc/kubernetes/admin.conf)
  5. 输出 worker 节点的 join 命令

本项目实际使用的命令​

kubeadm init \
--image-repository registry.aliyuncs.com/google_containers \
--kubernetes-version v1.36.3 \
--pod-network-cidr=10.244.0.0/16 \
--service-cidr=10.96.0.0/12 \
--service-dns-domain=cluster.local \
--apiserver-advertise-address=192.168.10.12 \
--token-ttl=24h

参数说明:

  • --image-repository:控制平面镜像仓库(registry.k8s.io 国内不可达,用阿里云)
  • --kubernetes-version:指定版本,避免探测到最新版
  • --pod-network-cidr:Pod 网段,必须与 CNI 插件 IPPool 一致(本项目用 10.244.0.0/16)
  • --service-cidr:Service VIP 网段,默认 10.96.0.0/12
  • --service-dns-domain:集群内 DNS 域名后缀
  • --apiserver-advertise-address:apiserver 公告 IP(单网卡可省,显式写更稳)
  • --token-ttl:join token 有效期,默认 24h

镜像预拉:kubeadm config images pull --image-repository registry.aliyuncs.com/google_containers

初始化完成后输出​

  • 成功后提示配置 kubectl、部署 CNI、以及 join 命令
  • join 命令若被截断,用 kubeadm token create --print-join-command 重新生成

二、配置 kubectl(Master)​

init 成功后执行(root 用户):

mkdir -p $HOME/.kube
cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
chown $(id -u):$(id -g) $HOME/.kube/config

本次实际用了临时方式 export KUBECONFIG=/etc/kubernetes/admin.conf(root 会话)。 要持久化:echo 'export KUBECONFIG=/etc/kubernetes/admin.conf' >> ~/.bashrc

验证:

kubectl get nodes
kubectl get pods -A

三、安装 CNI 网络插件(Calico)​

为什么:没有 CNI,节点 Ready 但 Pod 无法互通,且核心组件起不来(coredns Pending、节点 NotReady)​

Calico vs Flannel​

特性CalicoFlannel
网络模式BGP 路由(三层)VXLAN Overlay(二层)
性能更高(直接路由)稍低(隧道封装)
NetworkPolicy支持不支持
默认 Pod 网段192.168.0.0/1610.244.0.0/16
适用生产、需要策略控制简单场景

安装(Master 上执行)​

# 下载 Calico 清单(国内可能需要代理)
curl -L https://raw.githubusercontent.com/projectcalico/calico/v3.29.1/manifests/calico.yaml -o ~/calico.yaml

# 修改 IPPool 网段:把 CALICO_IPV4POOL_CIDR 改为与 --pod-network-cidr 一致
grep -n 'CALICO_IPV4POOL_CIDR' calico.yaml

kubectl apply -f calico.yaml

本次实际做法(代理方案)​

  • 给 containerd 配置了 HTTP 代理(systemd drop-in,见踩坑记录)
  • 预拉官方镜像:crictl pull docker.io/calico/cni:v3.29.1 / node / kube-controllers
  • 修改 calico.yaml 中 CALICO_IPV4POOL_CIDR 为 10.244.0.0/16

验证​

kubectl get ippool default-ipv4-ippool -o jsonpath='{.spec.cidr}'
kubectl get ds -n kube-system calico-node # 每节点一个 calico-node
kubectl get nodes # master 变 Ready,coredns 跟着 Ready

四、Worker 节点加入(Node01 / Node02)​

前置:Node 必须改 containerd sandbox 镜像(⚠️ 大坑,见踩坑记录)​

两台 Node 的 /etc/containerd/config.toml 必须把 sandbox 指向阿里云,否则 join 后 kubelet 建沙箱会拉被墙的 registry.k8s.io/pause,直接挂。

# 三台都要执行(Master 上 init 前也必须做)
sed -i "s|sandbox = 'registry.k8s.io/pause:3.10.2'|sandbox = 'registry.aliyuncs.com/google_containers/pause:3.10.2'|" /etc/containerd/config.toml
systemctl restart containerd

# Node 预拉 pause,避免 join 时现拉
crictl pull registry.aliyuncs.com/google_containers/pause:3.10.2

Node 上 /etc/crictl.yaml 可能不存在,crictl 默认会先连 cri-o/cri-dockerd 的 socket 报错。需配置:

cat > /etc/crictl.yaml <<'EOF'
runtime-endpoint: unix:///run/containerd/containerd.sock
image-endpoint: unix:///run/containerd/containerd.sock
timeout: 10
debug: false
EOF

生成 join 命令(Master 上执行)​

kubeadm token create --print-join-command

输出示例:

kubeadm join 192.168.10.12:6443 --token <token> --discovery-token-ca-cert-hash sha256:<hash>

在每台 Node 上以 root 执行 join​

kubeadm join 192.168.10.12:6443 --token <token> --discovery-token-ca-cert-hash sha256:<hash>

如报 CRI socket 找不到,手动加 --cri-socket unix:///run/containerd/containerd.sock

token 有效期 24h(本项目 init 时 --token-ttl=24h),过期重新生成。

五、验证集群(最终结果)​

kubectl get nodes -o wide
kubectl get pods -A -o wide

本项目最终状态(2026-08-09 21:42)​

NAME         STATUS   ROLES           INTERNAL-IP
k8s-master Ready control-plane 192.168.10.12
k8s-node01 Ready <none> 192.168.10.13
k8s-node02 Ready <none> 192.168.10.14
  • 控制面:etcd / apiserver / controller-manager / scheduler 全 Running
  • CNI:每节点一个 calico-node Running,calico-kube-controllers Running,IPPool = 10.244.0.0/16
  • DNS:coredns 双副本 Running
  • Pod 实际拿到了 10.244.235.x 网段(master 上 coredns/calico-controller 可见)

六、知识点:为什么控制面 Pod 的 IP 是节点 IP(hostNetwork)​

kubectl get pods -A -o wide 里两类 Pod IP 不一样:

  • 节点 IP(192.168.10.x):calico-node、kube-proxy、etcd、kube-apiserver、kube-controller-manager、kube-scheduler
  • Pod 网段 IP(10.244.235.x):coredns、calico-kube-controllers

原因:前者 spec 里都设了 hostNetwork: true——Pod 不创建独立网络命名空间,直接共享节点网卡/路由/iptables,CNI 不分配 Pod IP,所以显示节点 IP。

为什么这些组件必须用 hostNetwork​

组件原因
calico-node要操作节点 iptables、路由表、建 veth,必须待在节点网络栈里
kube-proxy要往节点 iptables/ipvs 写规则,把 Service VIP 转发到 Pod
kube-apiserver / etcd必须稳定监听固定 IP:6443(kubelet/join/kubectl 都要连),hostNetwork 保证 IP 永远稳定
controller-manager / scheduler与控制平面同机部署,hostNetwork 使控制平面不依赖 Pod 网络

关键:控制平面与 CNI 是"先有鸡还是先有蛋"​

kubelet 启动时要先拉起 apiserver,但那时 Calico 还没装,Pod 网络根本不存在。所以控制平面必须 hostNetwork + 静态 Pod(kubelet 直接拉 /etc/kubernetes/manifests/ 下的 yaml),完全不依赖 CNI。这也解释了:pause 镜像拉不到时 apiserver 整个起不来。

普通业务 Pod 走正常流程:CNI 分配 Pod IP → 建 veth → 进独立 netns → 经 Calico BGP/隧道与其他 Pod 互通。

CKA 考点:hostNetwork 意味着"共享节点网络、无独立 Pod IP、不经 CNI、不受 NetworkPolicy 约束"。

常见排障​

  • kubeadm init 失败 → 检查 journalctl -u kubelet -f 和 crictl images(镜像是否齐全)
  • 节点 NotReady → 多半是 CNI 没装或 Pod 网段与 IPPool 不一致
  • 证书/token 报错 → kubeadm reset 后重新 init(重置命令见下)

kubeadm reset(重来)​

kubeadm reset -f
rm -rf /etc/kubernetes /var/lib/kubelet /var/lib/etcd ~/.kube

易踩坑记录(持续更新)​

1. kubeadm init 卡住/失败:pause 沙箱镜像被墙(本次最大的坑)​

现象:init 失败,journalctl -u kubelet 刷屏 Unable to register mirror pod because node is not registered yet、connection refused 根因链:

  • kubelet 建任何静态 Pod 前都要先建 sandbox,sandbox 要拉 pause 镜像
  • containerd 2.x 的 sandbox 镜像地址在 pinned_images.sandbox,默认 registry.k8s.io/pause:3.10.2(国内不可达)
  • pause 拉不到 → 沙箱建不了 → 所有静态 Pod(etcd/apiserver/...)都起不来 → apiserver 不监听 6443 → kubelet 循环报错 解决:改 /etc/containerd/config.toml 的 pinned_images.sandbox 为阿里云地址,systemctl restart containerd。 经验:kubelet 的循环报错多是果,要顺藤摸瓜找根因(沙箱镜像 → CRI → apiserver)。

2. containerd 2.x 配置项和 1.x 不一样​

  • 1.x:[plugins."io.containerd.grpc.v1.cri"].sandbox_image = "..."(旧名 sandbox_image)
  • 2.x:[plugins.'io.containerd.cri.v1.images'.pinned_images].sandbox = "..."(新名 pinned_images)
  • 网上资料大量是 1.x 写法,2.x 直接套会不生效或报错

3. Node 节点 join 前必须同步改 sandbox 镜像​

Master init 时改好了,Node 上的 containerd 配置不会自动同步。Node join 后 kubelet 建沙箱一样拉被墙的 pause → kubelet 挂。 三台(甚至以后每加一台 Node)都要执行改 sandbox + 重启 containerd。

4. crictl 默认 endpoint 不是 containerd​

crictl 默认按顺序探测 cri-o/dockershim,没有 /etc/crictl.yaml 时连 /run/crio/crio.sock 报错。 解决:写 /etc/crictl.yaml 指定 runtime-endpoint: unix:///run/containerd/containerd.sock。

5. containerd 拉镜像走代理:systemd 服务不继承终端代理​

  • containerd 是 systemd 服务,不吃 export https_proxy=...
  • 需写 drop-in:
    mkdir -p /etc/systemd/system/containerd.service.d
    cat > /etc/systemd/system/containerd.service.d/http-proxy.conf <<'EOF'
    [Service]
    Environment="HTTP_PROXY=http://127.0.0.1:7890"
    Environment="HTTPS_PROXY=http://127.0.0.1:7890"
    Environment="NO_PROXY=localhost,127.0.0.1,10.244.0.0/16,192.168.0.0/16"
    EOF
    systemctl daemon-reload
    systemctl restart containerd
  • NO_PROXY 一定要把集群内网网段(Pod/Service/节点网段)排除,避免 Pod 间流量误走代理

6. 修改含特殊字符配置用 sed 注意转义​

config.toml 里地址含 . / 等,用 | 作 sed 分隔符 + 精确匹配,避免误伤。

7. Tabby 会话权限会回到普通用户​

SSH 会话有时停在 xiao(非 root),直接 sed /etc/containerd 会权限不够、systemctl 会弹 polkit 认证框(交互式,AI 无法代输密码)。 操作系统级配置前先 whoami 确认,非 root 则先 sudo su - 提权。