Kubernetes (K8S) 在 Linux 上的安装疑难解答指南

常见安装问题及解决方案

1. 系统要求不满足

症状: 安装过程中出现内核参数或系统版本警告

解决方案:

# 检查并设置内核参数
cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-ip6tables = 1
net.bridge.bridge-nf-call-iptables = 1
EOF
sudo sysctl --system

# 禁用交换空间 (临时)
sudo swapoff -a
# 永久禁用 (注释掉/etc/fstab中的swap行)
sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab

2. 容器运行时问题

症状: kubelet 无法启动，报错关于容器运行时

解决方案:

# 检查容器运行时状态
sudo systemctl status docker  # 对于Docker
sudo systemctl status containerd  # 对于containerd

# 安装Docker CE (如果使用Docker作为运行时)
sudo apt-get update && sudo apt-get install -y \
    apt-transport-https ca-certificates curl software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository \
   "deb [arch=amd64] https://download.docker.com/linux/ubuntu \
   $(lsb_release -cs) \
   stable"
sudo apt-get update && sudo apt-get install -y docker-ce

# 配置Docker使用systemd作为cgroup驱动
sudo mkdir /etc/docker
cat <<EOF | sudo tee /etc/docker/daemon.json
{
  "exec-opts": ["native.cgroupdriver=systemd"],
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "100m"
  },
  "storage-driver": "overlay2"
}
EOF
sudo systemctl restart docker

3. kubeadm init 失败

症状: kubeadm init 命令执行失败，出现各种错误

解决方案:

# 重置环境 (如果之前尝试过安装)
sudo kubeadm reset -f
sudo rm -rf /etc/cni/net.d
sudo rm -rf $HOME/.kube/config

# 重新初始化 (使用国内镜像源)
sudo kubeadm init \
  --image-repository registry.aliyuncs.com/google_containers \
  --pod-network-cidr=10.244.0.0/16 \
  --apiserver-advertise-address=<your-ip-address>

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

4. 网络插件问题

症状: Pod 处于 Pending 状态，coredns 无法启动

解决方案:

# 安装Flannel网络插件
kubectl apply -f https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml

# 或者安装Calico网络插件
kubectl apply -f https://docs.projectcalico.org/manifests/calico.yaml

# 检查网络组件状态
kubectl get pods -n kube-system

5. 节点无法加入集群

症状: worker节点无法加入master节点

解决方案:

# 在master节点上检查token
kubeadm token list
# 如果token过期，创建新token
kubeadm token create --print-join-command

# 在worker节点上执行正确的join命令
sudo kubeadm join <master-ip>:6443 --token <token> --discovery-token-ca-cert-hash sha256:<hash>

高级故障排除技巧

1. 检查组件日志

# 查看kubelet日志
journalctl -u kubelet -f

# 查看特定pod日志
kubectl logs <pod-name> -n <namespace>

# 查看容器运行时日志
journalctl -u docker -f  # 对于Docker
journalctl -u containerd -f  # 对于containerd

2. 证书问题排查

# 检查证书有效期
openssl x509 -in /etc/kubernetes/pki/apiserver.crt -noout -text | grep -A 2 Validity

# 手动更新证书 (如果过期)
kubeadm alpha certs renew all

3. 资源不足问题

# 检查系统资源
free -h
df -h
top

# 调整kubelet资源预留
# 编辑/etc/kubernetes/kubelet.conf 添加:
# KUBELET_EXTRA_ARGS=--system-reserved=cpu=500m,memory=500Mi --kube-reserved=cpu=500m,memory=500Mi

预防性建议

1. 使用兼容的版本组合:

   • 参考Kubernetes官方发布的版本兼容性矩阵
   • 保持K8S版本与容器运行时版本兼容

2. 生产环境建议:

   # 使用高可用配置
   kubeadm init --control-plane-endpoint "LOAD_BALANCER_DNS:LOAD_BALANCER_PORT" \
    --upload-certs
   
   # 使用外部etcd集群
   kubeadm init --config=kubeadm-config.yaml
   

3. 备份关键数据:

   # 备份etcd数据
   ETCDCTL_API=3 etcdctl --endpoints=https://127.0.0.1:2379 \
    --cacert=/etc/kubernetes/pki/etcd/ca.crt \
    --cert=/etc/kubernetes/pki/etcd/server.crt \
    --key=/etc/kubernetes/pki/etcd/server.key \
    snapshot save snapshot.db
   

4. 使用自动化工具:

   • 考虑使用kubespray、kops等工具进行自动化部署
   • 使用Terraform进行基础设施编排

通过以上方法，您应该能够解决大多数Kubernetes在Linux上的安装问题。如果遇到特定错误，建议检查相关组件的日志以获取更详细的错误信息。