K8s v1.23.17 + Calico（Tigera Operator）部署文档

适用环境：Ubuntu 20.04/22.04、国内网络、Docker 运行时、3 节点集群

环境信息

一、所有节点都要做（Master + Worker 共 3 台）

1.1 系统基础配置

# 关闭 swap
swapoff -a
sed -i '/swap/d' /etc/fstab

# 关闭防火墙（或放行 6443、10250-10255 等 K8s 端口）
ufw disable

# 加载内核模块
cat > /etc/modules-load.d/k8s.conf << 'EOF'
overlay
br_netfilter
EOF
modprobe overlay
modprobe br_netfilter

# 内核参数
cat > /etc/sysctl.d/k8s.conf << 'EOF'
net.bridge.bridge-nf-call-iptables = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward = 1
EOF
sysctl --system

1.2 安装 Docker

# 卸载旧版本
apt-get remove -y docker docker-engine docker.io containerd runc 2>/dev/null

# 安装依赖
apt-get update
apt-get install -y apt-transport-https ca-certificates curl gnupg lsb-release

# 添加 Docker 官方源
curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg | gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://mirrors.aliyun.com/docker-ce/linux/ubuntu $(lsb_release -cs) stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安装
apt-get update
apt-get install -y docker-ce docker-ce-cli containerd.io

# 配置镜像加速 + cgroupdriver
cat > /etc/docker/daemon.json << 'EOF'
{
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "https://dockerhub.timeweb.cloud",
    "https://docker.1ms.run"
  ],
  "exec-opts": ["native.cgroupdriver=systemd"],
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "100m",
    "max-file": "3"
  }
}
EOF

systemctl daemon-reload
systemctl enable docker --now
systemctl restart docker

1.3 安装 kubeadm / kubelet / kubectl

# 添加阿里云 K8s 源
curl -fsSL https://mirrors.aliyun.com/kubernetes/apt/doc/apt-key.gpg | apt-key add -
cat > /etc/apt/sources.list.d/kubernetes.list << 'EOF'
deb https://mirrors.aliyun.com/kubernetes/apt/ kubernetes-xenial main
EOF

# 安装指定版本
apt-get update
apt-get install -y kubeadm=1.23.17-00 kubelet=1.23.17-00 kubectl=1.23.17-00

# 锁定版本，防止 apt upgrade 误升级
apt-mark hold kubeadm kubelet kubectl

# 启动 kubelet
systemctl enable kubelet

二、Master 节点初始化

以下操作仅在 master 上执行。

2.1 拉取 K8s 镜像

kubeadm config images pull \
  --kubernetes-version=v1.23.17 \
  --image-repository=registry.aliyuncs.com/google_containers

国内必须用 registry.aliyuncs.com/google_containers，默认的 k8s.gcr.io 连不上。这一步可能要等 1-2 分钟，7 个镜像拉完会有 [config/images] Pulled 输出。

2.2 初始化集群

kubeadm init \
  --kubernetes-version=v1.23.17 \
  --image-repository=registry.aliyuncs.com/google_containers \
  --pod-network-cidr=10.244.0.0/16 \
  --service-cidr=10.96.0.0/12

成功后会输出类似这样的内容，把 kubeadm join 那一整行保存下来，worker 加入要用：

kubeadm join 192.168.0.34:6443 --token xxxxxx \
    --discovery-token-ca-cert-hash sha256:xxxxxx

2.3 配置 kubectl

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

2.4 安装 Calico 网络插件（Tigera Operator）

# 先确认你的物理网卡名
ip addr show | grep -E "^[0-9]+:" | awk -F': ' '{print $2}'
# 常见结果：ens34、ens33、eth0 等，记下来

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

# 创建 Calico 配置（把 interface 改成你实际的网卡名）
kubectl apply -f - << 'EOF'
apiVersion: operator.tigera.io/v1
kind: Installation
metadata:
  name: default
spec:
  calicoNetwork:
    ipPools:
    - blockSize: 24
      cidr: 10.244.0.0/16
      encapsulation: None
      natOutgoing: Enabled
    nodeAddressAutodetectionV4:
      interface: ens.*
EOF

关键：interface: ens.* 要根据你的实际网卡名修改。比如网卡是 ens34 就写 ens.*，是 eth0 就写 eth.*。写错了 calico-node 会报 no valid host interfaces found。

2.5 验证 Master 就绪

# 等 30-60 秒，Calico 会自动完成部署
kubectl get pods -n calico-system
kubectl get nodes

看到 master 状态 Ready，且 calico-node、calico-kube-controllers、calico-typha 都 Running 即可。

三、Worker 节点加入集群

以下操作在每个 worker 上执行。

3.1 拉取 K8s 镜像

kubeadm config images pull \
  --kubernetes-version=v1.23.17 \
  --image-repository=registry.aliyuncs.com/google_containers

3.2 加入集群

把 master 初始化时输出的 kubeadm join 命令粘贴过来执行。如果丢了，在 master 上重新生成：

# 在 master 上执行
kubeadm token create --print-join-command

把输出复制到每个 worker 上执行：

kubeadm join 192.168.0.34:6443 --token xxxxxx \
    --discovery-token-ca-cert-hash sha256:xxxxxx

3.3 回到 Master 验证

kubectl get nodes

三个节点都 Ready 即部署完成。Calico 由 Operator 自动部署到 worker 上，不需要手动干预。

四、故障排查速查

4.1 镜像拉不下来

现象：ImagePullBackOff 或 ErrImagePull

原因：k8s.gcr.io 和 docker.io 在国内被墙。

解决：

• K8s 系镜像：加 --image-repository=registry.aliyuncs.com/google_containers
• Docker Hub 镜像：确认 /etc/docker/daemon.json 里配了 registry-mirrors

4.2 Calico 节点 CrashLoopBackOff

现象：calico-node 反复重启

排查：

kubectl logs -n calico-system -l k8s-app=calico-node | tail -20

常见原因：

4.3 节点 NotReady

通常是网络插件还没部署到该节点。Operator 会在大约 30-60 秒内自动完成，等一等即可。

kubectl get pods -n calico-system -o wide

确认该节点上已经有 calico-node 在运行。

4.4 忘记 join 命令

# 在 master 上重新生成
kubeadm token create --print-join-command

4.5 完全重置（重来）

# 在需要重置的节点上执行
kubeadm reset -f
rm -rf /etc/cni/net.d/*
rm -rf /var/lib/calico /var/lib/cni
iptables -F && iptables -t nat -F && iptables -t mangle -F
ip link delete cni0 2>/dev/null
ip link delete tunl0 2>/dev/null
systemctl restart docker

五、关键注意事项

1. Pod CIDR（10.244.0.0/16）不能和公司内网网段重叠，否则路由冲突
2. Service CIDR（10.96.0.0/12）不能和 Pod CIDR 重叠
3. 国内环境永远用 registry.aliyuncs.com/google_containers 替代 k8s.gcr.io
4. Calico 用 Tigera Operator 安装，不要手写 yaml — Operator 自动处理 RBAC、CNI 二进制、IPAM、证书
5. Worker 节点不需要配 kubectl — 所有管理操作在 master 上执行
6. 安装后锁定版本：apt-mark hold kubeadm kubelet kubectl 防止误升级导致集群版本不一致