如何在美国服务器上部署K3s集群并验证节点间通信?
在两台美国服务器上部署 K3s,首次实施可以采用“一台控制节点、一台工作节点”的结构:先确认两台机器的私网互通,再安装 K3s Server、加入 K3s Agent,最后用分布在不同节点上的测试 Pod 验证双向访问、DNS 解析和 Service 转发。仅看到节点状态为 Ready,还不能证明节点间的容器网络正常。
下面以 Ubuntu 22.04 LTS、systemd 和 K3s 默认的 Flannel VXLAN 网络为例。两台服务器应位于同一美国机房或具备稳定互通的私网,具备 sudo 权限及软件、镜像下载条件。本方案用于首次部署验证,不包含多控制节点高可用、业务发布或公网服务暴露。
围绕美国服务器上的 K3s 容器集群部署,A5数据提供 Xeon、AMD EPYC 等物理服务器资源,可承载控制节点、工作节点及容器应用。美国 AMD 系列的大内存与 NVMe 存储组合,为多 Pod 运行、镜像存储和应用数据读写提供硬件基础;不同计算资源档位,也为从双节点实验环境向更多容器工作负载扩展提供资源选择。
一、准备服务器与网络条件
确认节点规划
本文使用以下示例地址,执行前替换成实际私网 IP 和网卡名称。
| 项目 | 控制节点 | 工作节点 |
|---|---|---|
| K3s 角色 | Server | Agent |
| 节点名称 | us-server-1 | us-agent-1 |
| 私网 IP | 10.20.0.10 | 10.20.0.11 |
| 私网网卡示例 | ens7 | ens7 |
| 测试资源参考 | 2 核 CPU、4 GB 内存 | 2 核 CPU、4 GB 内存 |
上述资源是小规模验证的参考配置,不代表业务容量。单控制节点故障时,集群管理能力会受到影响,不能将这一结构视为高可用方案。
在两台节点分别执行:
cat /etc/os-release
uname -r
free -h
df -h /
ip -br addr
swapon --show
timedatectl status
确认操作系统一致、磁盘有可用空间、私网 IP 固定,且系统时间同步。本文按未启用 swap 的环境操作;若 swapon --show 有输出,应先评估系统用途并按变更流程关闭,不直接修改已有业务服务器。
在控制节点检查到工作节点的路由:
ip route get 10.20.0.11
在工作节点执行反向检查:
ip route get 10.20.0.10
输出中的 src 应是本机私网 IP,dev 应对应实际用于节点互通的网卡。后面的 flannel-iface 必须填写这个网卡,而不是照抄 ens7。
默认 Pod 网段为 10.42.0.0/16,Service 网段为 10.43.0.0/16。两者不能与服务器现有私网或其他已连接网络重叠;存在冲突时,应在首次安装前规划替代网段。
放行必要通信,不公开集群内部端口
美国服务器有公网地址,不意味着 K3s 内部通信应该走公网。本文把节点地址固定为私网 IP,并要求两台机器的私网 UDP 通信可达。
| 协议与端口 | 允许方向 | 用途 |
|---|---|---|
| TCP 6443 | 工作节点到控制节点 | Kubernetes API、节点注册 |
| UDP 8472 | 两节点双向 | 默认 Flannel VXLAN 数据面 |
| TCP 10250 | 两节点之间按节点 IP 放行 | kubelet API,包括日志、exec 等功能 |
| 出站 DNS、HTTPS | 两节点到各自配置的解析器及下载源 | 域名解析、安装包与镜像下载 |
尤其不要把 UDP 8472 向整个互联网开放。云安全组、机房 ACL 和操作系统防火墙都要检查。
若服务器已经启用 UFW,可按下列方式增加精确来源规则。先保存 sudo ufw status numbered 的输出,并保留现有 SSH 管理规则;不要在远程部署过程中顺手启用、重置或清空防火墙。
控制节点执行:
sudo ufw allow from 10.20.0.11 to any port 6443 proto tcp
sudo ufw allow from 10.20.0.11 to any port 8472 proto udp
sudo ufw allow from 10.20.0.11 to any port 10250 proto tcp
工作节点执行:
sudo ufw allow from 10.20.0.10 to any port 8472 proto udp
sudo ufw allow from 10.20.0.10 to any port 10250 proto tcp
这些规则只处理节点间端口。如果 UFW 对转发流量有限制,还需允许实际 Pod 网段经 cni0、flannel.1 转发,不能把“端口已放行”等同于“Pod 转发已允许”。首次测试可使用已有合规策略、且未限制内部转发的干净服务器,避免叠加未知防火墙规则。

二、安装控制节点并验证 API
写入 K3s Server 配置
以下步骤只适用于尚未安装 K3s 的新节点。若 /etc/rancher/k3s/config.yaml 已存在,先备份并检查内容,不直接覆盖。
在控制节点执行:
sudo install -d -m 700 /etc/rancher/k3s
sudo tee /etc/rancher/k3s/config.yaml >/dev/null <<'EOF'
node-name: us-server-1
node-ip: 10.20.0.10
flannel-iface: ens7
write-kubeconfig-mode: "0600"
disable:
- traefik
- servicelb
EOF
sudo chmod 600 /etc/rancher/k3s/config.yaml
禁用 Traefik 和 ServiceLB,是为了让首次验证只聚焦节点及集群内部网络,并非 K3s 的必需设置。
下载安装脚本,查看后执行:
curl -fL https://get.k3s.io -o /tmp/k3s-install.sh
less /tmp/k3s-install.sh
sudo env INSTALL_K3S_CHANNEL=stable \
sh /tmp/k3s-install.sh server
安装脚本会以 root 权限创建服务并安装程序,只应执行可信来源的脚本。这里通过 stable 通道选择版本,不固定一个可能过期的补丁版本;工作节点随后必须使用控制节点实际安装的完整版本号。
验证控制节点
sudo systemctl is-active k3s
sudo k3s --version
sudo k3s kubectl get nodes -o wide
sudo k3s kubectl get pods -n kube-system
预期服务显示 active,节点最终进入 Ready,INTERNAL-IP 为 10.20.0.10。首次下载镜像时,系统 Pod 可能暂时处于 ContainerCreating;应结合事件判断,不将短暂等待直接判为失败。
记录 k3s --version 中的完整版本号,后续 Agent 使用同一版本。本文后面的 kubectl 命令均在控制节点通过 sudo k3s kubectl 执行,无需复制高权限 kubeconfig 到工作节点。
三、加入工作节点并检查节点状态
安全传递加入令牌
控制节点的加入令牌位于:
/var/lib/rancher/k3s/server/node-token
通过已有的可信管理通道,将其复制到工作节点的:
/etc/rancher/k3s/join-token
例如,只有在既有安全策略已经允许 root 密钥登录时,才可在工作节点使用以下命令;不要为了复制令牌临时开放 root 密码登录。
sudo install -d -m 700 /etc/rancher/k3s
sudo scp root@10.20.0.10:/var/lib/rancher/k3s/server/node-token \
/etc/rancher/k3s/join-token
sudo chmod 600 /etc/rancher/k3s/join-token
令牌属于敏感凭据,不应放进公开工单、代码仓库或文章截图。没有上述 SSH 条件时,改用经过授权的文件传输方式,目标路径和权限保持一致。
安装 Agent
在工作节点创建配置,同样不要覆盖已有文件:
sudo tee /etc/rancher/k3s/config.yaml >/dev/null <<'EOF'
server: https://10.20.0.10:6443
token-file: /etc/rancher/k3s/join-token
node-name: us-agent-1
node-ip: 10.20.0.11
flannel-iface: ens7
EOF
sudo chmod 600 /etc/rancher/k3s/config.yaml
将下列变量替换成控制节点刚才记录的完整版本号后,再执行安装:
K3S_VERSION='替换为控制节点的完整版本号'
curl -fL https://get.k3s.io -o /tmp/k3s-install.sh
less /tmp/k3s-install.sh
sudo env INSTALL_K3S_VERSION="$K3S_VERSION" \
sh /tmp/k3s-install.sh agent
sudo systemctl is-active k3s-agent
回到控制节点检查:
sudo k3s kubectl get nodes -o wide
此时应看到两个节点均为 Ready,内部地址分别为 10.20.0.10 和 10.20.0.11,版本一致。Agent 的 ROLES 显示 <none> 不代表加入失败。
四、验证跨节点 Pod、DNS 和 Service
节点注册验证的是控制面连接,跨节点 Pod 访问验证的是容器网络数据面。二者必须分别通过。 宿主机能 ping 通对端,也不能替代下面的测试。
创建分别固定到两个节点的测试 Pod
在控制节点保存以下清单为 k3s-check.yaml:
apiVersion: v1
kind: Namespace
meta
name: k3s-check
---
apiVersion: v1
kind: Pod
meta
name: check-server
namespace: k3s-check
labels:
app: check-server
spec:
nodeName: us-server-1
containers:
- name: http
image: busybox:1.36.1
command:
- sh
- -c
- |
mkdir -p /www
echo "$HOSTNAME" > /www/index.html
exec httpd -f -p 8080 -h /www
readinessProbe:
httpGet:
path: /
port: 8080
---
apiVersion: v1
kind: Pod
meta
name: check-agent
namespace: k3s-check
labels:
app: check-agent
spec:
nodeName: us-agent-1
containers:
- name: http
image: busybox:1.36.1
command:
- sh
- -c
- |
mkdir -p /www
echo "$HOSTNAME" > /www/index.html
exec httpd -f -p 8080 -h /www
readinessProbe:
httpGet:
path: /
port: 8080
应用并等待就绪:
sudo k3s kubectl apply -f k3s-check.yaml
sudo k3s kubectl wait -n k3s-check \
--for=condition=Ready pod --all --timeout=180s
sudo k3s kubectl get pods -n k3s-check -o wide
预期两个 Pod 均为 Running、1/1,且 NODE 分别对应两台服务器。若等待超时,先查看 Pod 事件;180 秒是本次测试的等待上限,不是部署时长保证。
双向访问对端 Pod IP
SERVER_POD_IP=$(sudo k3s kubectl get pod check-server \
-n k3s-check -o jsonpath='{.status.podIP}')
AGENT_POD_IP=$(sudo k3s kubectl get pod check-agent \
-n k3s-check -o jsonpath='{.status.podIP}')
sudo k3s kubectl exec -n k3s-check check-server -- \
wget -T 5 -qO- "http://${AGENT_POD_IP}:8080/"
sudo k3s kubectl exec -n k3s-check check-agent -- \
wget -T 5 -qO- "http://${SERVER_POD_IP}:8080/"
预期第一条返回 check-agent,第二条返回 check-server。这些是示例预期结果,不是实际执行记录。
验证 DNS 与 Service 转发
先从两个节点上的 Pod 分别解析集群域名:
sudo k3s kubectl exec -n k3s-check check-server -- \
nslookup kubernetes.default.svc.cluster.local
sudo k3s kubectl exec -n k3s-check check-agent -- \
nslookup kubernetes.default.svc.cluster.local
预期均解析到 Kubernetes API Service 的集群 IP。再给工作节点上的测试 Pod 创建内部 Service:
sudo k3s kubectl expose pod check-agent -n k3s-check \
--name=agent-http --port=8080 --target-port=8080
sudo k3s kubectl exec -n k3s-check check-server -- \
wget -T 5 -qO- \
http://agent-http.k3s-check.svc.cluster.local:8080/
预期返回 check-agent。这一步同时验证服务名解析、ClusterIP 转发和访问另一节点上的后端 Pod,不需要创建公网入口。

五、按由外到内的顺序处理异常
节点无法加入或一直 NotReady
先在工作节点检查私网路由和 API 连通性:
ip route get 10.20.0.10
curl -k --connect-timeout 5 https://10.20.0.10:6443/readyz
sudo journalctl -u k3s-agent -n 100 --no-pager
这里的 -k 仅用于连通性诊断,不用于配置 Agent。收到 HTTP 响应,包括认证拒绝,说明网络和 TLS 通道至少已经建立;超时通常需要检查安全组、ACL、主机防火墙和路由;连接拒绝则应检查控制节点服务是否启动、地址与端口是否正确。
随后在控制节点检查:
sudo journalctl -u k3s -n 100 --no-pager
sudo k3s kubectl describe node us-agent-1
日志提示令牌不匹配时核对令牌;提示证书时间问题时核对时间同步;提示网络插件未就绪时再检查 Flannel,而不是反复卸载重装。
Pod 未就绪或跨节点访问失败
先排除镜像拉取和容器启动问题:
sudo k3s kubectl describe pod check-agent -n k3s-check
sudo k3s kubectl get events -n k3s-check \
--sort-by=.metadata.creationTimestamp
ImagePullBackOff 指向镜像下载、解析或仓库访问,不等于节点网络故障。
若 Pod 已运行、宿主机互通,但对端 Pod IP 访问超时,检查两台节点的 UDP 8472、转发规则及实际出接口:
ip -d link show flannel.1
ip route
sysctl net.ipv4.ip_forward
预期存在 Flannel 接口和远端 Pod 网段路由,IPv4 转发值为 1。若安装了 tcpdump,可在发起测试时观察:
sudo tcpdump -ni ens7 udp port 8472
发送端有封装流量、接收端看不到,重点检查节点之间的网络过滤;接收端能看到流量但访问仍失败,再检查宿主机转发、路由和 Pod 状态。
若小请求成功而大包失败,应检查底层 MTU。VXLAN 有封装开销,不能直接把 Pod MTU 设置为与底层链路相同的数值。
Pod IP 可达但 Service 名访问失败时,应分别检查 DNS 与服务后端:
sudo k3s kubectl get pods -n kube-system -l k8s-app=kube-dns
sudo k3s kubectl get svc agent-http -n k3s-check
sudo k3s kubectl get endpointslices -n k3s-check \
-l kubernetes.io/service-name=agent-http
无可用后端地址通常指向标签选择或 Pod 就绪状态;域名已解析、Pod IP 可达但 ClusterIP 不通,则重点检查 Service 转发及防火墙规则。

六、验收与回滚检查项
部署验收
保留节点列表、Pod 分布和测试结果,但不要保存或公开令牌内容。
- 两个节点均为
Ready,版本一致,内部地址使用预期私网。 - 两个测试 Pod 分别运行在指定节点。
- 两个方向的 Pod IP HTTP 请求均返回对端标识。
- 两个 Pod 均能解析集群域名。
- 控制节点上的 Pod 能通过 Service 名访问工作节点上的后端。
- UDP 8472 未向公网开放,TCP 6443、10250 的来源范围符合规划。
通过这些检查,才可以确认本次环境的控制面、跨节点 Pod 网络、DNS 和 Service 基础通信正常;它不代表吞吐、故障恢复或生产容量已经验收。
清理测试与撤销部署
仅清理测试资源时执行:
sudo k3s kubectl delete namespace k3s-check
该操作会删除命名空间内全部资源,只适用于本文专用测试命名空间。之后再检查 get nodes,确认集群仍正常运行。
如果要撤销整次首次部署,以下卸载命令会清理对应节点的 K3s 组件和本地集群数据,可能影响本地持久卷。只在尚未承载真实业务时直接执行;已有业务必须先完成应用、数据库、存储和集群状态备份,并验证恢复方案。
工作节点先执行:
sudo /usr/local/bin/k3s-agent-uninstall.sh
控制节点再执行:
sudo /usr/local/bin/k3s-uninstall.sh
最后核对:
- 按变更记录撤销本次新增的安全组、ACL 和 UFW 规则,不删除原有规则;UFW 可使用原命令加
delete撤销,例如sudo ufw delete allow from 10.20.0.11 to any port 8472 proto udp。 - 确认
k3s、k3s-agent服务不再运行,相关端口不再监听。 - 检查残留配置和令牌文件,只删除确定属于本次部署的文件。
- 若保留集群、仅移除工作节点,应另外删除其 Node 对象;若恢复原环境,应按部署前备份恢复,而不是仅以“服务停止”作为回滚完成标准。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/4114.html



