Kubernetes 单机部署全攻略：从零到一的实践指南

一、为什么需要Kubernetes单机部署？

在开发测试、边缘计算或小型生产环境中，Kubernetes单机部署（Single-Node Kubernetes）是一种高效且低成本的解决方案。相比传统的多节点集群，单机部署具有以下优势：

1. 资源占用低：无需多台物理机或虚拟机，单台服务器即可运行完整K8s环境。
2. 部署速度快：省去网络配置、节点注册等复杂步骤，10分钟内可完成初始化。
3. 成本可控：适合预算有限的个人开发者或初创企业。
4. 隔离性强：独立环境避免与生产集群冲突，适合CI/CD流水线或实验性功能验证。

典型应用场景包括：本地开发环境搭建、IoT设备管理、教学演示以及轻量级应用部署。

二、环境准备与前置条件

1. 硬件要求

• CPU：至少2核（建议4核以上）
• 内存：8GB RAM（生产环境建议16GB+）
• 磁盘：50GB以上可用空间（SSD更佳）
• 网络：支持IPv4/IPv6双栈（可选）

2. 操作系统选择

推荐使用以下Linux发行版：

• Ubuntu 22.04 LTS：兼容性好，社区支持丰富
• CentOS Stream 9：企业级稳定性，适合传统用户
• Rocky Linux 9：CentOS替代方案，长期支持

禁用Swap分区（K8s要求）：

sudo swapoff -a
# 永久禁用需注释/etc/fstab中的swap行

3. 容器运行时安装

K8s 1.24+版本移除了对Docker的直接支持，需通过CRI接口兼容：

# 安装containerd（推荐）
cat <<EOF | sudo tee /etc/modules-load.d/containerd.conf
overlay
br_netfilter
EOF
sudo modprobe overlay
sudo modprobe br_netfilter
# 配置sysctl参数
cat <<EOF | sudo tee /etc/sysctl.d/99-kubernetes-cri.conf
net.bridge.bridge-nf-call-iptables  = 1
net.ipv4.ip_forward                 = 1
net.bridge.bridge-nf-call-ip6tables = 1
EOF
sudo sysctl --system

安装containerd：

sudo apt-get install -y containerd
sudo mkdir -p /etc/containerd
containerd config default | sudo tee /etc/containerd/config.toml
# 修改配置启用systemd cgroup
sudo sed -i 's/SystemdCgroup \= false/SystemdCgroup \= true/' /etc/containerd/config.toml
sudo systemctl restart containerd

三、Kubernetes核心组件部署

1. 使用kubeadm初始化集群

# 安装依赖工具
sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates curl
# 添加K8s仓库
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.28/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
echo "deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.28/deb/ /" | sudo tee /etc/apt/sources.list.d/kubernetes.list
# 安装kubeadm/kubelet/kubectl
sudo apt-get update
sudo apt-get install -y kubelet kubeadm kubectl
sudo systemctl enable kubelet
# 初始化控制平面（单机模式需跳过网络插件）
sudo kubeadm init --pod-network-cidr=10.244.0.0/16 --ignore-preflight-errors=NumCPU

2. 配置kubectl

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

3. 部署CNI网络插件（以Calico为例）

kubectl create -f https://raw.githubusercontent.com/projectcalico/calico/v3.26.1/manifests/tigera-operator.yaml
kubectl create -f https://raw.githubusercontent.com/projectcalico/calico/v3.26.1/manifests/custom-resources.yaml

验证节点状态：

kubectl get nodes
# 输出应显示：
# NAME       STATUS   ROLES           AGE   VERSION
# localhost Ready    control-plane  5m    v1.28.0

四、关键配置优化

1. 资源限制调整

编辑/etc/kubernetes/kubelet.conf，添加：

{
  "kind": "KubeletConfiguration",
  "apiVersion": "kubelet.config.k8s.io/v1beta1",
  "evictionHard": {
    "memory.available": "200Mi",
    "nodefs.available": "10%"
  }
}

重启服务：

sudo systemctl daemon-reload
sudo systemctl restart kubelet

2. 启用Dashboard（可选）

kubectl apply -f https://raw.githubusercontent.com/kubernetes/dashboard/v2.7.0/aio/deploy/recommended.yaml
# 创建ServiceAccount并获取Token
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: ServiceAccount
metadata:
  name: admin-user
  namespace: kubernetes-dashboard
EOF
kubectl create token admin-user

3. 持久化存储配置

使用hostPath作为本地存储示例：

apiVersion: v1
kind: PersistentVolume
metadata:
  name: local-pv
spec:
  capacity:
    storage: 10Gi
  accessModes:
    - ReadWriteOnce
  hostPath:
    path: /mnt/data
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: local-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 5Gi

五、常见问题解决方案

1. 节点状态NotReady

现象：kubectl get nodes显示NotReady
原因：CNI插件未正确部署或kubelet崩溃
解决：

# 检查CNI插件状态
kubectl get pods -n kube-system | grep calico
# 查看kubelet日志
journalctl -u kubelet -n 100 --no-pager

2. 镜像拉取失败

现象：ImagePullBackOff错误
原因：网络问题或镜像仓库认证失败
解决：

# 配置国内镜像源（以阿里云为例）
cat <<EOF | kubectl create -f -
apiVersion: v1
kind: ConfigMap
metadata:
  name: registry-config
  namespace: kube-system
data:
  registry.yaml: |
    mirrors:
      "docker.io":
        endpoint:
          - "https://registry.cn-hangzhou.aliyuncs.com"
EOF

3. 资源不足错误

现象：OOMKilled或Evicted
解决：

• 调整Pod的resources.requests/limits
• 增加节点资源或优化应用配置
• 使用kubectl top nodes监控资源使用

六、进阶实践建议

1. 备份与恢复：

   • 使用etcdctl snapshot save定期备份
   • 测试恢复流程确保数据安全

2. 自动化部署：

   • 编写Ansible/Terraform脚本实现一键部署
   • 示例Ansible任务片段：
     ```yaml
   • name: Initialize Kubernetes cluster
     command: kubeadm init —pod-network-cidr=10.244.0.0/16
     args:
     creates: /etc/kubernetes/admin.conf
     ```

3. 性能调优：

   • 调整kube-apiserver的--default-not-ready-toleration-seconds参数
   • 优化etcd的--quota-backend-bytes设置

七、总结与展望

Kubernetes单机部署为开发者和中小企业提供了轻量级的容器编排解决方案。通过本文的实践指南，读者可以：

1. 在30分钟内完成从环境准备到集群部署的全流程
2. 掌握关键组件的配置原理与故障排查方法
3. 根据实际需求进行定制化优化

未来可进一步探索：

• 与K3s/MicroK8s等轻量级发行版的对比
• 在Windows/macOS上的单机部署方案
• 结合GitOps实现环境管理的自动化

建议读者持续关注K8s官方文档（https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/single-node/），及时获取最新版本的安全更新与功能增强。