Deploy-Laboratory/docs/01-01-k3s-控制节点含traefik.md

01-01-k3s-控制节点含traefik

TL;DR

• 自动化验收：在控制端（如 ylc65）执行 ./scripts/verify.sh run 01-01
• 手工安装：控制节点执行 curl -sfL https://get.k3s.io | sh -s - server --data-dir=/storage（或默认路径）
• 成功判据：node 为 Ready；kube-system 中 coredns / traefik Deployment 存在；Traefik 入口可响应（常见为 404）
• 失败排障：见本文「排障」小节（事件/Pod/日志/磁盘压力）

说明：本篇聚焦 单控制节点安装与基础验收。若要一键自动化安装多节点集群，见 01-06-节点初始化-ansible-实践.md。

前置条件

• 控制节点系统已完成基础网络配置
• 可使用 sudo，并可访问公网或本地镜像源
• 节点时间已同步（NTP）
• 方案二（数据盘）：若使用自定义存储目录，需先将独立数据盘挂载到 /storage（本仓库验证环境为 约 10G 系统盘 + 约 32G 数据盘，四节点同构；控制节点也必须有独立数据盘，否则 Longhorn / containerd 与系统争用根分区，易出现 DiskPressure）。

存储方案说明

K3s 默认将数据（含 local-path 卷）放在 --data-dir 下。系统盘较小时，应将数据目录放到单独挂载的数据盘（如 /storage），避免占满系统盘。

方案	数据目录	适用场景
方案一（默认）	/var/lib/rancher/k3s	系统盘空间充足
方案二（数据盘）	/storage	系统盘小，数据盘单独挂载在 /storage

自定义 /storage 仅解决单节点内系统盘/数据盘分离；节点或数据盘重建后数据不会自动迁移，高可用与备份见 01-08、06-03。

操作步骤

1. 在控制节点安装 K3s Server（默认包含 Traefik）
2. 等待核心组件进入 Running
3. 记录节点 IP，供后续工作节点加入和入口验证

方案一：默认数据目录

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

方案二：数据盘（自定义数据目录）

确保数据盘已挂载到 /storage 后执行：

curl -sfL https://get.k3s.io | sh -s - server --data-dir=/storage

• 使用方案二时，token 路径为 /storage/server/token（供 01-02 工作节点加入与 01-08 HA 使用）。

配置 kubectl（供当前用户使用）

安装后 K3s 生成的 kubeconfig 在 /etc/rancher/k3s/k3s.yaml，默认仅 root 可读。若希望当前用户在本机直接执行 kubectl（无需 sudo），可任选其一：

方式一：复制到用户目录并设 KUBECONFIG

mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $(id -u):$(id -g) ~/.kube/config
chmod 600 ~/.kube/config
export KUBECONFIG=~/.kube/config

# 若希望每次登录自动生效，可把下面这一行（整行，不要带 #）写入 ~/.bashrc 或 ~/.profile：
#   export KUBECONFIG=~/.kube/config
# 写入示例： echo 'export KUBECONFIG=~/.kube/config' >> ~/.bashrc

方式二：仅用 KUBECONFIG 指向原路径（需 root 放宽该文件权限）

sudo chmod 644 /etc/rancher/k3s/k3s.yaml
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml

之后即可用 kubectl get nodes 等命令做验证。

其他设备使用 kubectl 控制集群

从笔记本、跳板机等非控制节点用 kubectl 管理集群时，需要：① 在该设备上安装 kubectl；② 有一份 kubeconfig，且其中的 API 地址指向控制节点（不能是 127.0.0.1）。

0. 在其他设备上安装 kubectl

在要执行 kubectl 的那台机器上安装 kubectl（仅需一次）：

• Linux（通用）：从官方 release 下载与集群版本相近的二进制（建议与 K3s 自带的 Kubernetes 版本一致），放入 PATH：

# 以 v1.28 为例，按实际 K3s 的 Kubernetes 版本选择
curl -LO https://dl.k8s.io/release/v1.28.0/bin/linux/amd64/kubectl
chmod +x kubectl
sudo mv kubectl /usr/local/bin/
kubectl version --client

• Debian/Ubuntu：可用包管理器安装（版本可能略旧）：

sudo apt-get update && sudo apt-get install -y apt-transport-https ca-certificates curl
curl -fsSL https://pkgs.k8s.io/core/stable/deb/Release.key | sudo gpg --dearmor -o /usr/share/keyrings/kubernetes-apt-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core/stable/deb/ /" | sudo tee /etc/apt/sources.list.d/kubernetes.list
sudo apt-get update && sudo apt-get install -y kubectl

• macOS：brew install kubectl（或从 Kubernetes 官方文档 选择其他方式）。

• Windows：可用 winget install Kubernetes.kubectl 或从 官方文档 下载二进制并加入 PATH。

1. 在控制节点上准备可外连的 kubeconfig

在控制节点执行（将 控制节点IP或主机名 改为实际地址，如 192.168.2.61 或 ylc61）：

sudo sed 's/127.0.0.1/控制节点IP或域名/' /etc/rancher/k3s/k3s.yaml > /tmp/k3s-for-remote.yaml
sudo chmod 644 /tmp/k3s-for-remote.yaml

2. 拷贝到其他设备

在其他设备上执行（需能 SSH 到控制节点，或通过 U 盘/SCP 等方式拿到文件）：

# 示例：从控制节点拉取到本机
scp 用户@控制节点IP或域名:/tmp/k3s-for-remote.yaml ~/.kube/config
# 若本机尚无 ~/.kube 目录
mkdir -p ~/.kube
# 再执行上述 scp，并设置权限
chmod 600 ~/.kube/config

3. 本机使用

export KUBECONFIG=~/.kube/config
# 可写入 ~/.bashrc / ~/.zshrc
kubectl get nodes

注意：其他设备需能访问控制节点的 6443 端口（K3s API）。若中间有防火墙，需放行控制节点 6443；若用域名，需能解析到控制节点 IP。

验证命令

若已按上节配置当前用户的 kubectl，可直接执行 kubectl；否则使用 sudo kubectl。

kubectl get nodes -o wide
kubectl -n kube-system get pods -o wide
kubectl -n kube-system get deploy,svc traefik -o wide
curl -I --max-time 3 http://127.0.0.1:80

预期

• kubectl get nodes 显示控制节点为 Ready
• kube-system 命名空间核心组件正常运行
• Traefik 服务已创建并可响应（常见为 404，表示入口已通）

清理

本篇为安装类文档：手工安装后一般 不卸载 K3s，而是继续后续实验。若你仅为排障临时验收，可在运行 ./scripts/verify.sh run 01-01 时设 VERIFY_TEARDOWN=0 保留现场（本篇用例默认不做破坏性清理）。

排障

• 节点不 Ready / DiskPressure：优先确认 /storage 为独立挂载点（见 docs/00-04-部署环境说明.md），再看 df -h、kubectl describe node <name> 事件。
• Traefik 不就绪：kubectl -n kube-system get pods -o wide；必要时 kubectl -n kube-system logs deploy/traefik --tail=200。
• CoreDNS 解析异常（影响后续 ACME）：见下节「CoreDNS 上游 DNS」。

CoreDNS 上游 DNS（ACME 用）

若后续要按 03-02 / 03-03 配置 ACME（Let's Encrypt），需确保集群内能解析 acme-v02.api.letsencrypt.org。宿主机若使用 IPv6 DNS（/etc/resolv.conf 含 240e:... 等），K3s Pod 网络仅 IPv4 时无法访问，ACME 会报 server misbehaving 或 network is unreachable。

手动修复（按需执行）：

kubectl -n kube-system edit configmap coredns

将 Corefile 中的 forward . /etc/resolv.conf 改为：

forward . 223.5.5.5 8.8.8.8

然后重启 CoreDNS：kubectl -n kube-system rollout restart deploy/coredns

若使用 Ansible 一键安装（01-06），playbook 已自动完成此配置，无需手动修改。

下一步

• 继续 01-02-k3s-工作节点.md