当前位置：首页 > news >正文

K3s简介、实战、问题记录

news 来源：原创 2025/6/3 20:18:49

概述

K3s由Rancher Labs开发，是一个开源的，轻量级的Kubernetes（下文简称k8s）发行版，专为边缘计算、IoT和资源受限环境设计；保留k8s核心功能，并去掉部分非必要组件。

官网，中文文档1，中文文档2。

选择K3s的三大理由：

完美适配边缘环境：K3s是一个高可用的、经过CNCF认证的Kubernetes发行版，专为无人值守、资源受限、偏远地区或物联网设备内部的生产工作负载而设计；
简单且安全：K3s被打包成单个小于60MB的二进制文件，从而减少运行安装、运行和自动更新生产Kubernetes集群所需的依赖性和步骤；
针对ARM进行优化：ARM64和ARMv7都支持二进制文件和多源镜像。K3s在小到树莓派或大到AWS a1.4xlarge 32GiB服务器的环境中均能出色工作。

适用场景

资源受限：如边缘计算、IoT设备，资源有限；
开发和测试：需要快速搭建一个轻量级的k8s环境；
小型集群：节点数量较少，不需要复杂的配置；
快速部署：需要一键安装和极简配置；
低成本运维：减少硬件和维护成本。

架构

架构简图
在这里插入图片描述
采用典型的服务器-代理架构，即Server-Agent架构。在K3s集群中，节点角色有两种：

Control Plane Nodes：控制平面节点，处理集群的管理任务，包括调度、控制循环和集群状态管理；一般会运行以下组件：kube-apiserver、kube-controller-manager、kube-scheduler和etcd；
Worker Nodes：工作节点，运行应用程序的工作负载（Pods）；一般会运行以下组件：kubelet、kube-proxy和container runtime。

k3s使用Containerd作为其底层容器运行时。
在这里插入图片描述
Agent与Server之间的交互

K3s内嵌组件

网络

在这里插入图片描述

负载均衡

在K3s中配置负载均衡策略通常涉及k8s Service和Ingress资源：

k8s Service
k8s Service提供基本的负载均衡能力，可通过创建不同类型的Service来实现不同的负载均衡策略：
- ClusterIP：仅集群内部可以访问；
- NodePort：每个选定的Node上开放一个静态端口，从集群外部也可以访问；
- LoadBalancer：在支持 LoadBalancer 的云平台（如 AWS，GCP，Azure）上创建外部负载均衡器；
- ExternalName：通过 DNS 将服务映射到外部服务。
Ingress控制器
对于更复杂的路由和负载均衡需求，可使用Ingress资源。Ingress控制器（如Nginx，Traefik）可提供HTTP/HTTPS路由、SSL终止等功能。
LoadBalancer服务类型
在支持LoadBalancer的云环境中，可直接使用LoadBalancer服务类型。如在AWS或GCP上，Kubernetes会自动为你创建一个外部负载均衡器。

apiVersion: v1
kind: Service
metadata:name: my-service-lb
spec:type: LoadBalancerselector:app: MyAppports:- protocol: TCPport: 80targetPort: 9376

MetalLB
如果在裸金属服务器上运行K3s，可使用MetalLB来提供裸金属集群的负载均衡能力。

安装MetalLB：bash kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.10.2/manifests/metallb.yaml

实战

集群部署

install.sh脚本负责下载二进制文件、设置适当的系统服务和配置初始集群。
在这里插入图片描述
安装主节点：
curl -sfL https://get.k3s.io | sh -

速度非常慢，那就对了。

使用国内镜像安装：curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh

安装从节点是可选地。验证k3s是否安装成功，执行命令：
k3s或k3s -v

安装从节点前需要知道主节点的IP地址和Token，在主节点执行命令查看Token：
cat /var/lib/rancher/k3s/server/node-token

使用国内镜像，安装从节点：
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | K3S_URL=https://192.168.0.108:6443 K3S_TOKEN=<>::server:<> INSTALL_K3S_MIRROR=cn sh -

有点不理解k3s的逻辑，使用上述命令安装从节点时，下载安装最新版本，而没有和主节点版本保持一致。

忘记截图。。

指定版本安装从节点（保持与主节点版本一致）：
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | INSTALL_K3S_VERSION=v1.32.3+k3s1 K3S_URL=https://192.168.105.52:6443 K3S_TOKEN=<>::server:<> INSTALL_K3S_MIRROR=cn sh -

验证集群安装效果，在主（或从）节点执行：
k3s kubectl get node
输出类似于如下截图，则表明集群安装成功：
在这里插入图片描述

卸载

如果想升级k3s，或修改某些配置后，部分命令执行结果不对，或错误地修改配置，需要卸载k3s集群，然后重新安装新版本。

先卸载从节点：

systemctl stop k3s-agent
/usr/local/bin/k3s-agent-uninstall.sh
# optional
sudo rm -rf /etc/rancher/k3s
sudo rm -rf /var/lib/rancher/k3s
sudo rm -rf /var/lib/kubelet
sudo rm -rf /var/lib/cni
sudo rm -rf /opt/cni
# 在主节点执行
k delete node k3s-worker-2

卸载主节点：

systemctl stop k3s
/usr/local/bin/k3s-uninstall.sh
# optional
sudo rm -rf /etc/rancher/k3s
sudo rm -rf /var/lib/rancher/k3s
sudo rm -rf /var/lib/kubelet
sudo rm -rf /var/lib/cni
sudo rm -rf /opt/cni

设置代理

因为某些众所周知的原因，速度慢，要设置代理。

主节点执行vim /etc/systemd/system/k3s.service.env，一般情况下该文件是空的，加入下述内容报错退出：

http_proxy='http://192.168.4.128:7890'
https_proxy='http://192.168.4.128:7890'

重启k3s：systemctl restart k3s

对于从节点，由于安装时会指定主节点IP，/etc/systemd/system/k3s-agent.service.env文件会存在类似如下内容：

K3S_TOKEN='<>::server:<>'
K3S_URL='https://192.168.4.134:6443'

追加如下内容，报错退出：

http_proxy='http://192.168.4.128:7890'
https_proxy='http://192.168.4.128:7890'

最后重启k3s-agent：systemctl restart k3s-agent

命令行

输入k3s，输出：

NAME:k3s - Kubernetes, but small and simpleUSAGE:k3s [global options] command [command options] [arguments...]VERSION:v1.32.3+k3s1 (079ffa8d)COMMANDS:server           Run management serveragent            Run node agentkubectl          Run kubectlcrictl           Run crictlctr              Run ctrcheck-config     Run config checktoken            Manage tokensetcd-snapshotsecrets-encrypt  Control secrets encryption and keys rotationcertificate      Manage K3s certificatescompletion       Install shell completion scripthelp, h          Shows a list of commands or help for one commandGLOBAL OPTIONS:--debug                     (logging) Turn on debug logs [$K3S_DEBUG]--data-dir value, -d value  (data) Folder to hold state default /var/lib/rancher/k3s or ${HOME}/.rancher/k3s if not root [$K3S_DATA_DIR]--help, -h                  show help--version, -v               print the version

如上输出，安装完K3s后，自动安装kubectl、ctr、crictl等命令行工具。
在这里插入图片描述

【一般】（注意这里的加粗，踩过坑）情况下：

输入ctr命令等价于输入k3s ctr命令；
输入k命令（在/root/.bashrc配置文件里有追加alias k='kubectl'）等价于输入k3s kubectl命令；
输入crictl命令等价于输入k3s crictl命令。

后来踩过一个坑之后，才注意到ctr输出的版本和k3s ctr输出的版本不一致：
在这里插入图片描述
两者具有不同的命名空间；准确来说，在k3s（实际上还是k8s）下，只有一个k8s.io命名空间：

总结：

k3s server [flags]    # Run K3s in server mode
k3s agent [flags]     # Run K3s in agent mode
k3s kubectl [args]    # Run embedded kubectl
k3s crictl [args]     # Run embedded crictl
k3s ctr [args]        # Run embedded ctr

问题

记录在实战使用k3s时遇到的问题。

`/etc/systemd/system/k3s.service`和`/etc/systemd/system/k3s.service.env`

有何区别？

其他

K3s和K8s

K3s有别于标准K8s发行版的几个特点：

单一二进制文件打包：所有K8s组件都打包在一个不到100MB的二进制文件中；
简化存储：使用SQLite作为默认存储后端，可选择etcd、MySQL或PostgreSQL；
捆绑组件：包括CoreDNS、Traefik、Metrics Server和Local Storage Provisioner等基本附加组件；
减少依赖性：最少的操作系统依赖性（只需正常的内核和cgroup挂载）；
安全通信：使用WebSocket隧道安全连接节点，无需公开kubelet API；
资源要求低：设计为每个节点只需不到512MB内存即可运行。

特性	K8s	K3s
资源占用	较高，需要较多CPU和内存	极低，适合资源受限的环境
安装复杂度	较复杂，需要较多配置	非常简单，一键安装
组件	包含所有k8s组件，如kubelet、kube-proxy、etcd等	去除非核心组件，如用SQLite替代etcd
存储	支持多种存储后端，如etcd	默认使用SQLite，也支持etcd、MySQL等
适用场景	大规模生产环境、复杂应用	边缘计算、IoT、开发测试、资源受限环境
高可用	原生支持HA	需要额外配置支持HA
社区	社区庞大	社区较小，由Rancher提供支持
生态系统	非常丰富，支持各种插件和工具，如Helm、Istio、Prometheus等	较小，但兼容大部分k8s工具和插件
性能	适合大规模集群，性能优化较好	轻量级，适合小规模集群和边缘场景

AutoK3S

https://github.com/cnrancher/autok3s
https://docs.rancher.cn/docs/k3s/autok3s/_index/

docker run -itd --restart=unless-stopped -p 8080:8080 cnrancher/autok3s:v0.9.3-arm

k3d

GitHub，官网，
中文文档：

https://istio.io/latest/zh/docs/setup/platform-setup/k3d/

k3d将k3s封装在docker容器内并运行。k3d允许你在单个主机上运行多个K3s集群，并使用熟悉的Docker工具进行管理。

安装k3d：curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | TAG=v5.4.5 bash

K3S和KubeEdge

KubeEdge是华为云开源的云原生边缘计算平台项目，目标是将Kubernetes原生的容器编排和调度能力拓展到边缘，并为边缘应用部署、云与边缘间的元数据同步、边缘设备管理等提供基础架构支持。

对比项	KubeEdge	K3S
核心定位	专注于云边协同，实现云端统一管理与边缘设备智能联动，支持海量异构设备接入	轻量化的k8s发行版，旨在降低k8s的部署复杂度与资源消耗，适用于资源受限的边缘节点
设计目标	解决云边协同、边缘自治、设备管理等问题，适合物联网（IoT）和需要离线运行的场景	提供完整k8s功能，但通过精简组件和优化资源占用，适配边缘和IoT设备
适用层级	主要面向设备边缘（如智能家居、工业传感器）和基础设施边缘（如边缘网关）	更适合基础设施边缘（如小型服务器集群），要求节点具备一定资源（如1-2 CPU核心、512MB内存）
核心功能	- 云边协同：云端管理面通过标准k8s API控制边缘节点和设备 - 设备管理：通过devicetwin抽象物理设备，支持MQTT协议接入物联网设备 - 离线自治：边缘节点离线时仍能通过本地元数据管理（metamanager）维持运行	- 轻量化k8s：内置SQLite替代etcd，默认集成Traefik、Flannel等组件 - 单二进制部署：所有控制面组件合并为单一进程，降低资源占用
扩展能力	支持通过k8s CRD扩展设备管理能力，与物联网协议（如Modbus、ZigBee）深度集成	依赖标准k8s生态工具（如Helm、Prometheus），但缺乏原生设备管理功能
高可用方案	- 云端控制面支持多副本，边缘节点通过edgehub实现与云端的可靠通信 - 边缘节点离线时仍能自治运行，数据通过metamanager持久化	- 支持多Server节点高可用，需依赖外部数据库（如etcd、MySQL） - 单节点默认使用SQLite，无原生云边协同能力
资源占用	- 边缘节点内存占用约100-200MB（含设备管理组件） - 云端组件需独立部署（如k8s Master）	- 单节点内存占用约50-100MB（仅Agent节点更低） - 管理面（Server）需额外资源（如1GB内存）
生态支持	CNCF项目，更注重与物联网生态的整合	依托Rancher社区，更适合传统k8s用户
版本兼容性	KubeEdge需适配k8s版本升级	可独立更新，兼容性更强
典型场景	- 工业物联网（IIoT）：工厂设备数据采集与云端联动 - 智能家居：通过边缘节点管理家庭设备	- 边缘服务器集群：小型k8s集群部署（如CDN节点） - 开发测试环境：本地轻量化k8s环境
局限性	- 对云端依赖较强，边缘节点功能需与云端协同 - 设备管理功能复杂，学习成本较高	- 缺乏原生云边协同能力，多集群管理需依赖第三方工具 - 不支持边缘设备直接接入，需额外开发适配

总结与选型建议

项目	优势	劣势	选型建议
KubeEdge	云边协同能力强、支持异构设备接入、适合离线场景	架构复杂、对云端依赖高、边缘节点资源需求较高	适用于需要云端统一管理且边缘设备异构性强的场景（如工业物联网）
K3S	轻量化、部署简单、兼容标准k8s工具链	缺乏设备管理能力、多集群管理方案不成熟	适用于资源有限但需完整k8s功能的边缘节点（如小型服务器集群）