Linux安装K3s轻量级集群与边缘计算容器环境详解

直接装 k3s 就行，不用先装 Docker、不依赖 systemd、512MB 内存设备也能跑起来——这是它和标准 Kubernetes 最本质的区别。

为什么 k3s 安装命令里带 curl | sh？

初次接触 k3s 安装命令 curl -sfL https://get.k3s.io | sh - 时，很多人心里会犯嘀咕：这安全吗？是不是太“偷懒”了？

其实不然。这个设计恰恰是 k3s 针对边缘和 IoT 场景的深思熟虑。它用一个自解压脚本，封装了所有复杂的环境适配逻辑。脚本会自动检测你的系统类型（是 Ubuntu、CentOS 还是 Alpine）、内核版本，以及关键的 cgroup 版本（v1 还是 v2），然后才下载对应的二进制文件、生成默认配置并注册为系统服务。这么做，本质上是为了避开不同 Linux 发行版之间包管理器（apt, yum, apk）的碎片化问题，实现“一键通吃”。

命令执行后，几个关键变化会发生：

• k3s 二进制文件会出现在 /usr/local/bin/k3s。
• Systemd 服务单元文件被写入 /etc/systemd/system/k3s.service。
• 脚本默认启用内置的 containerd 作为容器运行时，并且不会启动 Docker daemon——这是故意的，因为 Docker 自带的 containerd 可能与 k3s 管理的版本冲突。

不过，这里有个常见的坑需要注意：如果系统里连基础的 iptables 或 ip6tables 工具都没装，安装就会失败。比如 Alpine 用户，就需要先执行 apk add iptables 打好前置补丁。

k3s 启动后怎么确认集群真就绪了？

安装完成，服务也显示 active (running)，是不是就万事大吉了？别急，systemctl status k3s 只代表进程在跑，不代表控制平面的 API 已经就绪可用。真正的验证，得看下面几点：

• 执行 kubectl get nodes，节点状态必须明确显示为 Ready。如果 STATUS 列是 NotReady 或者空空如也，说明 agent 还没成功连接上 server。
• 运行 kubectl get pods -A，重点观察 kube-system 命名空间下的所有核心 Pod。它们的 READY 列都应该显示为 1/1。尤其要留意 local-path-provisioner（本地存储提供者）和 coredns（集群 DNS）这两个，绝不能是 0/1。

如果命令报错说找不到配置，那很可能是环境变量没设对。k3s 默认生成的 kubeconfig 文件在 /etc/rancher/k3s/k3s.yaml，记得用 export KUBECONFIG=/etc/rancher/k3s/k3s.yaml 指定一下路径再试。

边缘节点加不进去？重点查这三处

向现有集群添加边缘节点（agent），本质就是让新机器上的 k3s agent 进程，能够连接到 server 节点的 HTTPS API 端点，并使用正确的 token 完成认证。这个过程失败，十有八九卡在以下三个环节：

• Token 文件路径不对或内容被篡改：加入集群所需的 token 必须从 server 节点的 /var/lib/rancher/k3s/server/node-token 文件获取。切忌手动敲入，建议直接用 cat 命令输出内容并复制，因为里面可能包含换行符等不可见字符，用文本编辑器中转很容易出错。
• Server 地址填错了：在 agent 节点上安装时，K3S_URL 参数必须填写 server 节点对外可访问的 IP 地址或域名，例如 https://192.168.1.100:6443。填成 https://127.0.0.1:6443（本地回环地址）是新手最常犯的错误，这会导致 agent 试图连接自己。
• 防火墙端口没放开：Server 节点必须开放两个关键端口：6443（Kubernetes API Server）和 8472（Flannel 网络插件的 VXLAN 通信端口）。在 CentOS/RHEL 系上，可以用 firewall-cmd --add-port=6443/tcp --permanent 来放行；在 Ubuntu/Debian 系上，则常用 ufw allow 6443。别忘了操作后重载防火墙规则。

资源吃紧时哪些组件可以关？

k3s 为了开箱即用，默认启用了一批组件。但在内存仅有 512MB 的树莓派或工业网关上，有些组件就显得奢侈了。像 traefik（Ingress 控制器）、servicelb（内置负载均衡器）、local-storage（本地存储类）全关掉，能轻松省出 120MB 以上的常驻内存。

具体操作是在首次安装时，通过环境变量传递禁用参数：

• 禁用 Traefik Ingress Controller：curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="server --disable traefik" sh -
• 禁用 ServiceLB（Klipper Load Balancer）：加上 --disable servicelb，后续如果需要负载均衡，可以考虑使用 hostPort 或手动配置 NodePort 服务。
• 禁用默认的本地存储类：加上 --disable local-storage，除非你计划使用 NFS 或安装了外部的 CSI 存储插件。

这里有个重要提醒：这些 --disable 参数只能在首次安装时指定。如果已经安装好了想修改，需要先执行 sudo /usr/local/bin/k3s-uninstall.sh 彻底卸载，再重新安装并带上所需参数。

一个最常被忽略的底层问题：cgroup 驱动

最后，提一个隐蔽但致命的问题：cgroup 驱动兼容性。尤其是在旧版系统（如 Ubuntu 18.04）上部署新版本 k3s（如 v1.25+）时。

旧系统默认使用 cgroup v1，而新版本 Kubernetes 和 k3s 默认期望使用 cgroup v2。如果发现 k3s 日志里反复刷 failed to load cgroup parent 之类的错误，那很可能就是驱动不匹配。

这通常不是 k3s 配置能解决的，需要修改 Linux 内核的启动参数。具体来说，需要在 GRUB 配置中添加 cgroup_enable=cpuset cgroup_enable=memory cgroup_memory=1 这些参数，然后重启主机，确保系统以 cgroup v1 模式启动。对齐了内核这一层，上层的容器运行时才能正常工作。