使用 K3s 安装 Kubernetes
在 Debian 或 Ubuntu 上安装 K3s,使用 kubectl,部署第一个应用,添加节点并保护集群端口。
本页内容
您的参数
只需填写一次,指南中的命令会自动更新。
K3s 是一个轻量级且经过认证的 Kubernetes 发行版,以单个二进制文件的形式分发。它非常适合 VPS 或专用服务器:内置 kubectl、Traefik Ingress 控制器、简单的负载均衡器和本地存储。
本指南将带您在 Debian 12/13 或 Ubuntu 22.04/24.04 上,从安装一直到搭建出双节点集群:
- 安装服务器节点;
- 在不暴露 API 的情况下使用
kubectl; - 部署第一个应用;
- 添加代理节点;
- 更新并备份集群。
订购服务器
为了托管您的集群,HostMyServers 提供多种方案:
前提条件
| 角色 | 最低 CPU | 最低内存 |
|---|---|---|
| 服务器 | 2 核 | 2 GB |
| 代理 | 1 核 | 512 MB |
这些数值来自 K3s 文档,不包含您的应用所需的资源。
您还需要:
- 拥有
sudo权限的用户的 SSH 访问; - 每个节点使用不同的主机名;
- 其他节点可以访问的 IP 地址,通常是公网 IP 地址;
- 如果节点之间通过互联网通信,需要 WireGuard 内核模块。
在每个节点上检查 WireGuard 是否存在:
sudo modprobe wireguard && lsmod | grep wireguard端口
| 端口 | 协议 | 来源 | 用途 |
|---|---|---|---|
| 22 | TCP | 您的电脑 | SSH 及通往 API 的隧道 |
| 6443 | TCP | 代理节点 | Kubernetes API 和 K3s supervisor |
| 10250 | TCP | 所有节点 | kubelet 指标与 API |
| 51820 | UDP | 所有节点 | IPv4 下的 Flannel WireGuard |
| 51821 | UDP | 所有节点 | IPv6 下的 Flannel WireGuard(如使用) |
| 80, 443 | TCP | 互联网 | 由 Traefik 发布的应用 |
准备服务器
sudo apt update
sudo apt upgrade -y
sudo apt install -y curl ufwK3s 文档建议禁用 UFW,但暴露在互联网上的服务器仍应保持过滤。如果像这里一样保留 UFW,就必须放行 K3s 的内部网络。如果您使用其他 SSH 端口,请替换 22:
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp
sudo ufw allow 80,443/tcp
sudo ufw allow from 10.42.0.0/16 to any
sudo ufw allow from 10.43.0.0/16 to any
sudo ufw enable10.42.0.0/16 是默认的 Pod 网络,10.43.0.0/16 是默认的服务网络。
安装服务器节点
请在安装之前准备好配置。这样集群网络从一开始就是加密的,以后就可以通过互联网添加节点。
sudo mkdir -p /etc/rancher/k3s
sudo nano /etc/rancher/k3s/config.yamlnode-external-ip: 您的服务器IP
flannel-backend: wireguard-native
flannel-external-ip: true
tls-san:
- 您的服务器IP然后使用官方脚本安装 K3s,该脚本默认跟随 stable 通道:
curl -sfL https://get.k3s.io | sh -检查服务和节点。节点变为 Ready 状态可能需要一分钟:
sudo systemctl status k3s --no-pager
sudo k3s kubectl get nodes -o wide
sudo k3s kubectl get pods -A使用 kubectl
文件 /etc/rancher/k3s/k3s.yaml 提供对集群的完整管理员权限,且只有 root 能读取。请勿将其设为所有人可读。请改为创建一份个人副本:
mkdir -p ~/.kube
install -m 600 /dev/null ~/.kube/config
sudo k3s kubectl config view --raw > ~/.kube/config
echo 'export KUBECONFIG="$HOME/.kube/config"' >> ~/.bashrc
export KUBECONFIG="$HOME/.kube/config"
kubectl get nodes在您的电脑上管理集群
使用 SSH 隧道可以避免向您的电脑开放 6443 端口。请在您的机器上安装 kubectl,然后复制配置:
mkdir -p ~/.kube
scp 您的用户名@您的服务器IP:.kube/config ~/.kube/k3s-hms
chmod 600 ~/.kube/k3s-hms
ssh -N -L 6443:127.0.0.1:6443 您的用户名@您的服务器IP保持该隧道打开,然后在另一个终端中执行:
export KUBECONFIG=~/.kube/k3s-hms
kubectl get nodesK3s 每次启动时都会更新其管理文件中的证书。如果您的副本不再可用,请重新复制。
部署第一个应用
创建一个清单文件:
nano demo.yamlapiVersion: v1
kind: Namespace
metadata:
name: demo
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: web
namespace: demo
spec:
replicas: 2
selector:
matchLabels:
app: web
template:
metadata:
labels:
app: web
spec:
containers:
- name: nginx
image: nginx:stable-alpine
ports:
- containerPort: 80
resources:
requests:
cpu: 50m
memory: 32Mi
limits:
memory: 128Mi
---
apiVersion: v1
kind: Service
metadata:
name: web
namespace: demo
spec:
selector:
app: web
ports:
- port: 80
targetPort: 80
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web
namespace: demo
spec:
ingressClassName: traefik
rules:
- host: demo.您的域名.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: web
port:
number: 80应用该清单并跟踪部署进度:
kubectl apply -f demo.yaml
kubectl -n demo rollout status deployment/web
kubectl -n demo get pods,svc,ingress即使 DNS 尚未配置,也可以在您自己的电脑上测试该应用:
curl -H 'Host: demo.您的域名.com' http://您的服务器IP/您应当得到 Nginx 的欢迎页面。
不再需要该示例时,请将其删除:
kubectl delete namespace demo添加代理节点
在本节中,代理节点IP 表示新节点的 IP 地址。
开放节点之间的流量
在服务器上:
sudo ufw allow from 代理节点IP to any port 6443 proto tcp
sudo ufw allow from 代理节点IP to any port 10250 proto tcp
sudo ufw allow from 代理节点IP to any port 51820 proto udp在代理上:
sudo apt update
sudo apt install -y curl ufw
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp
sudo ufw allow 80,443/tcp
sudo ufw allow from 10.42.0.0/16 to any
sudo ufw allow from 10.43.0.0/16 to any
sudo ufw allow from 您的服务器IP to any port 10250 proto tcp
sudo ufw allow from 您的服务器IP to any port 51820 proto udp
sudo ufw enable代理上需要开放 80 和 443 端口,因为 Traefik 可能会发布在每个节点上。如果节点超过两个,请在所有节点之间开放 10250/TCP 和 51820/UDP 端口。
加入集群
在服务器上,显示令牌:
sudo cat /var/lib/rancher/k3s/server/node-token在代理上,先声明其外部地址,然后启动安装。read 命令会等待您粘贴令牌,既不会显示令牌,也不会将其记录到历史记录中:
sudo mkdir -p /etc/rancher/k3s
echo 'node-external-ip: 代理节点IP' | sudo tee /etc/rancher/k3s/config.yaml
read -rs K3S_TOKEN
curl -sfL https://get.k3s.io | K3S_URL=https://您的服务器IP:6443 K3S_TOKEN="$K3S_TOKEN" sh -
unset K3S_TOKEN
sudo systemctl status k3s-agent --no-pager在服务器上,新节点应显示为 Ready 状态:
kubectl get nodes -o wide更新 K3s
请先备份集群并阅读发行说明。先逐台更新服务器,然后再更新代理,且不要跳过 Kubernetes 的次要版本。
在服务器上重新运行脚本。config.yaml 中的配置会被保留:
curl -sfL https://get.k3s.io | sh -在每个代理上,重新传入相同的变量:
read -rs K3S_TOKEN
curl -sfL https://get.k3s.io | K3S_URL=https://您的服务器IP:6443 K3S_TOKEN="$K3S_TOKEN" sh -
unset K3S_TOKEN如果您的集群落后了多个次要版本,请使用相应的通道分步升级,例如:
curl -sfL https://get.k3s.io | INSTALL_K3S_CHANNEL=v1.36 sh -然后使用 kubectl get nodes 检查版本。
备份与恢复
使用 SQLite 时,请同时备份数据库和服务器令牌:没有该令牌,备份就无法使用。停止 K3s 可保证复制的内容一致,并且不会停止已在运行的容器。
sudo systemctl stop k3s
sudo tar -czpf "/root/k3s-$(date +%F).tar.gz" /var/lib/rancher/k3s/server/db /var/lib/rancher/k3s/server/token /etc/rancher/k3s/config.yaml
sudo systemctl start k3s
sudo chmod 600 /root/k3s-*.tar.gz本地存储创建的卷位于 /var/lib/rancher/k3s/storage。也请备份它们,最好使用各个应用自带的工具,例如导出数据库。同时请将您的清单文件保存在私有 Git 仓库中。
在服务器上恢复数据库:
sudo systemctl stop k3s
sudo rm -rf /var/lib/rancher/k3s/server/db
sudo tar -xzpf /root/k3s-YYYY-MM-DD.tar.gz -C /
sudo systemctl start k3s
kubectl get nodes故障排查
Unable to read /etc/rancher/k3s/k3s.yaml
您的用户无权访问管理文件。请回到 使用 kubectl 一节,并检查 echo $KUBECONFIG。请避免使用 --write-kubeconfig-mode 644 将该文件设为所有人可读。
k3s 服务无法启动
sudo journalctl -u k3s -n 80 --no-pager
sudo k3s check-config如果日志中提到 WireGuard,请检查 sudo modprobe wireguard。在单节点集群上若该模块不可用,请在重新安装之前从 config.yaml 中删除 flannel-backend 和 flannel-external-ip。请勿在通过互联网连接的节点之间用 VXLAN 替代 WireGuard。
代理无法加入集群
sudo journalctl -u k3s-agent -n 80 --no-pager
curl -vk -m 5 https://您的服务器IP:6443/pingconnection refused或超时:检查 UFW 和K3S_URL的地址。token无效:重新复制node-token的内容。Node password rejected, duplicate hostname:另一个节点使用了相同的名称,或该节点已经注册过。请更改主机名,或使用kubectl delete node 节点名称删除旧节点。
某个节点一直处于 NotReady 状态
kubectl describe node 节点名称
ip link show flannel-wg请检查节点之间的 10250/TCP 和 51820/UDP 端口,以及 node-external-ip 的值。
Pod 一直处于 Pending 或 ImagePullBackOff 状态
kubectl -n demo describe pod Pod名称
kubectl -n demo logs Pod名称Pending 通常表示 CPU 或内存不足。ImagePullBackOff 表示镜像名称不正确、被镜像仓库拒绝访问,或达到了下载限制。
Ingress 返回 404,或 80/443 端口无响应
kubectl -n kube-system get pods,svc | grep -E 'traefik|svclb'
sudo ss -tlnp | grep -E ':(80|443)\b'404 通常表示 Host 请求头与 Ingress 的 host 字段不一致。如果 svclb Pod 一直处于 Pending 状态,很可能是 Nginx 或 Apache 等系统服务已经占用了 80 和 443 端口。
卸载 K3s
/usr/local/bin/k3s-uninstall.sh在代理上:
/usr/local/bin/k3s-agent-uninstall.sh延伸阅读
如需存储您的容器镜像,请参阅指南 安装 Harbor。如需自动化节点的准备工作,请参阅 使用 Ansible 自动化管理服务器。