跳到主要内容

K3s 笔记

来自 I_Kubernetes基础笔记 的延伸:「小企业选哪个 K8s 发行版」的答案。


1. K3s 是什么​

K3s 是 Rancher Labs(已被 SUSE 收购)出品的轻量级 Kubernetes 发行版,把上游 K8s 打包成单个 < 100MB 的二进制,移除 alpha feature 和传统 in-tree cloud provider。

1.1 核心特点​

  • 单二进制:一个文件包含 kubelet、kube-proxy、scheduler、controller-manager 等所有组件
  • 低资源:server 节点最低 512MB RAM 即可运行
  • SQLite 默认存储:单节点用嵌入式 SQLite,HA 用嵌入式 etcd
  • 内置组件:默认装好 Traefik(Ingress)、servicelb(LB)、local-path(存储)、metrics-server
  • 易部署:一行命令启动
  • CNCF 一致性认证:与上游 K8s API 完全兼容

1.2 与上游 K8s 的差异​

项目K3s
安装单 curl + sh
默认存储SQLite(HA 时 etcd)
默认容器运行时containerd
默认 IngressTraefik v2
默认 LoadBalancerservicelb(轻量)
默认存储类local-path
默认 metricsmetrics-server
二进制大小~70MB
兼容上游 YAML100% 兼容(大部分 manifest 可直接 apply)
API 差异几乎无(少数 alpha 特性未实现)

1.3 适用场景​

✅ 适合

  • 边缘计算(IoT、零售店)
  • 小/中型企业内部 K8s
  • CI/CD runner 集群(Jenkins on K3s)
  • 资源受限环境
  • 不想维护 kubeadm 复杂度

❌ 不适合

  • 数百+ 节点的大规模集群(仍然用 EKS/RKE2/自建 kubeadm 更合适)
  • 需要原生 cloud provider 集成(GCE/AWS/GCP K8s 原生功能)

2. K3s vs RKE2 vs k8s(kubeadm)​

K3sRKE2kubeadm
二进制大小~70MB~100MB多组件
资源需求低中高
安全加固基础高级(CIS 合规默认开)需手动
数据库SQLite / 内置 etcd / 外部 SQL内置 etcd外部 etcd
部署复杂度最低低高
上游兼容性100% API 兼容100%100%
推荐场景边缘、中小规模金融、政企合规场景K8s 工程师学习底层

小企业:K3s 起步,规模起来或要安全合规再迁 RKE2。同一 Rancher 可纳管两者。


3. 安装​

3.1 单节点(学习 / 测试)​

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

# 自动 systemctl 启用 k3s 服务
# kubeconfig 位置:/etc/rancher/k3s/k3s.yaml

# 配置 kubectl
mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $(id -u):$(id -g) ~/.kube/config

# 验证
kubectl get nodes

3.2 单节点(生产)​

curl -sfL https://get.k3s.io | sh -s - \
--write-kubeconfig-mode 644 \
--disable=traefik \
--default-local-storage-path /var/lib/rancher/k3s/storage \
--node-name server-01 \
--node-external-ip 192.168.1.10

3.3 HA 集群(生产推荐)​

至少 3 个 server 节点用嵌入式 etcd:

# 第 1 台 server
curl -sfL https://get.k3s.io | sh -s - \
--cluster-init \
--write-kubeconfig-mode 644 \
--tls-san 192.168.1.10 \
--tls-san k3s.example.com

# 拿到 token
cat /var/lib/rancher/k3s/server/node-token

# 第 2、3 台 server(用 K3S_URL + K3S_TOKEN 环境变量)
curl -sfL https://get.k3s.io | sh -s - \
--server https://192.168.1.10:6443 \
--token <node-token> \
--tls-san k3s.example.com

# 添加 worker(agent 节点)
curl -sfL https://get.k3s.io | sh -s - \
--server https://192.168.1.10:6443 \
--token <node-token> \
--node-name worker-01
  • server 节点:跑 etcd + 控制平面,奇数台(1/3/5/7)
  • agent 节点:跑工作负载

3.4 离线安装(无外网环境)​

# 在有外网的机器上
mkdir -p /tmp/k3s-offline && cd /tmp/k3s-offline
wget https://github.com/k3s-io/k3s/releases/download/v1.30.4%2Bk3s1/k3s
wget https://github.com/k3s-io/k3s/releases/download/v1.30.4%2Bk3s1/k3s-airgap-images-amd64.tar
wget https://get.k3s.io/install.sh

# 复制到内网机器,scp 一个文件就够
# 在内网机器上
sudo mkdir -p /var/lib/rancher/k3s/agent/images/
sudo cp k3s-airgap-images-amd64.tar /var/lib/rancher/k3s/agent/images/
sudo cp k3s /usr/local/bin/
sudo chmod +x /usr/local/bin/k3s
sudo INSTALL_K3S_SKIP_ENABLE=true sh install.sh
sudo systemctl enable --now k3s

3.5 高可用外部数据库方案(SQL / MySQL / Postgres)​

# 启动时启用外部数据库
curl -sfL https://get.k3s.io | sh -s - \
--datastore-endpoint="mysql://root:pwd@tcp(mysql.example.com:3306)/k3s" \
--datastore-cafile=/etc/ssl/ca.pem \
--datastore-certfile=/etc/ssl/client-cert.pem \
--datastore-keyfile=/etc/ssl/client-key.pem

外部 DB 适合:1)大集群;2)想保留运维团队熟悉的 DBA 工具。


4. K3s 内置组件​

K3s 默认启用以下内置组件,生产环境建议评估是否替换:

组件默认替代方案
Container Runtimecontainerd-
DNSCoreDNS-
IngressTraefik v2(--disable=traefik 可关)Nginx Ingress Controller
LoadBalancerservicelb(--disable=servicelb 可关)MetalLB
Storagelocal-path(--disable=local-storage 可关)Longhorn / NFS
Metricsmetrics-server-
NetworkFlannel(默认 VXLAN)Calico / Cilium(要 NetworkPolicy)

⚠️ Flannel 默认不支持 NetworkPolicy。要做命名空间隔离必须换 Calico 或 Cilium:

curl -sfL https://get.k3s.io | sh -s - \
--flannel-backend=none \
--disable-network-policy

# 然后装 Calico
kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.27/manifests/calico.yaml

5. K3s 常用操作​

5.1 服务管理​

# 服务控制
sudo systemctl status k3s
sudo systemctl restart k3s
sudo journalctl -u k3s -f # 日志

# 配置文件
sudo vim /etc/rancher/k3s/config.yaml

# 重启生效
sudo systemctl restart k3s

5.2 etcd snapshot(HA 必备)​

# 手动
sudo k3s etcd-snapshot save

# 定时任务(默认 cron:每天 0:00, 8:00, 16:00)
# /etc/rancher/k3s/config.yaml
etcd-snapshot-schedule-cron: "0 */6 * * *" # 每 6 小时
etcd-snapshot-retention: 10 # 保留 10 个
etcd-snapshot-s3: true # 上传到 S3(需额外配置)
etcd-snapshot-s3-bucket: my-k3s-snapshots
etcd-snapshot-s3-folder: prod

恢复:

sudo systemctl stop k3s
sudo rm -rf /var/lib/rancher/k3s/server/db
sudo k3s server \
--cluster-reset \
--cluster-reset-restore-path=/var/lib/rancher/k3s/server/db/snapshots/<snapshot-name>

5.3 升级 K3s​

# 服务端 + 节点一起升
curl -sfL https://get.k3s.io | sh -

# server 之间会自动升级,agent 由 server 推送

升级顺序:先 server,再 agent。

5.4 K3s 二进制直接调用​

k3s server # 在前台启动 server
k3s agent # 在前台启动 agent
k3s kubectl get nodes # 集群内置 kubectl

# 一些常用子命令
k3s crictl ps # 容器运行时查看
k3s ctr -n k8s.io images ls # 镜像列表

6. K3s 上装 Helm​

# 安装 Helm
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

# 加 Rancher 仓库
helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
helm repo add jetstack https://charts.jetstack.io
helm repo add longhorn https://charts.longhorn.io
helm repo update

7. 备份恢复方案​

数据备份方式
集群状态(etcd)k3s etcd-snapshot → 本地 / S3
应用数据(DB 卷等)Longhorn Backup / Restic → NFS / S3
Helm / manifests 配置Git 仓库(GitOps 推荐)
镜像Harbor 内置 replication 到备份仓库

8. 常见坑点​

现象原因解决
kubectl 报 connection refusedK3s 没起来systemctl status k3s
traefik 默认占 80/443K3s 内置--disable=traefik 自己装 Nginx Ingress
LoadBalancer Service 一直 pendingservicelb 没启用--disable=servicelb 后需装 MetalLB
NetworkPolicy 不生效Flannel 不支持换 Calico / Cilium
高可用集群脑裂server 数 < 3加 server 节点,奇数台
离线装失败镜像包没放对路径确认为 /var/lib/rancher/k3s/agent/images/
升级后 API 不兼容上游 K8s 删除 alpha看 K3s release notes

9. 一句话总结​

  • K3s = 上游 K8s 的精简版,单二进制、低资源、易上手,对小企业最实用
  • 默认 traefik + servicelb + local-path + metrics-server,生产按需替换
  • HA 用 3/5 台 server + 嵌入式 etcd,配置 --cluster-init
  • 备份用 k3s etcd-snapshot,配置好 cron + S3 即可