Kubernetes 安装与配置

DevOps

Kubernetes

Kubernetes 安装与配置

以 WSL 2 + K3s 搭建本地 Kubernetes 开发环境，含国内网络加速方案。

1. 为什么选 K3s

方案	定位	适用场景
K3s	轻量级 Kubernetes，打包为单个 < 100MB 二进制	边缘计算、IoT、本地开发
Minikube	本地单节点 K8s 集群	学习与测试
Kind	在 Docker 容器中运行 K8s	CI/CD、本地测试
kubeadm	官方集群部署工具	生产环境标准部署

K3s 由 Rancher 维护，裁剪了 K8s 中不常用的功能（如 in-tree 云提供商），用轻量组件替代（SQLite 替代 etcd 作为默认存储），非常适合本地学习和开发。

2. 准备工作：配置 WSL 环境

在安装 K3s 之前，需要确保 WSL 2 环境满足要求。

前置条件：已安装 WSL 2 和 Ubuntu 发行版。

2.1 关闭交换分区

K3s 要求关闭交换空间：

sudo swapoff -a

2.2 加载必要内核模块

这些模块是容器网络所必需的：

sudo modprobe overlay
sudo modprobe br_netfilter

2.3 配置网络参数

创建内核配置，确保网络转发功能开启：

cat <<EOF | sudo tee /etc/sysctl.d/k3s.conf
net.bridge.bridge-nf-call-iptables = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward = 1
EOF

让配置立即生效：

sudo sysctl --system

3. 安装 K3s（国内加速版）

推荐使用 Rancher 提供的国内镜像加速脚本，解决下载慢的问题：

curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn K3S_KUBECONFIG_MODE="644" sh -

参数说明：

参数	作用
`INSTALL_K3S_MIRROR=cn`	🚨 关键参数：从国内镜像源下载 K3s 二进制文件
`K3S_KUBECONFIG_MODE="644"`	让配置文件对当前用户可读，省去每次 `sudo kubectl`

补充：如果希望将 K3s 数据存储到其他位置（如挂载的大容量磁盘），可追加 INSTALL_K3S_EXEC="--data-dir=/your/path"。

4. 后续配置：让 kubectl 更好用

安装完成后，K3s 会自动安装 kubectl，但还需做以下配置。

4.1 配置 kubeconfig 文件

mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $USER:$USER ~/.kube/config

4.2 创建 kubectl 软链接

WSL 环境下 kubectl 可能不在 PATH 中：

sudo ln -s /usr/local/bin/kubectl /usr/bin/kubectl

4.3 配置 kubectl 自动补全（💡 最佳实践）

# bash
echo 'source <(kubectl completion bash)' >> ~/.bashrc
source ~/.bashrc

# 常用缩写别名
echo 'alias k="kubectl"' >> ~/.bashrc
echo 'alias kg="kubectl get"' >> ~/.bashrc
echo 'alias kd="kubectl describe"' >> ~/.bashrc

5. 验证安装

kubectl get nodes

看到节点状态为 Ready，说明 K3s 集群已成功运行。

# 查看所有系统 Pod
kubectl get pods -A

期望输出类似：

NAMESPACE     NAME                                      READY   STATUS    RESTARTS   AGE
kube-system   coredns-xxx                               1/1     Running   0          1m
kube-system   local-path-provisioner-xxx                1/1     Running   0          1m
kube-system   metrics-server-xxx                        1/1     Running   0          1m
kube-system   traefik-xxx                               1/1     Running   0          1m

6. 多节点集群（可选）

如需添加 Worker 节点：

在 Master 节点获取 token：

sudo cat /var/lib/rancher/k3s/server/node-token

在 Worker 节点执行：

curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \
  K3S_URL=https://<MASTER_IP>:6443 \
  K3S_TOKEN=<NODE_TOKEN> \
  INSTALL_K3S_MIRROR=cn sh -

7. 卸载 K3s

# 卸载 Server/Master 节点
sudo /usr/local/bin/k3s-uninstall.sh

# 卸载 Agent/Worker 节点
sudo /usr/local/bin/k3s-agent-uninstall.sh

8. 私有镜像仓库配置

如果使用自建私有仓库（如 Docker Registry 或 Harbor），需配置 K3s 的镜像拉取。

8.1 配置 insecure registry

编辑 /etc/rancher/k3s/registries.yaml：

mirrors:
  <私有仓库IP:端口>:
    endpoint:
      - "http://<私有仓库IP:端口>"

然后重启 K3s：

sudo systemctl restart k3s

🚨 注意：如果是多节点集群，必须在每台机器上都做此配置。

8.2 Docker 侧的配置

在 /etc/docker/daemon.json 中加入：

{
  "insecure-registries": ["<私有仓库IP:端口>"]
}

9. 常见问题

问题	原因	解决
`kubectl` 命令找不到	未创建软链接	`sudo ln -s /usr/local/bin/kubectl /usr/bin/kubectl`
拉取镜像超时	境内网络访问 gcr.io 受限	使用 `INSTALL_K3S_MIRROR=cn`，或配置国内镜像代理
`crictl` 权限不足	需要 `sudo`	使用 `sudo crictl` 或 `sudo k3s crictl`
Pod 一直 Pending	资源不足或调度失败	`kubectl describe pod <name>` 查看 Events

Kubernetes 核心概念