Kubernetes（k8s）单机环境部署

1. Kubernetes (K8s) 简介

此文适合新手快速上手，涵盖安装、配置、基本使用单机环境

2. 环境

系统要求

操作系统：Linux（Ubuntu/CentOS）或 macOS（开发环境）
内存：至少 2GB（推荐 4GB+）
CPU：2 核+
存储：20GB+ 可用空间

安装工具

Docker（K8s 依赖容器运行时）
kubectl（K8s 命令行工具）
Minikube（本地单节点 K8s，适合学习）

3. 前置配置

 1# 1.关闭 swap
 2sudo swapoff -a
 3sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab
 4
 5# 2.加载内核模块
 6sudo modprobe overlay
 7sudo modprobe br_netfilter
 8
 9# 3.设置内核参数
10cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
11net.bridge.bridge-nf-call-ip6tables = 1
12net.bridge.bridge-nf-call-iptables = 1
13net.ipv4.ip_forward = 1
14EOF
15
16sudo sysctl --system

4.安装container runtime（推荐使用 containerd）

Kubernetes v1.24 开始，完全移除了 dockershim

不再直接支持 Docker 作为容器运行时
推荐使用 containerd 或 CRI-O

 1# v1.6.x（兼容 Kubernetes v1.29）
 2sudo yum downgrade containerd.io-1.6.28* -y
 3
 4sudo systemctl restart containerd
 5sudo systemctl enable containerd
 6ls /var/run/containerd/containerd.sock  # 确认 socket 文件存在
 7
 8containerd --version  # 应显示 1.6.x
 9
10# 生成默认配置
11sudo mkdir -p /etc/containerd
12containerd config default | sudo tee /etc/containerd/config.toml
13
14# 修改配置（使用 systemd cgroup 驱动）
15sudo sed -i 's/SystemdCgroup = false/SystemdCgroup = true/g' /etc/containerd/config.toml
16# 可选修改 pause 镜像地址（国内可用阿里云镜像）
17sudo sed -i 's|registry.k8s.io/pause:3.9|registry.aliyuncs.com/google_containers/pause:3.9|g' /etc/containerd/config.toml
18
19sudo systemctl restart containerd

3. 安装 kubeadm, kubelet 和 kubectl

方式 1：Minikube（推荐新手）

1# 安装 Minikube（Linux/macOS）
2curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64  # Linux
3sudo install minikube-linux-amd64 /usr/local/bin/minikube
4
5# 启动 Minikube（默认使用 Docker 驱动）
6minikube start
7
8# 验证
9kubectl get nodes  # 应返回一个节点（STATUS=Ready）

方式 2：kubeadm（多节点集群）此处为单机演示

安装 kubeadm kubelet kubectl

 1# CentOS 添加 Kubernetes 的 yum 仓库,再
 2   cat <<EOF | sudo tee /etc/yum.repos.d/kubernetes.repo
 3[kubernetes]
 4name=Kubernetes
 5baseurl=https://pkgs.k8s.io/core:/stable:/v1.29/rpm/
 6enabled=1
 7gpgcheck=1
 8gpgkey=https://pkgs.k8s.io/core:/stable:/v1.29/rpm/repodata/repomd.xml.key
 9EOF
10
11# 安装 kubeadm kubelet kubectl
12yum install -y kubeadm kubelet kubectl --disableexcludes=kubernetes 
13
14# 启动并设置开机自启 kubelet
15sudo systemctl enable --now kubelet
16# 启动并设置开机自启 kubeletcontainerd
17systemctl enable --now containerd

准备镜像，镜像拉取问题见下文中的常见问题4和5

初始化主节点

非常关键的一步，失败会出现很多问题，可参考下文中的常见问题

 1# **初始化主节点 此步需要确保containerd，kubelet正常运行，以及镜像已经提前拉好**
 2# 参数--apiserver-advertise-address=0.0.0.0：允许本地访问 API Server
 3# 参数---pod-network-cidr=10.244.0.0/16 是用来配合 Flannel 网络插件的（或你改了 Calico 也行）。
 4# 参数--control-plane-endpoint=localhost：显式声明单节点控制平面
 5# 初始化成功会出现类似 Your Kubernetes control-plane has initialized successfully!
 6kubeadm init \
 7--apiserver-advertise-address=192.168.0.2 \
 8--pod-network-cidr=10.244.0.0/16 \
 9--control-plane-endpoint=192.168.0.2
10--ignore-preflight-errors=Swap  # 如果有 swap 警告

配置 kubectl

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

安装网络插件（如 Calico）

 1# 此处单机选择安装Flannel
 2kubectl apply -f https://github.com/flannel-io/flannel/releases/latest/download/kube-flannel.yml
 3
 4# 或者安装网络插件（如 Calico）
 5kubectl apply -f https://docs.projectcalico.org/manifests/calico.yaml
 6# 如果kubectl apply 无法应用 Calico 的 YAML 文件，可以下载文件再手动应用
 7   # 使用 curl
 8   curl -O https://mirror.aliyuncs.com/kubernetes/network-plugin/calico.yaml
 9   # 如果 Calico 的默认配置（如 CIDR）与你的集群不匹配，可以编辑 calico.yaml
10   # 检查 CALICO_IPV4POOL_CIDR 是否与 kubeadm init --pod-network-cidr 一致（默认 192.168.0.0/16 或 10.244.0.0/16）
11   kubectl apply -f calico.yaml

允许 Master 节点调度 Pod（单机必须）

1
2kubectl taint nodes --all node-role.kubernetes.io/control-plane-

验证安装

1# 查看集群状态
2kubectl cluster-info
3
4# 检查节点状态
5kubectl get nodes  # 应显示 Ready
6
7# 检查容器运行时
8kubectl get nodes -o wide | grep -i container  # 应显示 containerd://1.6.x

常用命令速查

操作	命令
查看 Pod	kubectl get pods
查看 Service	kubectl get svc
查看日志	kubectl logs
进入容器	kubectl exec -it – /bin/bash
删除 Pod	kubectl delete pod
扩缩容	kubectl scale –replicas=3 deployment/nginx

卸载

1# Minikube
2minikube stop
3minikube delete
4
5# kubeadm
6sudo kubeadm reset
7sudo apt-get purge kubeadm kubectl kubelet  # Ubuntu
8sudo yum remove kubeadm kubectl kubelet    # CentOS

常见问题

错误显示 container runtime is not running，说明 containerd（或 Docker）未正确配置或未运行。

解决方法：

如果使用 containerd：

1# 确保 containerd 已安装并运行
2sudo systemctl enable --now containerd
3sudo systemctl status containerd
4
5# 生成默认配置并启用 CRI 插件
6sudo containerd config default | sudo tee /etc/containerd/config.toml
7sudo sed -i 's/SystemdCgroup = false/SystemdCgroup = true/' /etc/containerd/config.toml
8sudo systemctl restart containerd

如果使用 Docker：

 1# 确保 Docker 已安装并运行
 2sudo systemctl enable --now docker
 3sudo systemctl status docker
 4
 5# 配置 Docker 使用 systemd cgroup
 6sudo mkdir -p /etc/docker
 7cat <<EOF | sudo tee /etc/docker/daemon.json
 8{
 9"exec-opts": ["native.cgroupdriver=systemd"]
10}
11EOF
12sudo systemctl restart docker

错误 /proc/sys/net/bridge/bridge-nf-call-iptables does not exist 表示系统未加载 br_netfilter 内核模块。

解决方法：

 1# 加载内核模块
 2sudo modprobe br_netfilter
 3
 4# 确保重启后依然生效
 5echo "br_netfilter" | sudo tee /etc/modules-load.d/k8s.conf
 6
 7# 启用桥接流量转发
 8cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
 9net.bridge.bridge-nf-call-ip6tables = 1
10net.bridge.bridge-nf-call-iptables = 1
11net.ipv4.ip_forward = 1
12EOF
13sudo sysctl --system

kubelet 服务未能正常启动或健康检查失败

解决方法

检查 kubelet 状态和日志

1# 查看 kubelet 运行状态
2sudo systemctl status kubelet
3
4# 查看详细日志（若无状态异常）
5sudo journalctl -xeu kubelet --no-pager | tail -n 50

容器运行时（CRI）未就绪

1# 检查 containerd 或 Docker 是否运行
2sudo systemctl status containerd  # 或 docker
3
4# 如果没有运行，启动并启用
5sudo systemctl enable --now containerd
6sudo systemctl restart kubelet

kubeadm config images pull 失败

配置 containerd 镜像加速器

 1# 修改 containerd 配置
 2sudo mkdir -p /etc/containerd
 3containerd config default | sudo tee /etc/containerd/config.toml
 4
 5# 添加国内镜像加速器（阿里云）
 6sudo sed -i 's|registry.k8s.io|registry.aliyuncs.com/google_containers|g' /etc/containerd/config.toml
 7sudo sed -i 's|docker.io|mirror.ccs.tencentyun.com|g' /etc/containerd/config.toml
 8
 9# 重启 containerd
10sudo systemctl restart containerd

更换 Docker 仓库为国内源

 1# 1. 备份原有 Docker 仓库配置
 2sudo mv /etc/yum.repos.d/docker-ce.repo /etc/yum.repos.d/docker-ce.repo.bak
 3
 4# 2. 使用阿里云 Docker 镜像源
 5sudo tee /etc/yum.repos.d/docker-ce.repo <<'EOF'
 6[docker-ce-stable]
 7name=Docker CE Stable - AliYun
 8baseurl=https://mirrors.aliyun.com/docker-ce/linux/centos/$releasever/$basearch/stable
 9enabled=1
10gpgcheck=1
11gpgkey=https://mirrors.aliyun.com/docker-ce/linux/centos/gpg
12EOF
13
14# 3. 清理缓存并重新安装
15sudo yum clean all
16sudo yum makecache
17sudo yum install -y containerd.io-1.6.28

当 kubeadm init 卡在 [preflight] Pulling images… 时，通常是由于 Docker/Containerd 镜像拉取失败或网络问题导致

查看需要的镜像列表

 1kubeadm config images list --kubernetes-version=v1.29.15
 2
 3# 输出示例
 4registry.k8s.io/kube-apiserver:v1.29.15
 5registry.k8s.io/kube-controller-manager:v1.29.15
 6registry.k8s.io/kube-scheduler:v1.29.15
 7registry.k8s.io/kube-proxy:v1.29.15
 8registry.k8s.io/coredns/coredns:v1.11.1
 9registry.k8s.io/pause:3.9
10registry.k8s.io/etcd:3.5.16-0

手动拉取镜像

1sudo kubeadm config images pull --kubernetes-version=v1.29.15

如果拉取失败（如网络问题），尝试：

使用国内镜像源（如阿里云）

1sudo kubeadm config images pull --image-repository=registry.aliyuncs.com/google_containers --kubernetes-version=v1.29.15

手动拉取并重命名：

1docker pull registry.aliyuncs.com/google_containers/kube-apiserver:v1.29.15
2docker tag registry.aliyuncs.com/google_containers/kube-apiserver:v1.29.15 registry.k8s.io/kube-apiserver:v1.29.15

确认容器运行时

 1# 确认 kubelet 使用的容器运行时类型。 --container-runtime-endpoint=unix:///run/containerd/containerd.sock → 用的是 containerd
 2ps -ef | grep kubelet | grep container-runtime
 3
 4# 如果是 containerd
 5# 导出docker镜像
 6docker save registry.k8s.io/kube-apiserver:v1.29.15 -o kube-apiserver.tar
 7
 8# 导入到 containerd：
 9ctr -n k8s.io images import kube-apiserver.tar
10
11# 验证 containerd 中镜像是否存在：
12ctr -n k8s.io images ls | grep kube-apiserver
13
14# 重启 kubele
15systemctl restart kubelet

如果想要清理 aliyun 那些 sha256 镜像

ctr -n k8s.io images ls

ctr -n k8s.io images ls | grep aliyuncs

ctr -n k8s.io images rm <完整REF>

API Server 还没起来或者挂了，错误信息如： error: error validating “calico.yaml”: error validating data: failed to download openapi: Get “https://192.168.0.2:6443/openapi/v2?timeout=32s”: dial tcp 192.168.0.2:6443: connect: connection refused
- 检查 kubelet 状态
```
1systemctl status kubelet
2# 有没有绿色的 active (running)？如果不是，重启：
3systemctl restart kubelet
```
- kube-apiserver 是否正常运行, 能不能看到 kube-apiserver 正在运行？如果没有，可能初始化没完成，或者配置挂了。
```
1docker ps | grep kube-apiserver
2# 或 containerd 用户：
3crictl ps | grep kube-apiserver
```
- 检查 kubectl 的配置是否 OK ~/.kube/config 如果没配置好,去设置
```
1mkdir -p $HOME/.kube
2cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
3chown $(id -u):$(id -g) $HOME/.kube/config
```
crictl 输出报错如：ERRO[0000] validate service connection: validate CRI v1 runtime API for endpoint “unix:///var/run/dockershim.sock”: rpc error: code = Unavailable desc = connection error: desc = “transport: Error while dialing: dial unix /var/run/dockershim.sock: connect: no such file or directory”
- 说明当前没有配置容器运行时的 socket 路径，也就是说：crictl 没法找到 containerd 或 docker 的接口来查看容器运行情况。
- 显式配置 crictl 使用 containerd，创建/编辑配置文件
```
1cat <<EOF | sudo tee /etc/crictl.yaml
2runtime-endpoint: unix:///run/containerd/containerd.sock
3image-endpoint: unix:///run/containerd/containerd.sock
4timeout: 10
5debug: false
6EOF
```
```
1# 测试是否成功识别 containerd, 如果一切正常，会输出 containerd 的详细信息（运行中的容器、版本等）。
2crictl info
```
- 检查 kubelet 是否和 containerd 联通: 编辑 /var/lib/kubelet/kubeadm-flags.env 看看是否有设置
```
1KUBELET_KUBEADM_ARGS="--container-runtime=remote --container-runtime-endpoint=unix:///run/containerd/containerd.sock ..."
```
- 然后重启 kubelet：
```
1systemctl daemon-reexec
2systemctl restart kubelet
```
- 验证测试
```
1crictl ps | grep apiserver
2
3kubectl get nodes
```

Calico Pod 状态问题，如果 Pod 处于Pending、Error或者CrashLoopBackOff状态，就需要进一步排查。要保证 Calico 相关的 Pod 都处于Running状态

 1#查看 Calico Pod 状态
 2kubectl get pods -n kube-system | grep calico
 3
 4#输出示例
 5calico-kube-controllers-565f855c6c-6v9z7   1/1     Running   0          3d
 6calico-node-8h5g7                          1/1     Running   0          3d
 7calico-node-lt7f4                          1/1     Running   0          3d
 8
 9#  查看特定 Pod 的详细信息
10kubectl describe pod <pod-name> -n kube-system

* 镜像拉取失败无法拉取 Calico 镜像，可以尝试手动拉取
``` bash
# 可以手动代理下载，然后传输到目标主机导入镜像
docker pull docker.io/calico/cni:v3.25.0
docker save -o /path/to/calico-cni-v3.25.0.tar docker.io/calico/cni:v3.25.0
docker load -i /path/to/calico-cni-v3.25.0.tar

# 导入到 containerd：
ctr -n docker.io images import calico-cni-v3.25.0.tar
ctr -n docker.io images ls | grep cni
# 重启kubelet
sudo systemctl restart kubelet

其他必要步骤

注意版本兼容问题

彻底重置并重建集群：

 1# 删除文件
 2sudo kubeadm reset -f
 3sudo rm -rf /etc/kubernetes/ /var/lib/etcd/ ~/.kube/
 4sudo systemctl restart kubelet
 5
 6# 重置
 7sudo kubeadm init \
 8--apiserver-advertise-address=192.168.0.2 \
 9--pod-network-cidr=10.244.0.0/16 \
10--kubernetes-version=v1.29.15 \
11--image-repository=registry.aliyuncs.com/google_containers \  # 使用阿里云镜像
12--ignore-preflight-errors=Swap

重置后再进行上面的如果成功初始化，记得保存 kubeadm join 命令并安装 CNI 插件
重启 kubelet sudo netstat -tulnp | grep 6443

确认 API Server 是否运行

1# 检查 API Server 容器/Pod（根据容器运行时选择）
2sudo docker ps | grep kube-apiserver    # Docker
3sudo crictl ps | grep kube-apiserver   # Containerd

检查 API Server 端口监听

1sudo netstat -tulnp | grep 6443
2# 正常输出示例
3tcp  0  0  192.168.0.2:6443  0.0.0.0:*  LISTEN  <pid>/kube-apiserver

验证修复

检查 kubelet 状态和日志
检查容器运行时状态：

1sudo crictl ps  # 或 sudo docker ps

检查内核模块：

1lsmod | grep br_netfilter
2cat /proc/sys/net/bridge/bridge-nf-call-iptables

完全卸载

以下命令适用于 kubeadm 方式部署的单节点（单机）集群：

 1# 1. 关闭所有 kubelet 服务（如果有 systemd 服务）
 2sudo systemctl stop kubelet
 3sudo systemctl disable kubelet
 4
 5# 2. 重置 kubeadm 配置（会清理 etcd 数据、k8s 配置等）
 6sudo kubeadm reset -f
 7
 8# 3. 删除网络相关配置（flannel/cni）
 9sudo rm -rf /etc/cni /opt/cni /var/lib/cni /var/lib/kubelet /etc/kubernetes
10
11# 4. 清理 Docker/containerd 容器网络遗留
12sudo ip link delete cni0 || true
13sudo ip link delete flannel.1 || true
14sudo ip link delete docker0 || true
15
16# 5. 删除 Kubernetes 二进制文件（如果是手动解压安装的）
17sudo rm -f /usr/local/bin/kubectl /usr/local/bin/kubeadm /usr/local/bin/kubelet
18# yum安装方式
19sudo yum remove -y kubeadm kubelet kubectl kubernetes-cni
20sudo rm -rf /etc/kubernetes /var/lib/kubelet /etc/cni /opt/cni 
21rm -rf /etc/cni/net.d /var/lib/cni/
22
23# 6. 删除日志和残留目录
24sudo rm -rf ~/.kube
25sudo rm -rf /var/log/pods
26
27# 7. containerd和docker镜像清理
28sudo crictl images
29crictl images | grep -E 'k8s|flannel|dashboard|etcd' | awk '{print $1":"$2}' | xargs -r sudo crictl rmi
30sudo crictl rmi IMAGE_ID
31
32docker images 
33#删除所有未被使用的镜像 建议rmi 单个删除
34docker images | grep -E 'k8s|flannel|dashboard|etcd' | awk '{print $3}' | xargs -r docker rmi -f
35docker image prune -a -f

文档资源

官方文档：kubernetes.io
中文教程：Kubernetes 中文社区

清理并重新初始化脚本

 1#!/bin/bash
 2
 3set -e
 4
 5echo "🧼 [1/6] 停止 kubelet 服务..."
 6sudo systemctl stop kubelet || true
 7
 8echo "🧹 [2/6] 重置 kubeadm 和清理网络配置..."
 9sudo kubeadm reset -f
10sudo rm -rf /etc/cni/net.d
11sudo rm -rf $HOME/.kube
12sudo ip link delete cni0 || true
13sudo ip link delete flannel.1 || true
14
15echo "🔧 [3/6] 初始化 Kubernetes 控制平面..."
16sudo kubeadm init \
17  --apiserver-advertise-address=192.168.0.2 \
18  --pod-network-cidr=10.244.0.0/16 \
19  --control-plane-endpoint=192.168.0.2
20
21echo "👤 [4/6] 配置 kubectl 使用权限..."
22mkdir -p $HOME/.kube
23sudo cp /etc/kubernetes/admin.conf $HOME/.kube/config
24sudo chown $(id -u):$(id -g) $HOME/.kube/config
25
26echo "🌐 [5/6] 安装 Flannel 网络插件..."
27kubectl apply -f https://raw.githubusercontent.com/flannel-io/flannel/master/Documentation/kube-flannel.yml
28
29echo "🛑 [6/6] 移除控制节点的调度限制（适用于单机）..."
30kubectl taint nodes --all node-role.kubernetes.io/control-plane- || true
31
32sudo systemctl restart containerd
33sudo systemctl restart kubelet
34
35echo -e "\n✅ 集群初始化完成！执行以下命令查看状态："
36echo "kubectl get nodes"
37echo "kubectl get pods -A"

Kubernetes（k8s）单机环境部署

Kubernetes（k8s）单机环境部署

1. Kubernetes (K8s) 简介

2. 环境

3. 前置配置

4.安装container runtime（推荐使用 containerd）

3. 安装 kubeadm, kubelet 和 kubectl

方式 1：Minikube（推荐新手）

方式 2：kubeadm（多节点集群） 此处为单机演示

验证安装

常用命令速查

卸载

常见问题

验证修复

完全卸载

文档资源

清理并重新初始化脚本

发表评论

方式 2：kubeadm（多节点集群）此处为单机演示