151 lines
10 KiB
Markdown
151 lines
10 KiB
Markdown
# 00-02-部署环境说明
|
||
|
||
> 本文描述本仓库文档所针对的**验证环境**：节点布局、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` / `ansible/bin/verify.sh`、编辑与排障；通过 SSH 连 ylc61～ylc64 执行自动化，磁盘与 **§3.1 K3s 节点约定无关**（按本机实际即可） |
|
||
| openwrt | 192.168.2.1 | OpenWrt 主路由 | 局域网网关；可选 HAProxy 将 80/443 转发至 K3s，见 `01-06` |
|
||
| 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 中的节点。
|
||
- **集群外 HTTP 探测（如 `01-06`）**：`ansible/env/.env.verify` 中 **`WORKSTATION_SSH`** 推荐配置为 **SSH 到 Linux 工作机 `ylc65`** 的一行命令（在该机上执行 `curl`，流量视角与 k3s 节点分离）；**`onecloud`** 仍为 ARM/NFS 等场景主机，与「工作机探测」默认语义不同。
|
||
|
||
## 排障
|
||
|
||
- **`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` 上执行本仓库各步骤**（克隆仓库、`./ansible/bin/deploy-lab.sh`、`./ansible/bin/verify.sh`、`ansible-playbook …`）时，该主机是 **Ansible 控制端**，需预先安装下列组件（版本可与 §2 对照，其他发行版用等价包名即可）：
|
||
|
||
| 用途 | 说明 |
|
||
|------|------|
|
||
| **Git** | 克隆 / 更新本仓库；排障时对比本地与远端分支。 |
|
||
| **Ansible**（`ansible-core` + `ansible-playbook`） | 执行 `ansible/playbooks/*`、`ansible/bin/deploy-lab.sh`、`ansible/bin/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 时由节点侧提供，控制端亦建议具备以便自检。 |
|
||
| **Helm**（`helm` CLI，**可选但常用**） | 在 **已能访问集群 API** 的机器上安装（多为控制节点 `ylc61` 或工作机 `ylc65` + `KUBECONFIG`）。用于 **Longhorn、kube-prometheus-stack** 等 chart 安装与升级；与 K3s 内置的 **HelmChart / HelmChartConfig**（`kube-system` 内由 k3s 调度的 chart）是两条线：CLI 面向你在终端执行的 `helm upgrade --install`，CRD 面向随集群声明的 Traefik 等。安装指引见 [Helm 官方安装文档](https://helm.sh/docs/intro/install/)；本仓库实践见 `03-07`、`05-05`、`03-10`（HelmChartConfig）。 |
|
||
|
||
**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，同样需满足上表（在控制节点上安装等价软件）。
|
||
|
||
### 1.2 Helm CLI 安装与自检（按需）
|
||
|
||
在计划执行 **`verify/03-07.yml`（Longhorn）**、**手工跟做 `05-05`（Prometheus/Grafana）** 或阅读 **HelmChartConfig**（`03-10`）前，建议在 **一台已配置 `KUBECONFIG` 的机器**上安装 Helm 3：
|
||
|
||
```bash
|
||
# Fedora / RHEL（若仓库提供 helm 包）
|
||
sudo dnf install -y helm
|
||
|
||
# 或按官方脚本/二进制：https://helm.sh/docs/intro/install/
|
||
helm version
|
||
helm list -A
|
||
```
|
||
|
||
大 chart 安装请带 **`--wait` 与 `--timeout`**（如 10m～20m），排障时查 `helm status`、`kubectl describe`、`kubectl get events`，与 `00-03` §2.1 表格一致。
|
||
|
||
## 2. 软件版本（已验证）
|
||
|
||
|
||
| 组件 | 版本 | 备注 |
|
||
| ------- | ----------------- | --------------------------- |
|
||
| OS | Fedora 43 Server （CoreOS） | 其他 RHEL 系 / Debian 系按文档说明适配 |
|
||
| K3s | v1.34.5+k3s1 | 来自 get.k3s.io 默认 |
|
||
| Ansible | ansible-core 2.18 | 用于 `01-05` 自动化安装 |
|
||
| Helm | 3.x（与 chart 要求一致） | **可选**；`03-07` playbook 会尝试在节点安装；手工 chart 见 `05-05` |
|
||
|
||
|
||
## 3. 网络与存储
|
||
|
||
- **网段**：192.168.2.0/24
|
||
- **可选**：OpenWrt 主路由（上表 `openwrt`，192.168.2.1）上配置 HAProxy 负载均衡，将 80/443 转发到 K3s 节点，见 `01-06-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-05`）。
|
||
|
||
### 3.2 推荐自动化顺序
|
||
|
||
1. （可选）`ansible/playbooks/verify/01-05.yml`：声明 `k3s_data_disk_device` 并启用 `k3s_prepare_storage` 时，幂等准备 `/storage`。
|
||
2. `ansible/playbooks/verify/01-05.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-05.yml`
|
||
- **playbook（数据盘，可选）**：`ansible/playbooks/verify/01-05.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-05` 一次性安装成功，各节点 Traefik 入口 404 可达。自动化与验证常在 **`ylc65` Linux 工作机**上执行，该主机不参与 K3s。
|
||
|