197 lines
8.0 KiB
Markdown
197 lines
8.0 KiB
Markdown
# 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`
|