搭建 K3s

2024-09-04 17:11 由小OY酱发表于 #其他

概述

K3s 是一个轻量级的 Kubernetes 发行版，能以较少的代价快速搭建一个生产可用的 K8s 集群。参考：K3s - 轻量级 Kubernetes | Rancher文档

本文介绍的是通过其提供的“安装脚本”的方式搭建 K3s 的方法，并结合实际生产使用经验进行相关的配置。

准备工作

明确 K3s 版本

通过 K3s 安装脚本会默认使用 “stable” 的发布 Channel，如果没有特殊要求，保持默认值即可。参考：基础升级 | Rancher文档

如果需要在 K3s 上搭建 Rancher，则需要使用受 Rancher 支持的 K3s 版本，请参考 https://www.suse.com/suse-rancher/support-matrix/all-supported-versions/ 了解其版本对应关系。

准备镜像

由于常见的 Docker Registry 均已被墙，即使通过国内镜像站提供的 K3s 安装脚本亦不能稳定的下载镜像，仅此通过离线的方式提前准备好相关的镜像文件。

参考 K3s 的离线安装步骤，先手动从 K3s GitHub Release 页面获取对应 K3s 版本和架构的镜像 tar 文件，再将其放置到 K3s 的 images 目录下（推荐下载 zst 格式的压缩包，其体积最小）。

参考：离线安装 | Rancher文档

mkdir -p /var/lib/rancher/k3s/agent/images/
cp ./k3s-airgap-images-$ARCH.tar.zst /var/lib/rancher/k3s/agent/images/

K3s 默认使用并内置 containerd 容器运行时，会在启动运行时自动导入上述镜像。

准备配置文件

推荐使用”CONFIG 文件”的方式来对 K3s 进行配置。请编写配置文件并将其放置于 /etc/rancher/k3s/config.yaml。参考：如何使用标志和环境变量 | Rancher文档

注意，直接调整 K3s 的Systemd 服务定义文件虽可以实现对 K3s 的配置，但在“更新 K3s”时安装脚本仍会重新创建并生成 Systemd 服务定义文件，导致我们修改的内容被覆盖，因此不建议这么做。

这里提供我常用的配置文件内容：

disable:
  - traefik
flannel-backend: host-gw
kube-apiserver-arg:
  - 'service-node-port-range=80-32767'
  - 'event-ttl=168h0m0s'
kubelet-arg:
  - 'container-log-max-files=10'
  - 'container-log-max-size=500Mi'

配置内容如下：

--disable=traefik — 关闭 K3s 内置的 traefik，后续配置 Ingress-Nginx Controller；
--flannel-backend=host-gw — 采用 host-gw 模式以提高性能；
--kube-apiserver-arg 'service-node-port-range=80-32767' — 将 NodePort 的端口范围扩大到 80 端口（目的是便于直接给 Nginx Ingress 使用服务器的 80、443 端口，否则 Ingress 必须使用 3xxxx 的 NodePort 端口，无法正确设置 Forwarded 头且使用上不直观）；
--kube-apiserver-arg 'event-ttl=168h0m0s' — 事件保留时间（默认为 1h）；
--kubelet-arg 'container-log-max-files=10' — 容器日志文件保留个数；
--kubelet-arg 'container-log-max-size=500Mi' — 容器单个日志文件的大小。

其中后三条配置均是为了保留更多的事件、日志信息，若 K3s 仅做测试使用时可以不进行配置。

如果需要使用外部数据库（如 MySQL）来实现高可用安装，相关配置亦定义在该文件中。参考：使用外部数据库实现高可用安装 | Rancher文档

注意，并不是引入了外部数据库搭建了高可用集群，所以并不建议盲目引入外部数据库来增加部署的复杂度。高可用集群需要至少两个 Server 节点，并通过负载均衡或其他技术对外暴露固定的 Registry 地址。

参考：

K3s Server 配置参考 | Rancher文档
kube-apiserver | Kubernetes
kubelet | Kubernetes

安装 K3s

安装命令（国内加速）

curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn sh -

安装命令中指定使用了中国国内的镜像站点来下载安装脚本和二进制文件。

参考：快速入门指南 | Rancher文档

离线安装

若环境完全断网，则可以使用离线安装。具体步骤如下：

保存 https://rancher-mirror.rancher.cn/k3s/k3s-install.sh 的安装脚本并将其上传到环境；
从 K3s GitHub Release 页面获取你所运行的 K3s 版本的二进制文件，并将其放置在 /usr/local/bin；
通过以下安装命令进行安装：

INSTALL_K3S_SKIP_DOWNLOAD=true ./install.sh

参考：离线安装 | Rancher文档

检查 K3s 运行状态并获取 kubeconfig

# 检查 K3s 运行状态
systemctl status k3s
kubectl get node
# 打印 kubeconfig
cat /etc/rancher/k3s/k3s.yaml

打印的 kubeconfig 无法直接使用，需调整输出中的 clusters.cluster[].server ，将 127.0.0.1 替换为实际的 IP 后才可导入 Lens 等工具。

升级 K3s

在 K3s 集群规模较小的情况下可以通过“安装脚本”升级 K3s。参考：基础升级 | Rancher文档

对应的升级命令与安装命令相同，使用相同的标志重新运行安装脚本即可。

可以通过环境变量 INSTALL_K3S_CHANNEL 指定特定的 Channel 或通过环境变量 INSTALL_K3S_VERSION 指定具体的版本，否则将默认升级到稳定 channel 的较新版本。

根据文档中的指引，升级时，先逐个升级 server 节点，然后再升级其他 agent 节点。

大型集群的升级则应该使用自动升级 | Rancher文档。

后续操作

按需添加 Worker / agent 节点

搭建 Worker 节点的安装命令与 Server 节点的安装命令类似，仅需增加环境变量 K3S_URL 和 K3S_TOKEN 即可。

其中 K3S_URL 即 Server 节点的 Registry 地址，而 K3S_TOKEN 的值则是从 Server 节点的 /var/lib/rancher/k3s/server/node-token 中获取。

完整的 Worker 节点安装命令如下：

curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn K3S_URL=https://<Server Node>:6443 K3S_TOKEN=<Node Token> sh -

注意，不要在 Worker 节点上放置 Server 节点所使用的 config.yaml。虽然Worker 节点亦支持使用“CONFIG 配置文件”，但其具体的配置项与 Server 节点是不同的，请参考：K3s Agent配置参考 | Rancher文档了解更多。

如果是离线安装，对应的 Worker 节点安装命令为：

INSTALL_K3S_SKIP_DOWNLOAD=true K3S_URL=https://<Server Node>:6443 K3S_TOKEN=<Node Token> ./install.sh

备份 Server Token

从 /var/lib/rancher/k3s/server/token 中获取 Server Token 并妥善保存，因为从备份恢复和添加节点时都需要它。

注意，此处备份的是 Server Token，而非添加 Worker 时使用的 Node Token。

配置 Ingress-Nginx Controller

在 K8s 上搭建 Nginx Ingress