Notebook

K3s - 轻量级 Kubernetes

@@ Tags: Kubernetes;K3s
@@ Date: 2025-11-04

K3s 快速开始

K3s 是轻量级的 Kubernetes。K3s 易于安装，仅需要 Kubernetes 内存的一半，所有组件都在一个小于 100 MB 的二进制文件中。

K3s 是一个完全兼容的 Kubernetes 发行版，具有以下增强功能：

打包为单个二进制文件。
使用基于 sqlite3 作为默认存储机制的轻量级存储后端。同时支持使用 etcd3、MySQL 和 Postgres。
封装在简单的启动程序中，可以处理很多复杂的 TLS 和选项。
默认情况下是安全的，对轻量级环境有合理的默认值。
添加了简单但强大的 batteries-included 功能
所有 Kubernetes control plane 组件的操作都封装在单个二进制文件和进程中。因此，K3s 支持自动化和管理复杂的集群操作（例如证书分发等）。
最大程度减轻了外部依赖性，K3s 仅需要现代内核和 cgroup 挂载。K3s 打包了所需的依赖

安装

建议安装需求

仅 Linux
CPU 2 cores(最小 1)
RAM 1 GB(最小 512MB)

安装 Server 节点

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

# 查看 node token
sudo cat /var/lib/rancher/k3s/server/node-token

K3s 服务将被配置为在节点重启后或进程崩溃或被杀死时自动重启。
将安装其他实用程序，包括 kubectl、crictl、ctr、k3s-killall.sh 和 k3s-uninstall.sh。
kubeconfig 文件将写入到 /etc/rancher/k3s/k3s.yaml，由 K3s 安装的 kubectl 将自动使用该文件。

安装 Agent 节点并将它们添加到集群

curl -sfL https://get.k3s.io | K3S_URL=https://myserver:6443 K3S_TOKEN=mynodetoken sh -
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn K3S_URL=https://myserver:6443 K3S_TOKEN=mynodetoken sh -

K3S_URL 参数会导致安装程序将 K3s 配置为 Agent 而不是 Server。K3s Agent 将注册到在 URL 上监听的 K3s Server。K3S_TOKEN 使用的值存储在 Server 节点上的 /var/lib/rancher/k3s/server/node-token 中。

备注

每台主机必须具有唯一的主机名。如果你的计算机没有唯一的主机名，请传递 K3S_NODE_NAME 环境变量，并为每个节点提供一个有效且唯一的主机名。

# 查看服务的日志
sudo journalctl -u k3s -n 100 --no-pager
sudo journalctl -u k3s-agent -n 100 --no-pager


# 拉取镜像
sudo k3s ctr image pull docker.io/rancher/mirrored-pause:3.6

管理集群

# Server 节点执行
# 拷贝 k3s.yaml 到用户目录, 并修改权限
sudo cp /etc/rancher/k3s/k3s.yaml ~/
sudo chown $USER:$USER ~/k3s.yaml

# 远程管理机器执行
# 将 kk3s.yaml 拷贝到本地 ~/.kube/config
mkidr ~\.kube
scp user@server_ip:~/k3s.yaml ~\.kube\config
# 修改 config 文件的server字段到节点地址, 如下所示：
nano ~\.kube\config

# kubeconfig 配置文件
# 来自: /etc/rancher/k3s/k3s.yaml
apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: # CA 证书（Base64编码
    LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUJkekNDQVIyZ0F3SUJBZ0lCQURBS0JnZ3Foa2pPUFFRREFqQWpNU0V3SHdZRFZRUUREQmhyTTNNdGMyVnk
    ....
    NFUlRJRklDQVRFLS0tLS0K
    server: https://192.168.3.225:6443  # API Server 端点
  name: default                         # 集群名称
contexts:
- context:
    cluster: default
    user: default
  name: default
current-context: default
kind: Config
preferences: {}
users:
- name: default               # 用户名称
  user:
    client-certificate-data:  # 客户端证书数据
    LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUJrRENDQVRlZ0F3SUJBZ0lJWjYxeldWcHVhSVl3Q2dZSUtvWkl6ajBFQXdJd0l6RWhNQjhHQTFVRUF3d1k
    ....
    V09UUzQ0WXcySXZERzFVN3BWdW95Zm5rdWd4UFd6V29DS0t3QT09Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K
    client-key-data:          # 客户端密钥数据
    LS0tLS1CRUdJTiBFQyBQUklWQVRFIEtFWS0tLS0tCk1IY0NBUUVFSU9UeHVicGVIcXYvd3J1VzNxU25KUVhrbXQwK3JGR1F3T3ZKMm1wRFZRR3FvQW9HQ0NxR1NNNDkKQXdFSG9VUURRZ0FFSWFLakNNNzFOK3UyNDRKcGZYSGY4Wm9Bekw4Q1RwaVV0Z1QxUk5hMmpxRzk1MTdSTDg2ZwpINjE1T3htc2tWQ3JrRmVzUi9rT0dIQW1zTTZNbXM1ZTNRPT0KLS0tLS1FTkQgRUMgUFJJVkFURSBLRVktLS0tLQo=

server 节点生成　/etc/rancher/k3s/k3s.yaml 的主要目的:

让管理员能够在 Server 节点本机上使用 kubectl 管理整个 K3s 集群

集群管理员身份凭证:　这个 k3s.yaml 包含了最高权限的认证凭证

作为其他管理配置的基准

此时可以使用 kubectl 命令来管理集群。

# 测试集群连接
kubectl cluster-info

# 查看节点
kubectl get nodes

# 查看所有 pods
kubectl get pods -A
kubectl get pods -A -o wide

# 查询所有的 ingress
kubectl get ingress -A

# 查看所有服务的状态
kubectl get svc -A -o wide

# 查看所有 namespace=kube-system 的pods详细信息
kubectl describe pod -n kube-system

# 查看 pods traefik-c98fdf6fb-629q2 的状态 (tail)
kubectl logs traefik-c98fdf6fb-629q2 -n kube-system -f

# 查看所有节点的状态
kubectl top node

# 删除单个失败的 Pod
kubectl delete pod <pod-name>

# 删除所有失败的 Pod
kubectl delete pods --field-selector=status.phase=Failed

# 删除所有状态不是 Running 的 Pod（谨慎使用）
kubectl delete pods --field-selector=status.phase!=Running

# 查看所有 configmap(配置数据)
kubectl.exe get configmap -A

# 查看所有 configmap 的内容
kubectl.exe get configmap traefik-conf -n kube-system -o yaml

# 通过重启 Pod, 可以清理日志
kubectl rollout restart deployment/traefik -n kube-system

# 删除 Pod 迫使其重建（如果是 Deployment 管理的）
kubectl delete pod traefik-c98fdf6fb-629q2 -n kube-system

# 查看节点, 标签
kubectl get nodes --show-labels

# 设置节点标签
kubectl label nodes <node-name> node-type=worker

# 添加标准的 worker 角色
kubectl label node <node-name> node-role.kubernetes.io/worker=true

POD 状态

ContainerCreating
容器创建中
Running
正在运行
Completed
已完成
ErrImagePull
镜像拉取失败, 镜像仓库异常
ImagePullBackOff
镜像拉取失败, 可能是镜像不存在, 镜像仓库异常
CrashLoopBackOff
容器启动后崩溃
CreateContainerConfigBackOff
创建容器配置失败, 例如，引用了不存在的 Secret 或 ConfigMap。
Error
容器启动失败
Terminating
终止状态, 可能节点失联

配置

server 配置文件位于 /etc/rancher/k3s/config.yaml, 字段内容参考官方文档;

也支持多个配置文件。

默认情况下，配置文件/etc/rancher/k3s/config.yaml按/etc/rancher/k3s/config.yaml.d/*.yaml字母顺序读取。

服务角色管理

启动 K3s 服务器--cluster-init将运行所有控制平面组件，包括 API 服务器、控制器管理器、调度器和 etcd。可以禁用特定组件，以便将控制平面和 etcd 角色拆分到不同的节点上。

比如创建专用etcd节点:

curl -fL https://get.k3s.io | sh -s - server --cluster-init --disable-apiserver --disable-controller-manager --disable-scheduler

集群数据存储

K3s 支持以下数据存储选项：

嵌入式SQLite
- SQLite 无法在多服务器集群中使用
- 是默认数据存储，当没有其他数据存储配置且磁盘上不存在嵌入式 etcd 数据库文件时，将使用 SQLite。
- 位于: /var/lib/rancher/k3s/server/db/
嵌入式 etcd
有关在多台服务器上使用嵌入式 etcd 的更多信息，请参阅高可用性嵌入式 etcd文档。如果 K3s 配置为初始化新的 etcd 集群、加入现有 etcd 集群，或者在启动期间磁盘上存在 etcd 数据库文件，则会自动选择嵌入式 etcd。

备份恢复

除了备份数据存储本身之外，您还必须备份服务器令牌文件/var/lib/rancher/k3s/server/token。如果在恢复时未使用相同的令牌值，则快照将无法使用，因为该令牌用于加密数据存储中的机密数据。

手动导入镜像

镜像可以被手动导入, 通过运行 ctr -n k8s.io image pull 命令来拉取镜像(嵌入的注册表)，或者通过使用 ctr -n k8s.io import 或 ctr -n k8s.io load 命令加载镜像归档文件。注意，k8s.io命名空间必须指定，以便在ctr中管理镜像时，kubelet可以识别这些镜像。

集群架构

K3s Architecture

K3s 集群架构大概分为两种:

单服务器架构，内置数据库
高可用性, 多服务器架构, 嵌入式 etcd 数据存储, 节点通常建议使用奇数个（如3个、5个），这是由底层etcd的Raft共识算法决定的，可以有效避免“脑裂”问题。

参考

嵌入式注册表镜像

K3s 内置了Spegel，这是一个无状态的分布式 OCI 镜像仓库，允许 Kubernetes 集群中的节点之间进行容器镜像的对等共享。该分布式镜像仓库默认处于禁用状态。

启动时，K3s 会检查该文件是否/etc/rancher/k3s/registries.yaml存在。如果存在，则会在生成 containerd 配置时使用此文件中的注册表配置。

如果您想使用私有注册表作为公共注册表（例如 docker.io）的镜像，则需要registries.yaml在每个要使用该镜像的节点上进行配置。
如果您的私有镜像仓库需要身份验证、使用自定义 TLS 证书或不使用 TLS，则需要 registries.yaml 在每个拉取镜像的节点上进行配置。

registries.yaml 文件的格式如下：

mirrors:
  <REGISTRY>:
    endpoint:
      - https://<REGISTRY>/v2
configs:
  <REGISTRY>:
    auth:
      username: <BASIC AUTH USERNAME>
      password: <BASIC AUTH PASSWORD>
      token: <BEARER TOKEN>
    tls:
      ca_file: <PATH TO SERVER CA>
      cert_file: <PATH TO CLIENT CERT>
      key_file: <PATH TO CLIENT KEY>
      insecure_skip_verify: <SKIP TLS CERT VERIFICATION BOOLEAN>

示例(国内镜像)：

mirrors:
  docker.io:
    endpoint:
      - "https://docker.1ms.run/"
      - "https://docker.xuanyuan.me/"

mirrors:
  "docker.io":
    endpoint:
      - "https://registry-1.docker.io"

重启后应用, 然后可以查看日志检查是否成功应用

sudo systemctl restart k3s
sudo systemctl restart k3s-agent
sudo systemctl status k3s-agent

与 containerd 配置

k3s 默认使用containerd，需要修改containerd的配置文件，才能让Pod的镜像使用镜像加速器。

K3s会自动生成containerd的配置文件/var/lib/rancher/k3s/agent/etc/containerd/config.toml,不要直接修改这个文件，k3s重启后修改会丢失。

$ sudo cat /var/lib/rancher/k3s/agent/etc/containerd/config.toml
# File generated by k3s. DO NOT EDIT. Use config.toml.tmpl instead.
version = 3
root = "/var/lib/rancher/k3s/agent/containerd"
state = "/run/k3s/containerd"
# ...
[plugins.'io.containerd.cri.v1.images'.registry]
  config_path = "/var/lib/rancher/k3s/agent/etc/containerd/certs.d"

$ sudo cat /var/lib/rancher/k3s/agent/etc/containerd/certs.d/docker.io/hosts.toml
# File generated by k3s. DO NOT EDIT.
server = "https://registry-1.docker.io/v2"
capabilities = ["pull", "resolve", "push"]

[host]

[host."https://docker.1ms.run/v2"]
  capabilities = ["pull", "resolve"]

[host."https://docker.xuanyuan.me/v2"]
  capabilities = ["pull", "resolve"]

OCI 镜像仓库

OCI 镜像仓库是一个用于存储和分发符合 OCI（开放容器倡议）规范的容器镜像及其他制品的系统。其核心目标是实现标准化，确保镜像在不同的容器运行时（如 Docker、Podman、containerd、CRI-O）和客户端（如 Helm、Nerdctl、oras）之间能够自由分发和运行，避免兼容性问题。

etcd

etcd是一个强一致性的分布式键值存储系统，它为分布式系统或集群中需要访问的数据提供了一种可靠的存储方式。它能够优雅地处理网络分区期间的领导者选举，并且即使在领导者节点上发生故障，也能容忍机器故障。

脑裂问题

在分布式系统中，脑裂指的是：原本应该协同工作的一个集群，由于网络故障被分割成两个或多个无法通信的子集群，每个子集群都认为自己是“唯一存活”的部分，并继续对外提供服务，从而导致数据不一致和系统混乱。

crictl

crictl 是 Kubernetes 节点上的容器运行时命令行工具，主要用于与 CRI（Container Runtime Interface）兼容的容器运行时进行交互。

命令行语法与docker 命令行语法相似，但有些命令可能不同。

# 查看 Pod 列表
sudo crictl pods

# 查看容器列表
sudo crictl ps

# 查看镜像列表
sudo crictl images

# 查看容器状态
sudo crictl inspect <container-id>

# 查看 Pod 状态
sudo crictl inspectp <pod-id>

ctr

ctr 是 containerd 的命令行工具，用于与 containerd 进行交互。

# 查看镜像列表
sudo ctr images list

# 拉取镜像
sudo ctr images pull docker.io/library/nginx:latest

# 删除镜像
sudo ctr images rm docker.io/library/nginx:latest

# 查看容器列表
sudo ctr containers list

# 查看任务列表（运行的容器）
sudo ctr tasks list

# 在容器中执行命令
sudo ctr tasks exec --exec-id $RANDOM -t <container-id> /bin/sh

# 查看命名空间
sudo ctr namespaces list

K3s - 轻量级 Kubernetes

安装

管理集群

POD 状态

配置

服务角色管理

集群数据存储

备份恢复

手动导入镜像

集群架构

参考

嵌入式注册表镜像

与 containerd 配置

OCI 镜像仓库

etcd

脑裂问题

crictl

ctr

Read next

STM32 定时器

STM32 GPIO

STM32 基础

Comments ()

安装

管理集群

POD 状态

配置

服务角色管理

集群数据存储

备份恢复

手动导入镜像

集群架构

参考

嵌入式注册表镜像

与 containerd 配置

OCI 镜像仓库

etcd

脑裂问题

crictl

ctr

Read next

Comments ( )

Comments ()