[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.top-K3S工作原理图

K3S 架构图

有单节点、高可用等多种架构方式，你可以根据实际情况选择架构方式。

• 单节点架构：有一个内嵌 SQLite 数据库的单节点 K3s server，在此种配置中每个 agent 节点都注册到同一个 server 节点。
• 高可用架构: 多个K3s Server节点为 Kubernetes API 提供服务并运行其他 control-plane 服务，并需挂载一个external database外部数据库作为数据存储的媒介。

weiyigeek.top-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环境。

# 0.此处环境为Ubuntu 22.04 上进行实践安装
uname -a
  # Linux Ubuntu-Security 5.15.0-48-generic #54-Ubuntu SMP Fri Aug 26 13:26:29 UTC 2022 x86_64 x86_64 x86_64 GNU/Linux

# 1.使用https://get.k3s.io 提供的安装脚本在基于 systemd 和 openrc 的系统上安装 K3s 作为服务。
# Check for Ready node, takes maybe 30 seconds
curl -sfL https://get.k3s.io | INSTALL_K3S_CHANNEL=latest sh -

# 2.国内用户，可以使用以下方法加速安装：
curl -sfL https://rancher-mirror.oss-cn-beijing.aliyuncs.com/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn INSTALL_K3S_CHANNEL=latest K3S_TOKEN=k3s.weiyigeek.top sh -s - \
     --system-default-registry "registry.cn-hangzhou.aliyuncs.com"
# 离线安装：INSTALL_K3S_MIRROR=cn INSTALL_K3S_CHANNEL=latest K3S_TOKEN=k3s.weiyigeek.top ./k3s-install.sh --system-default-registry "registry.cn-hangzhou.aliyuncs.com"
# 执行结果: 
  # [INFO]  Finding release for channel latest
  # [INFO]  Using v1.25.3+k3s1 as release
  # [INFO]  Downloading hash rancher-mirror.oss-cn-beijing.aliyuncs.com/k3s/v1.25.3-k3s1/sha256sum-amd64.txt
  # [INFO]  Downloading binary rancher-mirror.oss-cn-beijing.aliyuncs.com/k3s/v1.25.3-k3s1/k3s
  # [INFO]  Verifying binary download
  # [INFO]  Installing k3s to /usr/local/bin/k3s
  # [INFO]  Skipping installation of SELinux RPM
  # [INFO]  Creating /usr/local/bin/kubectl symlink to k3s
  # [INFO]  Creating /usr/local/bin/crictl symlink to k3s
  # [INFO]  Creating /usr/local/bin/ctr symlink to k3s
  # [INFO]  Creating killall script /usr/local/bin/k3s-killall.sh
  # [INFO]  Creating uninstall script /usr/local/bin/k3s-uninstall.sh
  # [INFO]  env: Creating environment file /etc/systemd/system/k3s.service.env
  # [INFO]  systemd: Creating service file /etc/systemd/system/k3s.service
  # [INFO]  systemd: Enabling k3s unit
  # Created symlink /etc/systemd/system/multi-user.target.wants/k3s.service → /etc/systemd/system/k3s.service.
  # [INFO]  systemd: Starting k3s  # 表示安装和k3s服务启动成功

$ ls /usr/local/bin
crictl  ctr  k3s  k3s-killall.sh  k3s-uninstall.sh

步骤 02.查看k3s服务安装环境验证。

# 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.top-载kubernetes最新的二进制客户端文件下载图

# 0.访问k8s项目Release首页,然后可以查看到最新版本以及标注出来的"CHANGELOG"，点击 Client Binary。
# https://github.com/kubernetes/kubernetes/releases
# Downloads for v1.26.0
#     Source Code
#     Client Binaries
#     Server Binaries 
#     Node Binaries
#     Container Images

wget https://dl.k8s.io/v1.26.0/kubernetes-client-linux-amd64.tar.gz &&  tar -zxvf kubernetes-client-linux-amd64.tar.gz
cp kubernetes/client/bin/kubectl /usr/local/bin/kubectl

# 自动补齐
apt install -y bash-completion && source /usr/share/bash-completion/bash_completion
source <(kubectl completion bash)
echo "source <(kubectl completion bash)" >> ~/.bashrc

# 1.设置 kubeconfig 文件路径用于对 Kubernetes 集群的访问。
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml

# 2.查看运行正常后的kube-system名称空间下的pod信息。
$ k3s kubectl get node --show-labels
  NAME        STATUS   ROLES                  AGE   VERSION        LABELS
  master-01   Ready    control-plane,master   65s   v1.25.3+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=master-01,kubernetes.io/os=linux,node-role.kubernetes.io/control-plane=true,node-role.kubernetes.io/master=true,node.kubernetes.io/instance-type=k3s

$ kubectl get pod -A
  NAMESPACE     NAME                                      READY   STATUS      RESTARTS   AGE
  kube-system   coredns-64858695d9-87272                  1/1     Running     0          88s
  kube-system   local-path-provisioner-858c864885-kcgzp   1/1     Running     0          88s
  kube-system   helm-install-traefik-crd-qnkdm            0/1     Completed   0          88s
  kube-system   metrics-server-5d7f9fc86-8jhqk            1/1     Running     0          88s
  kube-system   svclb-traefik-4e10ea70-9s2nf              2/2     Running     0          61s
  kube-system   helm-install-traefik-qjdss                0/1     Completed   1          88s
  kube-system   traefik-b4bf7b498-fkbb5                   1/1     Running     0          61s

# 3.Pod 创建测试与运行查看
kubectl run hello-k3s --image=alpine:latest --image-pull-policy=IfNotPresent --restart=Never --env="project=k3s" --labels="app=helloworld"  --command -- echo "hello world! K3s !"
kubectl get pod --show-labels -o wide
  # NAME        READY   STATUS      RESTARTS   AGE   IP           NODE              NOMINATED NODE   READINESS GATES   LABELS
  # hello-k3s   0/1     Completed   0          29s   10.42.0.17   ubuntu-security   <none>           <none>            app=helloworld

kubectl logs -f hello-k3s
  # hello world! K3s !

步骤 04.一条命令将其他工作节点加入到k3s集群管理。

server-ip=10.10.107.201
k3s-token=k3s.weiyigeek.top
curl -sfL http://rancher-mirror.cnrancher.com/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn K3S_URL=https://${server-ip}:6443 K3S_TOKEN=${k3s-token} sh -

步骤 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'

k get ns
k get pod -A

2.K3s 配置目录及文件路径说明。

# 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 在运行时安装。

ls /var/lib/rancher/k3s/server/manifests
ccm.yaml  coredns.yaml  local-storage.yaml  metrics-server  rolebindings.yaml  traefik.yaml

4.k3s默认使用 containerd 作为容器运行时, 在 goroutine 中以 子进程 方式 启动 containerd。

ps aux | grep "k3s server" | grep -v "grep"
root     1209470  3.2 12.0 1267032 484888 ?      Ssl  15:47   1:21 /usr/local/bin/k3s server

ps -A -ostat,pid,ppid,cmd | grep 1209470 | grep -v "grep"
Ssl  1209470       1 /usr/local/bin/k3s server
Sl   1209529 1209470 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

3.脚本离线安装

你可以使用两种不同的方法在离线环境中安装 K3s，离线环境是不直接连接到 Internet 的任何环境，你可以部署一个私有镜像仓库，或者你可以手动部署镜像，比如用于小型集群。

通常离线安装的两大步骤, 步骤1部署镜像, 步骤2安装 K3s

部署私有镜像仓库

• Harbor安装与配置:
• K3S 私有镜像仓库配置:

mirrors:
  docker.io:
    endpoint:
      - "https://harbor.weiyigeek.top"
    rewrite:
      "^rancher/(.*)": "mirrorproject/rancher-images/$1"
configs:
  "harbor.weiyigeek.top":
    auth:
      username: xxxxxx # 这是私有镜像仓库的用户名
      password: xxxxxx # 这是私有镜像仓库的密码
    tls:
      cert_file: # 镜像仓库中使用的cert文件的路径。
      key_file:  # 镜像仓库中使用的key文件的路径。
      ca_file:   # 镜像仓库中使用的ca文件的路径。

例如，以下配置将透明地从 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.初始化配置节点相关配置。

# 配置主机名称, 注意各个节点名称需不一致。
hostnamectl hostname master-01
vim /etc/hostname

步骤 01.拉取指定版本的k3s二进制文件到本地 /usr/local/bin/ 目录之中以及获取你所运行的 K3s 版本的镜像 tar 文件。

# 1.K3s 二进制文件
#!/bin/bash
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。

# 当使用 INSTALL_K3S_SKIP_DOWNLOAD 环境变量运行 K3s 脚本时，K3s 将使用本地的脚本和二进制。
# Server 节点
INSTALL_K3S_SKIP_DOWNLOAD=true ./install.sh

# Agent 节点 INSTALL_K3S_MIRROR=cn
# 将 myserver 替换为 server 的 IP 或有效的 DNS
# 将 mynodetoken 替换 server 节点的 token
# token 通常在/var/lib/rancher/k3s/server/node-token
INSTALL_K3S_SKIP_DOWNLOAD=true K3S_URL=https://myserver:6443 K3S_TOKEN=mynodetoken ./install.sh

步骤 04.高可用安装需要调整安装命令，以便指定 INSTALL_K3S_SKIP_DOWNLOAD=true并在本地运行安装脚本, 您还将利用INSTALL_K3S_EXEC=’args’为 k3s 提供其他参数。

INSTALL_K3S_SKIP_DOWNLOAD=true INSTALL_K3S_EXEC='server' K3S_DATASTORE_ENDPOINT='mysql://username:password@tcp(hostname:3306)/database-name' ./install.sh

4.升级安装

K3s 支持手动与自动升级，下面简单的对升级流程进行说明。

脚本离线升级流程:

1. 从 K3s GitHub Release 页面下载要升级到的 K3s 版本, 将 tar 文件放在每个节点的 /var/lib/rancher/k3s/agent/images/ 目录下, 删除旧的 tar 文件。
2. 复制并替换每个节点上/usr/local/bin中的旧 K3s 二进制文件, 复制 https://get.k3s.io 的安装脚本（因为它可能在上次发布后发生了变化）再次运行脚本。
3. 重启 K3s 服务。

自动升级功能
描述: 从 v1.17.4+k3s1 开始，K3s 支持自动升级, 要在离线环境中启用此功能，您必须确保所需镜像在您的私有镜像仓库中可用, 但是在实际情况中并不建议开启哟。

1. 你将需要与你打算升级到的 K3s 版本相对应的 rancher/k3s-upgrade 版本, 注意，镜像标签将 K3s 版本中的+替换为-，因为 Docker 镜像不支持+。

2. 你还需要在你要部署的 system-upgrad-controller manifestYAML 中指定的 system-upgrad-controller 和 kubectl 的版本。
   在这里检查 system-upgrad-controller 的最新版本，并下载 system-upgrad-controller.yaml 来确定你需要推送到私有镜像仓库的版本。
   例如，在system-upgrade-controller的 v0.4.0 版本中，在 manifest YAML 中指定了这些镜像：

   rancher/system-upgrade-controller:v0.4.0
   rancher/kubectl:v0.17.0

3. 将必要的 rancher/k3s-upgrade、rancher/system-upgrade-controller 和 rancher/kubectl 镜像添加到您的私有镜像仓库中以后 ，就可以按照K3s 自动升级指南进行操作。

参考地址: https://docs.rancher.cn/docs/k3s/upgrades/automated/_index

---

0x02 配置文件

K3s 配置文件

mkdir -vp /etc/rancher/{k3s,node}
tee /etc/rancher/k3s/config.yaml <<'EOF'
node-name: master-01
bind-address: 0.0.0.0
https-listen-port: 6443
cluster-cidr: 10.42.0.0/16
service-cidr: 10.43.0.0/16
cluster-domain: cluster.local
token: k3s.weiyigeek.top
agent-token: agent.weiyigeek.top
pause-image: registry.cn-hangzhou.aliyuncs.com/google_containers/pause:3.6
EOF

k3s 配置服务变量

tee /etc/systemd/system/k3s.service.env <<'EOF'
INSTALL_K3S_MIRROR=cn
INSTALL_K3S_CHANNEL=latest
K3S_TOKEN='k3s.weiyigeek.top'
K3S_AGENT_TOKEN='agent.weiyigeek.top'
EOF

K3S systemd 服务

tee /etc/systemd/system/k3s.service <<'EOF'
[Unit]
Description=Lightweight Kubernetes
Documentation=https://k3s.io
Wants=network-online.target
After=network-online.target

[Install]
WantedBy=multi-user.target

[Service]
Type=notify
EnvironmentFile=-/etc/default/%N
EnvironmentFile=-/etc/sysconfig/%N
EnvironmentFile=-/etc/systemd/system/k3s.service.env
KillMode=process
Delegate=yes
# Having non-zero Limit*s causes performance problems due to accounting overhead
# in the kernel. We recommend using cgroups to do container-local accounting.
LimitNOFILE=1048576
LimitNPROC=infinity
LimitCORE=infinity
TasksMax=infinity
TimeoutStartSec=0
Restart=always
RestartSec=5s
ExecStartPre=/bin/sh -xc '! /usr/bin/systemctl is-enabled --quiet nm-cloud-setup.service'
ExecStartPre=-/sbin/modprobe br_netfilter
ExecStartPre=-/sbin/modprobe overlay
ExecStart=/usr/local/bin/k3s server --system-default-registry registry.cn-hangzhou.aliyuncs.com
EOF

# 使用 `systemctl` 命令启动 `k3s server` 服务
# Kubeconfig is written to /etc/rancher/k3s/k3s.yaml
$ systemctl daemon-reload && systemctl restart k3s.service
$ systemctl status -l k3s.service
$ journalctl -xeu k3s.service

# On a different node run the below. NODE_TOKEN comes from /var/lib/rancher/k3s/server/node-token
$ cat /var/lib/rancher/k3s/server/node-token
K10d3c367aa2703bccaed90f0b1cf14c1091adb3fc554805c35f2300b0b8c269868::server:k3s.weiyigeek.top

安装环境验证及配置文件检测

k3s check-config

Worker 节点

sudo k3s server &
sudo k3s kubectl get node


# On a different node run the below. NODE_TOKEN comes from /var/lib/rancher/k3s/server/node-token
# on your server
sudo k3s agent --server https://myserver:6443 --token ${NODE_TOKEN}

rm -rf /var/lib/kubelet /var/lib/rancher

---

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权限错误问题。

~$ 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 错误问题。

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 是否正常运行，若没有请排查错误

kubectl get pod -n kube-system metrics-server-5d7f9fc86-8jhqk
NAME                             READY   STATUS    RESTARTS   AGE
metrics-server-5d7f9fc86-8jhqk   1/1     Running   0          110m

---

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/