集群初始化 · 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 节点怎么办(扩容规划)
节点上限 = 池子大小 ÷ 每节点分配粒度,两条路:
- 扩大 Pod 网段:/16=256节点、/12=4096节点、/8=6.5万节点,init 时一次定死
- 减小分配粒度: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 上执行)
会做什么
- 生成集群 TLS 证书(CA、apiserver、etcd 等)
- 部署 etcd(集群状态存储)
- 把控制平面组件(kube-apiserver / controller-manager / scheduler)作为静态 Pod 跑起来
- 生成 kubeconfig(/etc/kubernetes/admin.conf)
- 输出 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
| 特性 | Calico | Flannel |
|---|---|---|
| 网络模式 | BGP 路由(三层) | VXLAN Overlay(二层) |
| 性能 | 更高(直接路由) | 稍低(隧道封装) |
| NetworkPolicy | 支持 | 不支持 |
| 默认 Pod 网段 | 192.168.0.0/16 | 10.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-nodeRunning,calico-kube-controllersRunning,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 - 提权。