K3s on IT 运维小秋

k3s合集

chenwx716@139.com — Thu, 12 Mar 2026 12:30:00 +0800

k3s

特点

资源需求低
裁减了很多非核心功能

https://k3s.io/
https://github.com/k3s-io/k3s/
https://docs.k3s.io/
https://docs.k3s.io/installation/configuration

注解

sqlite3 作为默认存储后端, 也支持 etcd3, MySQL 和 Postgres
区分控制面(server), 工作节点(agent)

内置组件

containerd
内置 Flannel cni
Traefik Ingress controller
ServiceLB Load-Balancer controller
Kube-router Network Policy controller
Local-path-provisioner Persistent Volume controller
Spegel distributed container image registry mirror, 仓库镜像
Host utilities (iptables, socat, etc)

组件

servicelb

支持 service LoadBalancer

原理:

在集群的每个节点上, 自动创建一个 DaemonSet 类型, 名为 svc- 的 Pod,
这个 pod 会生成 iptable 规则, 将外部发往节点特定端口的流量, 转发给实际提供服务的应用 Pod
pod 也带健康检查, 动态调节规则;

两种工作模式, 会根据节点配置自动选择

外部 IP 模式(推荐):

如果节点配置了外部 IP(如云服务器的公网 IP),
ServiceLB 会直接使用该 IP 作为服务的 EXTERNAL-IP;
外部流量直接到达节点的物理网卡, 然后被转发
内部 IP 模式:
如果节点没有配置外部 IP(如纯内网环境), ServiceLB 会退而使用节点的内网 IP;
外部流量需要先经过 NAT(网络地址转换)才能到达节点

cni

Flannel VXLAN
Flannel WireGuard

部署

常用部署环境变量

# 安装时跳过下载镜像, 离线安装
INSTALL_K3S_SKIP_DOWNLOAD=true

# 当没跳过二进制程序安装时，指定k3s版本安装的版本，默认为最新版
INSTALL_K3S_VERSION=v1.18.6-k3s1

# k3s二进制程序所在路径
INSTALL_K3S_BIN_DIR=/usr/local/bin

# 指定k3s server地址, 用于注册agent节点
K3S_URL=https://xxx:6443

# 设置k3s启动参数，当K3S_URL未设置时，默认为server, 反之为agent
# 对应server节点系统程序为 k3s
# 对应agent节点系统程序为 k3s-agent
INSTALL_K3S_EXEC="server"

# 从文件中获取k3s启动参数, 默认为 /etc/rancher/k3s/config.yaml
# 该参数用于替代INSTALL_K3S_EXEC变量，该变量在v1.19.1-k3s1+版本支持
# 参考文档: https://docs.k3s.io/installation/configuration
K3S_CONFIG_FILE=xxx

# 启动参数为server时, 指定server的token，token存放路径为/var/lib/rancher/k3s/server/node-token
# 启动参数为agent时, 指定连接server的token
K3S_TOKEN=xxx

# 和K3S_TOKEN作用一致，区别在于该参数会从文件地区token
K3S_TOKEN_FILE=xxx

启动参数

server启动参数

在 INSTALL_K3S_EXEC 变量中指定server启动参数,
例如INSTALL_K3S_EXEC=“server xxx”, 多个参数使用空格分隔

# 初始化集群
--cluster-init

# k3s数据持久化目录, 默认为 /var/lib/rancher/k3s
--data-dir /var/lib/rancher/k3s

# 安装k3s集群时禁止部署的服务
# 可以为coredns、servicelb、traefik、local-storage、metrics-server
--disable traefik

# 关闭ccm
--disable-cloud-controller

# 指定apiserver参数, 多个参数指定多次
--kube-apiserver-arg  

# 指定scheduler参数, 多个参数指定多次
--kube-scheduler-arg key=value

# 指定controller-manager参数, 多个参数指定多次
--kube-controller-manager-arg key=value

# 指定kubelet参数, 多个参数指定多次
--kubelet-arg key=value

# flannel网络配置, 可以为vxlan或host-gw, 默认为vxlan
--flannel-backend=vxlan

# 集群网络划分
--cluster-cidr=10.42.0.0/16
--service-cidr=10.43.0.0/16

# 指定etcd快照策略
--etcd-snapshot-schedule-cron='10 0 1-31 1-12 0-6'

agent 启动参数

# k3s数据持久化目录, 默认为/var/lib/rancher/k3s
--data-dir /var/lib/rancher/k3s

# 指定kubelet参数, 多个参数指定多次
--kubelet-arg key=value

自动部署

systemctl disable firewalld --now
# or
firewall-cmd --permanent --add-port=6443/tcp #apiserver
firewall-cmd --permanent --zone=trusted --add-source=10.42.0.0/16 #pods
firewall-cmd --permanent --zone=trusted --add-source=10.43.0.0/16 #services
firewall-cmd --reload

curl -sfL https://get.k3s.io | sh -

# 查看节点1
sudo k3s kubectl get node

# 可以先导出脚本
# curl https://get.k3s.io > install-k3s.sh

# 初始化参数

curl -fL https://get.k3s.io | sh -s - server \
    --node-ip=192.168.80.10 \
    --flannel-backend none \     # 关闭 flannel
    --disable-cloud-controller
    --cluster-init \
    --node-external-ip=192.168.80.80 \
    --disable-kube-proxy \
    --disable-network-policy \
    --disable-helm-controller \
    # 选择性禁用组件
    --disable=traefik,local-storage,metrics-server,servicelb,coredns
    --token                     # 固定后续节点加入的token

# 国内环境安装 k3s
INSTALL_K3S_MIRROR=cn curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | sh -s - server \
  --disable-cloud-controller \
  --disable-network-policy \
  --disable-helm-controller \
  --disable=traefik,local-storage,metrics-server \
  --system-default-registry=registry.cn-hangzhou.aliyuncs.com

# 获取随机产生的 K3S_TOKEN: /var/lib/rancher/k3s/server/node-token

新节点加入集群

curl -sfL https://get.k3s.io | K3S_URL=https://myserver:6443 K3S_TOKEN=mynodetoken sh -

curl -sfL https://get.k3s.io | \
  K3S_TOKEN=${NODE_TOKEN} sh -s - agent \
  --server https://192.168.80.80:6443 \
  --node-ip=${WORKER_ADDR} \            # 固定节点ip - 多网卡或多ip时
  --node-external-ip=${WORKER_ADDR}     # 固定外部ip

离线安装

# 下载安装脚本
curl -o install.sh https://get.k3s.io

# 准备 cli 和 镜像压缩包 github
k3s
k3s-airgap-images-amd64.tar


# 预加载镜像
sudo mkdir -p /var/lib/rancher/k3s/agent/images/
sudo cp ./k3s-airgap-images-amd64.tar /var/lib/rancher/k3s/agent/images/

chmod +x k3s
cp k3s /usr/local/bin/

# 执行安装脚本
chmod +x install.sh
INSTALL_K3S_SKIP_DOWNLOAD=true ./install.sh

systemctl status k3s
journalctl -u k3s -f

k3s kubectl get node

# 导出 kubeconfig
k3s kubectl config view --raw > k3s

k3s目录结构

# 连接k3s集群的认证文件 kubeconfig
/etc/rancher/k3s/k3s.yaml

# k3s在启动之后会部署的清单文件目录，可以提前创建该目录并将需要部署的应用放置其中
# 当k3s启动或文件修改时间出现变化时就会重新apply改目录下资源清单
/var/lib/rancher/k3s/server/manifests

# k3s server的token信息
/var/lib/rancher/k3s/server/node-token

# k3s证书目录
/var/lib/rancher/k3s/server/tls

# k3s containerd配置文件
/var/lib/rancher/k3s/agent/etc/containerd

# k3s cni网络接口配置文件
/var/lib/rancher/k3s/agent/etc/cni/

# k3s flannel配置文件
/var/lib/rancher/k3s/agent/etc/flannel/

k3s 管理 cli

# 检查k3s启动状态
k3s kubectl get pod -n kube-system

# 管理容器
k3s ctr
k3s ctr version
k3s ctr i ls -q

crictl rmi --prune  # 清理镜像

进入对应容器

# 获取 pid, 查看 pid 对应containerd的task
k3s ctr t ls | grep 25101

# 通过task id进入容器
k3s ctr t exec --exec-id xxxxx TASKID /bin/sh

升级 k3s

下载新的 k3s 二进制程序和安装脚本
替换当前的 k3s 二进制程序和安装脚本
使用相同的环境变量重新执行安装脚本即可
升级时一次升级一个 server 节点, 然后升级所有 agent 节点

简单办法就是将下载的二进制文件替换旧文件, 先停后启;

k3s 存储

k3s 集群默认提供了 local-path 作为 storageclass 来进行持久化存储;
该 storageclass 由系统名称空间的 deploy 资源 local-path-provisioner 进行控制

k3s网络

提供了klipper-lb用于实现LoadBalancer访问

一个集群中LoadBalancer的port端口唯一不可重复

延长证书有效期

创建 /etc/default/k3s 文件

`1`	`CATTLE_NEW_SIGNED_CERT_EXPIRATION_DAYS=3650`

手动触发证书轮转并重启

1
2

k3s certificate rotate
systemctl restart k3s

备份恢复

自动备份机制

k3s内置etcd集群的快照目录默认为k3s数据目录下的/server/db/snapshots,
默认每12小时进行一次备份, 部署时通过k3s参数–etcd-disable-snapshots来指定备份策略

1
2
3

INSTALL_K3S_EXEC="server \
--etcd-disable-snapshots=true \
--etcd-snapshot-schedule-cron='0 */5 * * *'"

手动备份

ETCDCTL_ENDPOINTS='https://127.0.0.1:2379' \
ETCDCTL_CACERT='/var/lib/rancher/k3s/server/tls/etcd/server-ca.crt' \
ETCDCTL_CERT='/var/lib/rancher/k3s/server/tls/etcd/server-client.crt' \
ETCDCTL_KEY='/var/lib/rancher/k3s/server/tls/etcd/server-client.key' \
ETCDCTL_API=3 \
./etcdctl snapshot save /tmp/mysnapshot.db

恢复数据

恢复数据时需要指定集群之前的token, 同时需要指定所有启动参数,
将下面命令中的 –WITH-OTHER-ARGS 修改为对应的启动参数,
启动参数中需要去除 cluster-init 或 –cluster

k3s server \
--cluster-reset \
--cluster-reset-restore-path=/tmp/mysnapshot.db \
--WITH-OTHER-ARGS \
--token=mastergo

systemctl restart k3s

k3s混合云组网

chenwx716@139.com — Thu, 12 Mar 2026 12:30:00 +0800

k3s混合云组网
- k3s_WireGuard
  - Agent 安装
- Tailscale网络
  - 安装并配置 Tailscale
  - 部署 K3s 集群

k3s混合云组网

K3s 有两种主要方案来满足混合云和多云环境的需求:

嵌入式 k3s 多云解决方案
与 Tailscale VPN 集成

多云场景下, 节点之间的延迟会变高; 延迟太高会降低网络性能, 还可能影响集群的运行;
此类部署不支持嵌入式 etcd; 如果使用嵌入式 etcd, 所有 Server 节点必须通过其私有 IP 相互访问;
Agent 可能分布在多个网络上, 但所有 server 都应该位于同一位置;

k3s_WireGuard

部署 WireGuard, wg 网段设置为 192.168.1.x
基于 vpn 通道部署 k3s

curl -sfL http://rancher-mirror.cnrancher.com/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn \
  sh -s -  --node-external-ip 42.xx.xx.12 \
  --advertise-address 42.xx.xx.12 \
  --node-ip 192.168.1.1 \
  --flannel-iface wg0

systemctl status k3s
kubectl get pods -A

Agent 安装

curl -sfL http://rancher-mirror.cnrancher.com/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn \
  K3S_URL=https://192.168.1.1:6443 \
  K3S_TOKEN=K107xxxxxxxxxxxxxxxx2cf95048d6a3cd85f15717edfbe5::server:xxxxxxxxxxxxxxxxxxxx4da1b7e701f67e sh -s - \
  --node-external-ip 122.xx.xxx.111 \
  --node-ip 192.168.1.2 --flannel-iface wg0

systemctl status k3s-agent

K3S_Token 去 cat /var/lib/rancher/k3s/server/node-token 获取即可
K3S_URL 需要设置 master 的通信地址端口, 端口默认是 6443, IP 地址就是虚拟网域的 IP
node-external-ip 为节点公网地址
node-ip 节点虚拟 IP 地址

1
2
3

kubectl get nodes -o wide

k3s kubectl get node

Tailscale网络

Tailscale 作为 saas 服务商, 各节点通过它组成了一个 vpn 网络;
并通过 vpn 网络进行通信; 于是 k3s 集群并没有在公网暴露任何端口

本地局域网的一个虚拟机作为 K3s server 节点(K3s1),
阿里云(izwz9eox9l8h9wh9bazd2hz)和 AWS(ip-172-31-7-7) 的两台实例分别作为 agent 节点

安装并配置 Tailscale

登录到你的 Tailscale 帐户
在 Settings > Keys 中, 生成一个授权密钥($AUTH-KEY), 它可以被集群中的所有节点重复使用:

本例获取的 AUTH-KEY 为: tskey-auth-kfZp9F4CNTRL-Kj3sqcKW4i7zY3cCq2q7h7uhXitJutpY

定义 K3s 集群使用的 pod CIDR(默认 10.42.0.0/16)网络策略;
在 Access Controls 中附加 CIDR(或双栈的 CIDR)

"autoApprovers": {
        "routes": {
            "10.42.0.0/16":        ["kingsd041@xxx.com"],
            // "2001:cafe:42:0::/56": ["your_account@xyz.com"],
        },
    },

在每个节点中安装 Tailscale
curl -fsSL https://tailscale.com/install.sh | sh

部署 K3s 集群

要部署启用了 Tailscale 集成的 K3s, 必须在每个节点上添加以下参数
–vpn-auth=“name=tailscale,joinKey=$AUTH-KEY

1
2
3


curl -sfL https://get.k3s.io | sh -s - \
    --vpn-auth="name=tailscale,joinKey=tskey-auth-kfZp9F4CNTRL-Kj3sqcKW4i7zY3cCq2q7h7uhXitJutpY"

安装成功后, 会自动将该节点注册到 Tailscale 中
并在 Tailscale 中生成一个可用于 VPN 网络内访问的 IP 地址: 例如 100.105.190.87
在注册 agent 节点时, 就可以通过 Tailscale 提供的 100.105.190.87 作为 K3s server 节点 IP 去注册

curl -sfL https://get.k3s.io | \
    K3S_URL=https://100.105.190.87:6443 \
    K3S_TOKEN=mynodetoken sh -s - \
    --vpn-auth="name=tailscale,joinKey=tskey-auth-kfZp9F4CNTRL-Kj3sqcKW4i7zY3cCq2q7h7uhXitJutpY"

三个节点之间可以通过 Tailscale 提供的 100. 开头的 IP 地址进行相互通信

也可以通过 Tailscale 提供的私有网络来访问 K3s 集群