对齐文件规范
This commit is contained in:
132
docs/00-02-部署环境说明.md
Normal file
132
docs/00-02-部署环境说明.md
Normal file
@@ -0,0 +1,132 @@
|
||||
# 00-04-部署环境说明
|
||||
|
||||
> 本文描述本仓库文档所针对的**验证环境**：节点布局、IP、OS、K3s 版本等。其他环境按需对照调整。
|
||||
|
||||
## TL;DR
|
||||
|
||||
- **自动化验收（基线）**：本篇为环境说明文档，不参与 `verify.sh run-all/full`；按本文完成环境核对即可
|
||||
- **你需要准备**：`ansible/inventory.ini` 可 SSH；（可选）每台 k3s 节点独立挂载 `/storage`
|
||||
- **成功判据**：文档存在且 `ansible/files/00-02` 目录可追溯；节点规划/IP/角色与本文一致（或你已按本文做差异化对照）
|
||||
- **失败排障**：见本文「排障」小节（SSH/inventory/私钥权限、/storage 挂载、k3s API 连通）
|
||||
|
||||
## 1. 节点与角色
|
||||
|
||||
| 主机名 | IP | 角色 | 说明 |
|
||||
| -------- | ------------- | --------------- | --------------------------------------- |
|
||||
| ylc61 | 192.168.2.61 | k3s server | 控制节点，运行 API、etcd、Traefik 等 |
|
||||
| ylc62 | 192.168.2.62 | k3s worker | 工作节点 |
|
||||
| ylc63 | 192.168.2.63 | k3s worker | 工作节点 |
|
||||
| ylc64 | 192.168.2.64 | k3s worker | 工作节点 |
|
||||
| ylc65 | 192.168.2.65 | Linux 工作机（非 K3s） | **不参与** `kubectl get nodes`；提供日常 **Linux/x86_64** 环境，用于克隆本仓库、跑 `ansible-playbook` / `scripts/verify.sh`、编辑与排障；通过 SSH 连 ylc61～ylc64 执行自动化，磁盘与 **§3.1 K3s 节点约定无关**（按本机实际即可） |
|
||||
| openwrt | 192.168.2.1 | OpenWrt 主路由 | 局域网网关；可选 HAProxy 将 80/443 转发至 K3s，见 `01-07` |
|
||||
| onecloud | 192.168.2.22 | ARM32（Armbian） | 非 K3s 集群节点；armv7 / NFS 等文档的实验或外部 curl 来源 |
|
||||
|
||||
|
||||
- Kubernetes 中的节点名使用短主机名（**仅** `ylc61`～`ylc64` 四类 K3s 机器），与 inventory 中 `[k3s_server]` / `[k3s_worker]` 一致；`ylc65` **不是**集群成员。便于配合 Cloudflare CDN（若计算机 hostname 为 FQDN，本机解析会优先走本地导致无法访问）。
|
||||
- **控制机**（运行 `ansible-playbook`、`verify.sh`）：推荐 **`ylc65`（Linux 工作机）** 或 ylc61；亦可在你的本机 Linux 上执行，只要满足下节 **§1.1** 依赖并能 SSH 到 inventory 中的节点。
|
||||
|
||||
## 排障
|
||||
|
||||
- **`verify.sh preflight` / `run` 报 inventory 私钥不存在/权限过宽**：按报错提示 `chmod 600`，并检查 `ansible/inventory.ini` 中 `ansible_ssh_private_key_file` 路径是否在当前控制端存在。
|
||||
- **k3s API 不可达（6443）**：确认控制节点防火墙放行、IP/主机名解析正确；在控制端 `curl -k https://<server_ip>:6443/ping` 快速自检。
|
||||
- **DiskPressure / 系统盘被写满**：确认 `/storage` 为独立挂载点（见 §3.1），并确保 server/worker 都使用一致的 `--data-dir`。
|
||||
|
||||
### 1.1 Linux 工作机（ylc65）软件依赖
|
||||
|
||||
在 **`ylc65` 上执行本仓库各步骤**（克隆仓库、`./scripts/deploy-lab.sh`、`./scripts/verify.sh`、`ansible-playbook …`）时，该主机是 **Ansible 控制端**，需预先安装下列组件（版本可与 §2 对照，其他发行版用等价包名即可）：
|
||||
|
||||
| 用途 | 说明 |
|
||||
|------|------|
|
||||
| **Git** | 克隆 / 更新本仓库；排障时对比本地与远端分支。 |
|
||||
| **Ansible**（`ansible-core` + `ansible-playbook`） | 执行 `ansible/playbooks/*`、`scripts/deploy-lab.sh`、`scripts/verify.sh` 所调用的 playbook；与 §2「Ansible ansible-core 2.18」一致即可。 |
|
||||
| **OpenSSH 客户端**（`ssh`、`scp`、`ssh-keygen`） | 按 `ansible/inventory.ini` 连接 `ylc61`～`ylc64`（通常为 root + 私钥）；`scripts/ssh/test-ssh.sh` 等亦依赖本机 `ssh`。运行 `scripts/ssh/setup-k3s-workers-ssh.sh` 预配密钥时同样只需 OpenSSH；**不要求** PuTTY（仅当该脚本交互中勾选「生成 PuTTY .ppk」供 Windows 使用时，才需额外安装 `puttygen`）。 |
|
||||
| **Bash** | 仓库脚本为 `#!/usr/bin/env bash`；勿在仅 `sh` 的环境强行执行。 |
|
||||
| **curl** | 部分验证与文档示例；`verify` playbook 在远端执行 curl 时由节点侧提供，控制端亦建议具备以便自检。 |
|
||||
|
||||
**Fedora / RHEL 系示例**（在 ylc65 上）：
|
||||
|
||||
```bash
|
||||
sudo dnf install -y git ansible-core openssh-clients curl bash
|
||||
```
|
||||
|
||||
**Debian / Ubuntu 系示例**：
|
||||
|
||||
```bash
|
||||
sudo apt update
|
||||
sudo apt install -y git ansible openssh-client curl bash
|
||||
```
|
||||
|
||||
安装后自检：
|
||||
|
||||
```bash
|
||||
git --version
|
||||
ansible-playbook --version
|
||||
ssh -V
|
||||
```
|
||||
|
||||
Python 3 会作为 **Ansible 控制端**依赖被包管理器一并拉取，一般无需单独指定版本。若仅在 **ylc61 本机**跑 Ansible 而不使用 ylc65，同样需满足上表（在控制节点上安装等价软件）。
|
||||
|
||||
## 2. 软件版本（已验证）
|
||||
|
||||
|
||||
| 组件 | 版本 | 备注 |
|
||||
| ------- | ----------------- | --------------------------- |
|
||||
| OS | Fedora 43 Server （CoreOS） | 其他 RHEL 系 / Debian 系按文档说明适配 |
|
||||
| K3s | v1.34.5+k3s1 | 来自 get.k3s.io 默认 |
|
||||
| Ansible | ansible-core 2.18 | 用于 `01-06` 自动化安装 |
|
||||
|
||||
|
||||
## 3. 网络与存储
|
||||
|
||||
- **网段**：192.168.2.0/24
|
||||
- **可选**：OpenWrt 主路由（上表 `openwrt`，192.168.2.1）上配置 HAProxy 负载均衡，将 80/443 转发到 K3s 节点，见 `01-07-openwrt-haproxy.md`
|
||||
|
||||
### 3.1 磁盘规划（四台 K3s 节点统一：10G + 32G）
|
||||
|
||||
本仓库验证环境约定：**每台 K3s 节点**（`ylc61`～`ylc64`，即 1 server + 3 worker）各用一块约 **10G 系统盘**（根文件系统）+ 一块约 **32G 数据盘**，与 Longhorn、K3s `--data-dir` 实验相匹配。**`ylc65` 为工作机，不适用本节 `/storage` 与 K3s 数据盘约定。**
|
||||
|
||||
- **`/storage` 必须是独立挂载点**（数据盘格式化后挂载），**不能**只是根分区上的普通目录；否则镜像、local-path、Longhorn 仍会写满系统盘，控制节点易出现 **DiskPressure**。
|
||||
- **K3s**：server 与 worker 均使用 `--data-dir=/storage`（见 `ansible/group_vars/all.yml`）。
|
||||
- **token 路径**：`/storage/server/token`
|
||||
|
||||
**自检（每台执行）**：
|
||||
|
||||
```bash
|
||||
findmnt -n -o SOURCE / /storage
|
||||
lsblk -f
|
||||
```
|
||||
|
||||
两行 `SOURCE` 应指向**不同**块设备（或不同 LV）；若 `/storage` 未单独挂载，请先完成分区、格式化、`/etc/fstab` 再装 K3s（见 `01-06`）。
|
||||
|
||||
### 3.2 推荐自动化顺序
|
||||
|
||||
1. （可选）`ansible/playbooks/verify/01-06.yml`：声明 `k3s_data_disk_device` 并启用 `k3s_prepare_storage` 时，幂等准备 `/storage`。
|
||||
2. `ansible/playbooks/verify/01-06.yml`：安装 K3s（可开启 `k3s_verify_storage_mount` 校验挂载）。
|
||||
3. （可选）`ansible/playbooks/verify/03-07.yml`：Helm 安装 Longhorn（`ansible/files/03-07/values-lab.yaml`）。
|
||||
4. （可选）按 `03-05` 应用本仓库 **local-path** ConfigMap 真源（`ansible/files/03-05/local-path-config-lab.json`）。
|
||||
|
||||
## 4. 防火墙
|
||||
|
||||
- **firewalld**：启用
|
||||
- **已放行端口**：
|
||||
- 6443/tcp（k3s API，仅 server）
|
||||
- 8472/udp（flannel VXLAN，全部节点）
|
||||
- flannel.1、cni0 加入 trusted zone
|
||||
|
||||
## 5. Ansible 相关
|
||||
|
||||
控制端软件要求见 **§1.1**（`ylc65` 或任意运行 `ansible-playbook` 的机器）。
|
||||
|
||||
- **inventory**：`ansible/inventory.ini`，分组 `k3s_server`、`k3s_worker`、`k3s_nodes`（**勿**将 `ylc65` 列入 K3s 分组；工作机只作为 Ansible 控制端）
|
||||
- **变量**：`ansible/group_vars/all.yml`，含 `k3s_data_dir`、`k3s_server_ip`、`k3s_manage_`* 等
|
||||
- **playbook（k3s）**：`ansible/playbooks/verify/01-06.yml`
|
||||
- **playbook（数据盘，可选）**：`ansible/playbooks/verify/01-06.yml`
|
||||
- **playbook（Longhorn，可选）**：`ansible/playbooks/verify/03-07.yml`（Helm + `ansible/files/03-07/values-lab.yaml`，文档 `03-07`）
|
||||
- **playbook（nginx 矩阵）**：`ansible/playbooks/verify/02-05.yml`（manifests 在 `ansible/files/02-05/`，文档 `02-05`）
|
||||
- **playbook（nginx TLS 矩阵）**：`ansible/playbooks/verify/03-02.yml`（manifests 在 `ansible/files/03-02/`，文档 `03-02`（02-05 升级版））
|
||||
- **SSH**：root 连接，`scripts/ssh/setup-k3s-workers-ssh.sh` 预配密钥
|
||||
|
||||
## 6. 验证时间
|
||||
|
||||
- 2026-03：**4 节点**（1 server + 3 worker）集群按 `01-06` 一次性安装成功，各节点 Traefik 入口 404 可达。自动化与验证常在 **`ylc65` Linux 工作机**上执行，该主机不参与 K3s。
|
||||
|
||||
Reference in New Issue
Block a user