使用 K3s 快速搭建集群

K3s 是轻量化 Kubernetes 发行版，裁剪了体积和依赖，但保留了核心 API 体验。它默认集成 containerd、flannel 以及简化的存储插件，适合实验、边缘、演示与小型测试环境。

这篇快速上手覆盖你真正需要的步骤：安装、节点加入、验证集群、部署一个示例工作负载，同时补上常见的网络与排错注意事项。

为什么选择 K3s

• 体积小、启动快，适合资源受限或临时环境。
• 默认组件齐全，几分钟内即可形成可用集群。
• YAML 与 kubectl 使用方式与标准 Kubernetes 一致。

预备条件

• 64 位 Linux 主机，建议 2 核 CPU 与 2-4GB 内存作为单节点控制平面起步。
• 需要开放端口：6443(API Server)、8472/udp(flannel VXLAN)。
• 如果防火墙较严格，建议额外放行 10250(kubelet) 与 2379-2380(启用内置 etcd 时)。
• 主机具备 curl 与 systemd。

规模与预期

K3s 虽然轻量，但本质仍是 Kubernetes。单机演示场景可以勉强在 2 核 2GB 上运行，但只要 Pod 数量上升，控制平面就会明显受压。更稳妥的起步是 4 核 8GB，特别是你计划同时跑监控、日志或 CI 任务时。

如果你使用默认的 SQLite 数据库，请把集群当作“快速实验环境”。当你需要高可用或更高可靠性时，再考虑内置 etcd 或外部数据存储。

如果计划跑构建或测试任务，建议把控制平面与负载节点分开。构建容器通常更吃 CPU 与磁盘 IO，独立工作节点能明显降低控制平面的抖动。

安装控制平面

默认安装会启动单节点控制平面，并启用 containerd 与 flannel：

curl -sfL https://get.k3s.io | sh -

查看服务状态与日志：

sudo systemctl status k3s
sudo journalctl -u k3s -n 200 --no-pager

查看 kubeconfig 并设置环境变量：

sudo cat /etc/rancher/k3s/k3s.yaml
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml

如果你在远程管理机上访问，请复制配置并替换服务器地址：

scp user@<server-ip>:/etc/rancher/k3s/k3s.yaml ~/.kube/k3s.yaml
sed -i 's/127.0.0.1/<server-ip>/g' ~/.kube/k3s.yaml
export KUBECONFIG=~/.kube/k3s.yaml

常用配置文件

K3s 会读取 /etc/rancher/k3s/config.yaml，你可以在这里调整集群网段或关闭内置组件：

# /etc/rancher/k3s/config.yaml
write-kubeconfig-mode: "0644"
cluster-cidr: "10.42.0.0/16"
service-cidr: "10.43.0.0/16"
disable:
  - traefik
  - metrics-server

修改配置后重启服务：

sudo systemctl restart k3s

控制平面数据存储与高可用

K3s 默认使用内置 SQLite，配置简单但不适合高可用。需要多控制平面时，应参考官方 HA 方案启用内置 etcd，并明确备份与恢复策略。建议先在单机上把流程跑通，再逐步升级架构。

加入工作节点

先获取 server token：

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

在工作节点执行安装命令：

curl -sfL https://get.k3s.io | K3S_URL=https://<server-ip>:6443 K3S_TOKEN=<token> sh -

确认节点加入成功：

kubectl get nodes -o wide

网络与端口提示

• flannel 默认使用 VXLAN，需要 8472/udp 能互通。
• API Server 端口为 6443，所有节点需要访问到它。
• CoreDNS 未就绪时，集群内域名解析会失败，先查看 kube-system 命名空间的 Pod 状态。

存储：local-path-provisioner

K3s 默认启用 local-path-provisioner，适合快速验证持久化流程：

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: demo-pvc
spec:
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi

kubectl apply -f pvc.yaml
kubectl get pvc

部署一个示例工作负载

创建一个 Nginx Deployment 与 Service，并使用端口转发验证：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: hello
spec:
  replicas: 2
  selector:
    matchLabels:
      app: hello
  template:
    metadata:
      labels:
        app: hello
    spec:
      containers:
      - name: web
        image: nginx:1.27
        ports:
        - containerPort: 80

apiVersion: v1
kind: Service
metadata:
  name: hello
spec:
  selector:
    app: hello
  ports:
  - port: 80
    targetPort: 80

kubectl apply -f deploy.yaml
kubectl apply -f svc.yaml
kubectl get pods -o wide
kubectl port-forward svc/hello 8080:80

在浏览器打开 http://localhost:8080 验证服务。

Ingress 与组件选择

K3s 默认启用 Traefik，如果你有统一的 Ingress 方案，可以在配置里禁用并改用 NGINX Ingress 或其他控制器。务必保证 Service 类型、域名解析与证书策略匹配你的部署环境。

metrics-server 在小集群里很有用，能支持 kubectl top 和 HPA 实验，但会额外占用资源。如果禁用它，HPA 将无法获取指标。

服务暴露方式

快速验证推荐使用 kubectl port-forward，不需要额外改动网络。要让其他机器访问，可以使用 NodePort 并放行节点防火墙端口。更接近真实场景的做法是配合 Ingress 和 DNS/TLS，实现基于域名的访问。

验证与排错

常用排查流程：

kubectl get nodes
kubectl get pods -A
kubectl get events -A

节点 NotReady 时重点检查：

• journalctl -u k3s 与 journalctl -u k3s-agent。
• 防火墙或安全组是否放行 6443 和 8472/udp。
• kube-system 中 CoreDNS 是否 Running。

Pod 一直 Pending 时检查：

kubectl describe pod <pod-name>
kubectl get pvc,pv

访问控制与运维建议

k3s.yaml 拥有集群全权限，务必限制文件权限，避免共享到不可信环境。多人协作时，建议创建独立的 ServiceAccount 并分配最小权限。

日常运维建议：

• 给节点打 Label，方便用 nodeSelector 或亲和性调度。
• 用 Namespace 区分实验与业务环境。
• 关注版本更新，升级前阅读 K3s 发行说明。
• 发现 token 或 kubeconfig 泄漏时，及时轮换并重新加入节点。

卸载清理

控制平面：

sudo /usr/local/bin/k3s-uninstall.sh

工作节点：

sudo /usr/local/bin/k3s-agent-uninstall.sh

快速检查清单

• 资源定义与业务意图一致。
• Namespace、权限、镜像与环境匹配。
• 上线前具备健康探针与可观测日志。
• 节点间端口互通，网络插件正常工作。

参考链接

• K3s 文档
• K3s 官网