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

## TL;DR

- **自动化验收**：在控制端（如 `ylc65`）执行 `./ansible/bin/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-05-节点初始化-ansible-实践.md`。

## 契约与真源

- **安装命令备忘**：`ansible/files/01-01/k3s-server-install.example.sh`（与下文 curl 片段一致；非 K8s 清单）。
- **自动**：`./ansible/bin/verify.sh run 01-01`（专用 kubectl 断言；与手工安装共用 `ansible/files/01-01/` 索引）。

## 前置条件

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

## 存储方案说明

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

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

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

## 操作步骤

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

### 方案一：默认数据目录

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

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

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

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

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

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

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

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

```bash
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 放宽该文件权限）**

```bash
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：

```bash
# 以 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**：可用包管理器安装（版本可能略旧）：

```bash
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 官方文档](https://kubernetes.io/zh-cn/docs/tasks/tools/install-kubectl/) 选择其他方式）。

- **Windows**：可用 `winget install Kubernetes.kubectl` 或从 [官方文档](https://kubernetes.io/zh-cn/docs/tasks/tools/install-kubectl-windows/) 下载二进制并加入 PATH。

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

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

```bash
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 等方式拿到文件）：

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

**3. 本机使用**

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

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

## 验证命令

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

```bash
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**，而是继续后续实验。若你仅为排障临时验收，可在运行 `./ansible/bin/verify.sh run 01-01` 时设 `VERIFY_TEARDOWN=0` 保留现场（本篇用例默认不做破坏性清理）。

## 排障

- **节点不 Ready / DiskPressure**：优先确认 `/storage` 为独立挂载点（见 `docs/00-02-部署环境说明.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`。

**手动修复**（按需执行）：

```bash
kubectl -n kube-system edit configmap coredns
```

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

```txt
forward . 223.5.5.5 8.8.8.8
```

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

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

## 下一步

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