[toc]
0x00 前言简述
Q: 什么是 K3S?
描述: 它是一个轻量级K8S(Lightweight Kubernetes)同时它也是一个云原生计算基金会(CNCF)沙盒项目, 为物联网和边缘计算构建的经过认证的 Kubernetes 发行版, 减少了kubernetes云供应商相关插件所以其更加精简, 部署也更加简单。
为什么叫 K3s?
我们希望安装的 Kubernetes 在内存占用方面只是一半的大小,且 Kubernetes 是一个10个字母的单词简写为 K8s。所以,有 Kubernetes 一半大的东西就是一个 5 个字母的单词,简写为 K3s (其没有全称,也没有官方的发音)
。
Q: 为什么使用 K3S?
1) 简化和安全 : K3s
单个二进制文件小于50MB,可减少安装、运行和自动更新生产 Kubernetes 集群
所需的依赖关系和步骤。
2) 边缘的完美选择: 高度可用、经过认证的 Kubernetes 发行版,专为无人值守、资源受限的远程位置或IoT 设备
内部的生产工作负载而设计。
3) 支持ARM优化 : K3S 提供了 ARM64 和 ARMv7 都支持二进制文件和多架构映像, 所以可以运行在嵌入式设备
之中。
4) 资源占用更少: 不仅能够缩短启动集群
的时间,还能够减少集群需要消耗的资源
。
5) 存储机制 : 使用基于sqlite3
的轻量级存储后端作为默认存储,但同时支持使用etcd3、MySQL 和 PostgreSQL
作为存储机制。
6) 内置增强功能 : 添加了简单但功能强大的batteries-included
功能,例如本地存储提供程序,服务负载均衡器,Helm controller 和 Traefik Ingress controller
, 所有Kubernetes control-plane
组件的操作都封装在单个二进制文件和进程中,使 K3s 具有自动化和管理包括证书分发在内的复杂集群操作的能力。
7) 更少的依赖 : 最大程度减轻了外部依赖性,K3s 仅需要 kernel 和 cgroup 挂载。
K3S 工作原理
描述: K3S 它由 Server 与 Agent 两大节点组成,其中K3s server 是运行k3s server命令的机器(裸机或虚拟机),而 K3s worker 节点是运行k3s agent命令的机器。

WeiyiGeek.K3S工作原理图
K3S 架构图
有单节点、高可用等多种架构方式,你可以根据实际情况选择架构方式。
- 单节点架构:有一个内嵌 SQLite 数据库的单节点 K3s server,在此种配置中每个 agent 节点都注册到同一个 server 节点。
- 高可用架构: 多个K3s Server节点为 Kubernetes API 提供服务并运行其他 control-plane 服务,并需挂载一个external database外部数据库作为数据存储的媒介。

WeiyiGeek.K3S架构图
K3S Agent 节点
Agent 节点 用k3s agent进程发起的 websocket 连接注册,连接由作为代理进程一部分运行的客户端负载均衡器维护。
Agent 将使用节点集群 secret 以及随机生成的节点密码向 k3s server 注册, 密码存储在 /etc/rancher/node/password
路径下, K3s server 将把各个节点的密码存储为 Kubernetes secrets,随后的任何尝试都必须使用相同的密码,节点密码秘密存储在kube-system命名空间中,名称使用模板<host>.node-password.k3s
温馨提示:
- 在 K3s v1.20.2 之前,K3s server 将密码存储在
/var/lib/rancher/k3s/server/cred/node-passwd
的磁盘上。 - 如果您删除了 agent 的/etc/rancher/node 目录,则需要为该 agent 重新创建密码文件,或者从 server 中删除该条目。
- 通过使用
--with-node-id
标志启动 K3s server 或 agent,可以将唯一的节点 ID 附加到主机名中。
K3s 应用场景
描述: 由于运行 K3s 所需的资源相对较少,所以 K3s 也适用于开发和测试场景,以及边缘计算-Edge、物联网-IoT、CI、ARM、嵌入 K8s
等场景中!
综上所述,使用 K3s 不仅能够缩短启动集群的时间,还能够减少集群需要消耗的资源。
0x01 安装实践
1.环境要求
描述: 无论您是将 K3s 集群配置为在 Docker 还是 Kubernetes 设置中运行,运行 K3 的每个节点都应满足以下最低要求。
测试环境
- 硬件: 内存最少512MB(建议至少1GB), CPU 最少一个, 磁盘最好使用SSD。
- 软件: 选择常用的操作系统例如
Ubuntu、Debian、CentOS
等, 但是针对某些操作系统有特定要求例如Red Hat/CentOS
、Alpine Linux
和Raspbian Buster
. - 先决条件:
- 节点不能具有相同的主机名
- 防火墙需要对k3s Server 的 6443端口 放行,因为 K3s服务器需要端口 6443 才能被所有节点访问。
生产环境
对于生产环境中的外部数据库,建议使用以下数据库MySQL (常用)/ PostgreSQL / etcd
,并且硬件要求取决于 K3s 集群的大小以下是高可用性K3s服务器中节点的最低CPU和内存要求:
DEPLOYMENT SIZE | NODES | VCPUS | RAM |
---|---|---|---|
Small | Up to 10 | 2 | 4 GB |
Medium | Up to 100 | 4 | 8 GB |
Large | Up to 250 | 8 | 16 GB |
X-Large | Up to 500 | 16 | 32 GB |
XX-Large | 500+ | 32 | 64 GB |
K3s 软件包需要的依赖项包括
- containerd
- Flannel
- CoreDNS
- CNI
- 主机实用程序(iptables、socat 等)
- Ingress controller(Traefik)
- 嵌入式服务负载均衡器(service load balancer)
- 嵌入式网络策略控制器(network policy controller)
服务端口
K3s服务器节点的入站规则(Inbound Rules for K3s Server Nodes)
PROTOCOL | PORT | SOURCE | DESCRIPTION |
---|---|---|---|
TCP | 6443 | K3s agent nodes | Kubernetes API Server |
UDP | 8472 | K3s server and agent nodes | Required only for Flannel VXLAN |
UDP | 51820 | K3s server and agent nodes | Required only for Flannel Wireguard backend |
UDP | 51821 | K3s server and agent nodes | Required only for Flannel Wireguard backend with IPv6 |
TCP | 10250 | K3s server and agent nodes | Kubelet metrics |
TCP | 2379-2380 | K3s server nodes | Required only for HA with embedded etcd |
当前【2022年6月14日 22:04:49】节点最新版本为 v1.24.1+k3s1 (https://github.com/k3s-io/k3s/releases/tag/v1.24.1+k3s1)
2.脚本在线安装
描述:k3s官方提供的一键安装脚本仅需30秒即可启动k3s,但是国内用户使用官方链接下载安装巨慢无比,好在提供了国内快速安装方法脚本。
环境变量
使用此方法安装 K3s 时,可使用以下环境变量来配置安装选项(重点):
- INSTALL_K3S_SKIP_DOWNLOAD :如果设置为 “true “将不会下载 K3s 的哈希值或二进制。
- INSTALL_K3S_SYMLINK :默认情况下,如果路径中不存在命令,将为 kubectl、crictl 和 ctr 二进制文件创建符号链接。如果设置为’skip’将不会创建符号链接,而’force’将覆盖。
- INSTALL_K3S_SKIP_ENABLE :如果设置为 “true”,将不启用或启动 K3s 服务。
- INSTALL_K3S_SKIP_START :如果设置为 “true “将不会启动 K3s 服务。
- INSTALL_K3S_VERSION :从 Github 下载 K3s 的版本。如果没有指定,将尝试从”stable”频道下载。
- INSTALL_K3S_BIN_DIR :安装 K3s 二进制文件、链接和卸载脚本的目录,或者使用/usr/local/bin作为默认目录。
- INSTALL_K3S_BIN_DIR_READ_ONLY :如果设置为 true 将不会把文件写入INSTALL_K3S_BIN_DIR,强制设置INSTALL_K3S_SKIP_DOWNLOAD=true。
- INSTALL_K3S_SYSTEMD_DIR :安装 systemd 服务和环境文件的目录,或者使用/etc/systemd/system作为默认目录。
- INSTALL_K3S_EXEC :带有标志的命令,用于在服务中启动 K3s。如果未指定命令,并且设置了K3S_URL,它将默认为“agent”。如果未设置K3S_URL,它将默认为“server”。要获得帮助,请参考此示例。
- INSTALL_K3S_NAME :要创建的 systemd 服务名称,如果以服务器方式运行 k3s,则默认为’k3s’;如果以 agent 方式运行 k3s,则默认为’k3s-agent’。如果指定了服务名,则服务名将以’k3s-‘为前缀。
- INSTALL_K3S_TYPE :要创建的 systemd 服务类型,如果没有指定,将默认使用 K3s exec 命令。
- INSTALL_K3S_SELINUX_WARN :如果设置为 true,则在没有找到 k3s-selinux 策略的情况下将继续。
- INSTALL_K3S_SKIP_SELINUX_RPM :如果设置为 “true “将跳过 k3s RPM 的自动安装。
- INSTALL_K3S_CHANNEL_URL :用于获取 K3s 下载网址的频道 URL。默认为 https://update.k3s.io/v1-release/channels 。
- INSTALL_K3S_CHANNEL :用于获取 K3s 下载 URL 的通道。默认值为 “stable”。选项包括:stable, latest, testing。
- K3S_CONFIG_FILE :指定配置文件的位置。默认目录为/etc/rancher/k3s/config.yaml。
- K3S_TOKEN :用于将 server 或 agent 加入集群的共享 secret。
- K3S_TOKEN_FILE :指定 cluster-secret,token 的文件目录。
- INSTALL_K3S_MIRROR: 使用国内镜像源进行安装
操作步骤
步骤01.国内使用安装脚本快速安装单节点实例的k3s环境。
1 | # 0.此处环境为Ubuntu 22.04 上进行实践安装 |
步骤 02.查看k3s服务安装环境验证。1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28# 1.查看k3s服务状态
systemctl status -l k3s.service
● k3s.service - Lightweight Kubernetes
Loaded: loaded (/etc/systemd/system/k3s.service; enabled; vendor preset: enabled)
Active: active (running) since Sun 2022-10-30 14:27:16 CST; 3min 55s ago
Docs: https://k3s.io
Process: 84116 ExecStartPre=/bin/sh -xc ! /usr/bin/systemctl is-enabled --quiet nm-cloud-setup.service (code=exited, status=0/SUCCESS)
Process: 84118 ExecStartPre=/sbin/modprobe br_netfilter (code=exited, status=0/SUCCESS)
Process: 84122 ExecStartPre=/sbin/modprobe overlay (code=exited, status=0/SUCCESS)
Main PID: 84123 (k3s-server)
Tasks: 116
Memory: 1.2G
CPU: 40.024s
CGroup: /system.slice/k3s.service
├─84123 "/usr/local/bin/k3s server"
├─84169 containerd -c /var/lib/rancher/k3s/agent/etc/containerd/config.toml -a /run/k3s/containerd/containerd.sock --state /run/k3s/containerd --root /var/lib/rancher/k3s/agent/containerd
.......
# 2.查看 k3s 节点相关
k3s kubectl get node --show-labels -o wide
# NAME STATUS ROLES AGE VERSION INTERNAL-IP EXTERNAL-IP OS-IMAGE KERNEL-VERSION CONTAINER-RUNTIME LABELS
# ubuntu-security Ready control-plane,master 2m17s v1.25.3+k3s1 10.10.107.201 <none> Ubuntu 22.04.1 LTS 5.15.0-48-generic containerd://1.6.8-k3s1 beta.kubernetes.io/arch=amd64,beta.kubernetes.io/instance-type=k3s,beta.kubernetes.io/os=linux,egress.k3s.io/cluster=true,kubernetes.io/arch=amd64,kubernetes.io/hostname=ubuntu-security,kubernetes.io/os=linux,node-role.kubernetes.io/control-plane=true,node-role.kubernetes.io/master=true,node.kubernetes.io/instance-type=k3s
# 3.查看 k3s 集群配置文件
k3s kubectl cluster-info
# Kubernetes control plane is running at https://127.0.0.1:6443
# CoreDNS is running at https://127.0.0.1:6443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy
# Metrics-server is running at https://127.0.0.1:6443/api/v1/namespaces/kube-system/services/https:metrics-server:https/proxy
步骤 03.在 尝试在 k3s 环境中快速创建 hello world Pod 容器, 此处为了方便我们使用kubectl命令,我们可以设置别名或者直接下载kubernetes最新的二进制客户端文件(kubectl) ,下载地址【 https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.26.md 】。

WeiyiGeek.载kubernetes最新的二进制客户端文件下载图
1 | # 0.访问k8s项目Release首页,然后可以查看到最新版本以及标注出来的"CHANGELOG",点击 Client Binary。 |
步骤 04.一条命令将其他工作节点加入到k3s集群管理。
1 | server-ip=10.10.107.201 |
步骤 05. 卸载 K3s 如果您使用安装脚本安装了 K3s,那么在安装过程中会自动生成一个卸载 K3s 的脚本。
卸载 K3s 会删除集群数据和所有脚本, 要使用不同的安装选项重新启动集群,请使用不同的标志重新运行安装脚本。
- 要从 server 节点卸载 K3s,请运行:
/usr/local/bin/k3s-uninstall.sh
- 要从 agent 节点卸载 K3s,请运行:
/usr/local/bin/k3s-agent-uninstall.sh
补充说明:
1.除此之外我们还可以为K3S命令行设置别名,例如,临时生效alias k='k3s kubectl'
1
2k get ns
k get pod -A
2.K3s 配置目录及文件路径说明。1
2
3
4
5
6
7
8
9
10
11
12
13
14
15# k3s 相关配置
$ tree /etc/rancher
/etc/rancher
├── k3s
│ └── k3s.yaml # kubeconfig
└── node
└── password # 随机生成的节点密码向 k3s server 注册
# k3s 节点数据信息
$ ls /var/lib/rancher/k3s/
agent data server
# kubelet 服务运行配置相关信息
$ ls /var/lib/kubelet
cpu_manager_state device-plugins memory_manager_state plugins plugins_registry pod-resources pods
3.自动部署的清单, 位于目录路径 /var/lib/rancher/k3s/server/manifests
的清单在构建时被捆绑到 K3s 二进制文件中, 将由 `rancher/helm-controller 在运行时安装。1
2ls /var/lib/rancher/k3s/server/manifests
ccm.yaml coredns.yaml local-storage.yaml metrics-server rolebindings.yaml traefik.yaml
4.k3s默认使用 containerd 作为容器运行时, 在 goroutine 中以 子进程 方式 启动 containerd。
1 | ps aux | grep "k3s server" | grep -v "grep" |
3.脚本离线安装
你可以使用两种不同的方法在离线环境中安装 K3s,离线环境是不直接连接到 Internet 的任何环境,你可以部署一个私有镜像仓库,或者你可以手动部署镜像,比如用于小型集群。
通常离线安装的两大步骤, 步骤1部署镜像
, 步骤2安装 K3s
部署私有镜像仓库
- Harbor安装与配置:
- K3S 私有镜像仓库配置:
1 | mirrors: |
例如,以下配置将透明地从 harbor.weiyigeek.top/mirrorproject/rancher-images/coredns-coredns:1.6.3
拉取镜像 docker.io/rancher/coredns-coredns:1.6.3
, 镜像仍将以原始名称存储,所以 crictl image ls
将显示 docker.io/rancher/coredns-coredns:1.6.3
在节点上是可用的,即使镜像是以不同的名字从镜像仓库中拉取的。
安装实践
描述: 一切开源,立即体验,K3S 二进制项目地址 [ https://github.com/k3s-io/k3s/releases/ ], 如果是我们手动进行二进制环境安装,就可能稍微麻烦一点了。
步骤 00.初始化配置节点相关配置。1
2
3# 配置主机名称, 注意各个节点名称需不一致。
hostnamectl hostname master-01
vim /etc/hostname
步骤 01.拉取指定版本的k3s二进制文件到本地 /usr/local/bin/
目录之中以及获取你所运行的 K3s 版本的镜像 tar 文件。1
2
3
4
5
6
7
8
9
10
11
12# 1.K3s 二进制文件
K3S_VERSION=v1.26.0
wget -c --show-progress https://github.com/k3s-io/k3s/releases/download/${K3S_VERSION}+k3s1/k3s -O /usr/local/bin/k3s
chmod +x /usr/local/bin/k3s
k3s --version
# k3s version v1.26.0+k3s1 (f2585c16)
# go version go1.19.2
# 下载对应 K3s 版本的镜像 tar 文件到指定目录, 并确保拥有可执行权限。完成后,现在可以转到下面的安装 K3s部分
sudo mkdir -p /var/lib/rancher/k3s/agent/images/
sudo cp k3s-airgap-images-amd64.tar.gz /var/lib/rancher/k3s/agent/images/
步骤 03.下载 K3s 安装脚本:https://get.k3s.io, 将安装脚本放在每个离线节点的任意地方,并命名为 install.sh。
1 | # 当使用 INSTALL_K3S_SKIP_DOWNLOAD 环境变量运行 K3s 脚本时,K3s 将使用本地的脚本和二进制。 |
步骤 04.高可用安装需要调整安装命令,以便指定 INSTALL_K3S_SKIP_DOWNLOAD=true
并在本地运行安装脚本, 您还将利用INSTALL_K3S_EXEC=’args’为 k3s 提供其他参数。
1 | INSTALL_K3S_SKIP_DOWNLOAD=true INSTALL_K3S_EXEC='server' K3S_DATASTORE_ENDPOINT='mysql://username:password@tcp(hostname:3306)/database-name' ./install.sh |
4.升级安装
K3s 支持手动与自动升级,下面简单的对升级流程进行说明。
脚本离线升级流程:
- 从
K3s GitHub Release
页面下载要升级到的 K3s 版本, 将 tar 文件放在每个节点的/var/lib/rancher/k3s/agent/images/
目录下, 删除旧的 tar 文件。 - 复制并替换每个节点上/usr/local/bin中的旧 K3s 二进制文件, 复制
https://get.k3s.io
的安装脚本(因为它可能在上次发布后发生了变化)再次运行脚本。 - 重启 K3s 服务。
自动升级功能
描述: 从 v1.17.4+k3s1 开始,K3s 支持自动升级, 要在离线环境中启用此功能,您必须确保所需镜像在您的私有镜像仓库中可用, 但是在实际情况中并不建议开启哟。
你将需要与你打算升级到的 K3s 版本相对应的 rancher/k3s-upgrade 版本, 注意,镜像标签将 K3s 版本中的+替换为-,因为 Docker 镜像不支持+。
你还需要在你要部署的
system-upgrad-controller manifestYAML
中指定的system-upgrad-controller
和kubectl
的版本。
在这里检查 system-upgrad-controller 的最新版本,并下载 system-upgrad-controller.yaml 来确定你需要推送到私有镜像仓库的版本。
例如,在system-upgrade-controller的 v0.4.0 版本中,在 manifest YAML 中指定了这些镜像:1
2rancher/system-upgrade-controller:v0.4.0
rancher/kubectl:v0.17.0将必要的
rancher/k3s-upgrade、rancher/system-upgrade-controller
和rancher/kubectl
镜像添加到您的私有镜像仓库中以后 ,就可以按照K3s 自动升级指南进行操作。
参考地址: https://docs.rancher.cn/docs/k3s/upgrades/automated/_index
0x02 配置文件
K3s 配置文件
1 | mkdir -vp /etc/rancher/{k3s,node} |
k3s 配置服务变量
1 | tee /etc/systemd/system/k3s.service.env <<'EOF' |
K3S systemd 服务
1 | tee /etc/systemd/system/k3s.service <<'EOF' |
安装环境验证及配置文件检测
1 | k3s check-config |
Worker 节点
1 | sudo k3s server & |
0x03 问题解决
安装问题
问题1.如果从国内环境安装 K3s 可能会遇到安装速度特别缓慢或者 time out 的情况,从以上的安装过程可以分析出以下几个原因:
- K3s 的安装脚本 存储在国外的服务器,从国内环境访问可能出现无法访问的情况。
- K3s 默认安装 stable 版本,stable 对应的具体 K3s 版本是通过 https://update.k3s.io/v1-release/channels 解析来的,而这个地址也是运行在一个国外的服务器上。
- 当通过 channel 解析出对应 K3s 的版本为:v1.25.3+k3s1,此时需要到 github 上拉取对应的 K3s 二进制文件。虽然这个二进制文件才几十兆,但国内环境访问 github 经常会出现无法访问的情况。
另外,要完整运行 K3s,还依赖一些系统的服务,这些系统服务(例如:coredns、traefik)都是以容器的方式运行;而这些系统服务依赖的系统镜像默认是从 DockerHub 去拉取。同样从国内访问偶尔会出现无法访问或拉取镜像缓慢的情况。
以上,就是在国内环境使用 K3s 的一些痛点。
解决办法: 参考 0x01 安装实践 -> 脚本在线安装
。
使用问题
问题1.使用kubectl查看节点时报open /etc/rancher/k3s/k3s.yaml: permission denied
权限错误问题。1
2
3~$ kubectl get node
WARN[0000] Unable to read /etc/rancher/k3s/k3s.yaml, please start server with --write-kubeconfig-mode to modify kube config permissions
error: error loading config file "/etc/rancher/k3s/k3s.yaml": open /etc/rancher/k3s/k3s.yaml: permission denied
解决办法: chmod 644 /etc/rancher/k3s/k3s.yaml
问题2.使用k3s命令以及kubectl命令时报 the server is currently unable to handle the request
错误问题。1
E1230 15:37:26.981461 1207736 memcache.go:255] couldn't get resource list for metrics.k8s.io/v1beta1: the server is currently unable to handle the request
解决办法: 请检查 kube-system 名称空间下的 metrics-server-5d7f9fc86-8jhqk
Pod 是否正常运行,若没有请排查错误
1 | kubectl get pod -n kube-system metrics-server-5d7f9fc86-8jhqk |
0x0n 参考来源
官方地址: https://k3s.io/ && https://www.rancher.cn/k3s/
官方文档: https://rancher.com/docs/k3s/latest/en/
项目地址: https://github.com/rancher/k3s/releases/latest && https://github.com/k3s-io/k3s/