jack
8c43761962
- ansible/files 改为与文档 XX-YY 对齐的目录结构，更新相关 playbook 路径 - 新增 scripts/verify.sh 与 ansible/playbooks/verify/*.yml，移除单体 verify-matrix.yml - 补充 docs/00-02 矩阵状态、00-05 验证框架与流程、00-04 环境与 ylc65 工作机说明 - 增加 k3s 存储准备、Longhorn、local-path 等 playbook 与辅助脚本 Made-with: Cursor
140 lines
8.6 KiB
Markdown
140 lines
8.6 KiB
Markdown
# 00-01-k3s-基础概念
|
||
|
||
> 入门速查：先把核心概念看明白，再去做安装与排障。
|
||
|
||
## 阅读建议
|
||
|
||
- 新手按本页顺序读完即可
|
||
- 遇到术语不懂，先回这里再继续操作文档
|
||
|
||
## 1. K3s 是什么
|
||
|
||
- 轻量 Kubernetes 发行版，适合 Homelab。
|
||
- **用途**：在自家机器上跑容器、做编排，本仓库用它搭家庭实验环境。你的环境中：`ylc61` 是 server，`ylc62` 是 worker。
|
||
|
||
## 2. Service 类型（你最常用）
|
||
|
||
### 2.1 ClusterIP
|
||
|
||
- 只在集群内可访问，不对外暴露端口。
|
||
- **用途**：服务之间互相访问用（例如 Traefik 转给后端 Pod 就走 ClusterIP），适合内部调用。
|
||
|
||
### 2.2 NodePort
|
||
|
||
- 每个节点开放一个高位端口（如 3xxxx），集群外通过「节点 IP:端口」访问。
|
||
- **用途**：临时从外网访问某个服务、排查问题时用；长期对外入口一般用 LoadBalancer + Ingress，不直接暴露 NodePort。
|
||
|
||
### 2.3 LoadBalancer（K3s ServiceLB）
|
||
|
||
创建 Service 类型为 LoadBalancer 时，K3s 会为该服务分配对外 IP（多为节点 IP），使集群外可通过该 IP 访问服务，相当于**负载均衡入口**。K3s 用内置的 ServiceLB 实现：在部分节点上起 `svclb-*` Pod，在这些节点上监听并转发到后端。通过节点标签 **`svccontroller.k3s.cattle.io/enablelb=true`** 控制哪些节点参与负载均衡（即哪些节点会跑 svclb、对外暴露端口）；**`lbpool`** 可进一步分组（如 `lbpool=edge`），便于多组入口节点。未打 `enablelb` 的节点不会承载该 Service 的入口流量。
|
||
|
||
**用途**：让外网通过一个入口（或几台节点上的同一端口）访问你的服务，Traefik 的 80/443 就是这样暴露出来的。
|
||
|
||
## 3. 节点标签（nodeSelector 常用）
|
||
|
||
### 3.1 hostname（指定单台节点）
|
||
|
||
**标签**：`kubernetes.io/hostname`，值为节点名（短主机名，如 `ylc61`，便于配合 Cloudflare CDN）。
|
||
|
||
**获取**：NAME 列即节点名；或使用下面命令列出所有节点名：
|
||
|
||
```bash
|
||
kubectl get nodes
|
||
# 或只输出节点名
|
||
kubectl get nodes -o jsonpath='{.items[*].metadata.name}'
|
||
```
|
||
|
||
**用途**：在 Deployment 的 `nodeSelector` 里写 `kubernetes.io/hostname: <节点名>`，可指定 Pod 只跑在某一条节点上（如 02-05 的 M2、M4）。
|
||
|
||
### 3.2 control-plane / worker 标签（随机控制节点、随机工作节点）
|
||
|
||
**标签**：`node-role.kubernetes.io/control-plane`（控制平面）、`node-role.kubernetes.io/worker`（工作节点）。K3s 常不默认打这两个标签。
|
||
|
||
**获取**：查 control-plane 标签是否存在、取值是什么。CONTROL 列为 `<none>` 表示该节点没有此标签；工作节点同理可用 `--show-labels` 或把路径中的 `control-plane` 改为 `worker`。
|
||
|
||
```bash
|
||
kubectl get nodes -o custom-columns=NAME:.metadata.name,CONTROL:.metadata.labels.node-role\.kubernetes\.io/control-plane
|
||
```
|
||
|
||
**用途**：nodeSelector 用 `control-plane: ""` 或 `"true"` 可让 Pod 随机落在某一台控制节点（02-05 M1）；用 `worker: ""` 可随机落在某一台工作节点（02-05 M3）。未打标时需先打标或改用 hostname。
|
||
|
||
### 3.3 ROLES 列（一眼区分控制节点 / 工作节点）
|
||
|
||
**标签**：这里指 `kubectl get nodes` 的 ROLES 列（非节点上的 label，而是界面显示），取值为 `control-plane` 或空（终端显示 `<none>`）。
|
||
|
||
**获取**：执行下面命令即可看到 ROLES 列：
|
||
|
||
```bash
|
||
kubectl get nodes
|
||
```
|
||
|
||
**用途**：快速区分哪台是 server、哪几台是 worker。注意：ROLES 只是显示，K3s 不一定同时写入 `node-role.kubernetes.io/control-plane` 标签，用 3.2 的命令查该标签可能为空，此时 nodeSelector 需手动打标或改用 hostname。
|
||
|
||
## 4. Ingress 与 IngressRoute
|
||
|
||
- **Ingress**：Kubernetes 标准资源，按域名和路径把请求转到不同后端 Service。
|
||
- **IngressRoute**：Traefik 自带的 CRD，能表达的规则更多（如中间件、多后端权重）。
|
||
- **用途**：在同一个 80/443 端口上，按「哪个域名、哪个路径」把流量分到不同应用，不用每个服务都单独占一个端口或 IP。
|
||
|
||
## 5. NetworkPolicy 基本原则
|
||
|
||
- 一旦 Pod 被策略选中，该方向默认拒绝，只放行你显式允许的。
|
||
- Traefik 到后端建议同时放行：目标命名空间后端端口、Service CIDR（例如 `10.43.0.0/16`）。
|
||
- **用途**：限制「谁可以访问谁、哪些端口」，做网络隔离、缩小攻击面；配错了会导致访问不通，排障时需一起看。
|
||
|
||
参考：`06-01-k3s-networkpolicy-故障排查.md`
|
||
|
||
## 6. 常见误解
|
||
|
||
1. `404` 不等于故障（通常是入口通、路由未命中）
|
||
2. Pod IP 直连失败不一定影响主链路
|
||
3. 只放行端口不配转发策略，跨节点常会出问题
|
||
|
||
**用途**：排障时少走弯路，先分清「是没连上」还是「连上了但路由/策略不对」。
|
||
|
||
## 7. kubectl
|
||
|
||
- **是什么**：和集群 API 通信的命令行工具，本仓库里的 `kubectl get/apply/delete/logs` 等都用它。
|
||
- **用途**：查节点和 Pod 状态、部署/删除应用、看日志、排障，日常管理集群基本都靠它。
|
||
- **在哪里执行**：默认应在控制节点（server）上执行；K3s 装 server 时会在该节点生成 kubeconfig（如 `/etc/rancher/k3s/k3s.yaml`），只有控制节点默认能访问 API。工作节点若没拷 kubeconfig，不能直接在本机执行 `kubectl`；要在本机或其它机器执行时，需从控制节点拷贝 kubeconfig 并设好 `KUBECONFIG`，且该机器能访问控制节点 6443 端口。
|
||
|
||
## 8. 存储与节点故障
|
||
|
||
### 8.1 K3s 默认持久卷（local-path-provisioner）
|
||
|
||
K3s 自带 **local-path-provisioner**：当你创建 PVC 且不指定 `storageClassName` 时，由它按需创建本地 PersistentVolume。
|
||
|
||
- **工作机制**：PVC 被创建后，provisioner 会在 **Pod 被调度到的节点** 上，在其本地磁盘创建目录（默认在 `data-dir` 下的 `storage`，例如 `/var/lib/rancher/k3s/storage` 或 `/storage`），并为之创建 PV、与 PVC 绑定。
|
||
- **绑定到节点**：数据只存在于该节点的本地目录，**与该节点绑定**；Pod 被调度到另一节点时，会拿到新的空卷，旧节点上的数据不会自动迁移。
|
||
- **适用场景**：单副本应用、缓存、日志等，能接受 Pod 漂移后数据丢失或需手动恢复。**多副本共享数据**应使用 NFS、CSI 等共享存储（见 `01-05`）。
|
||
- **查看**：`kubectl get storageclass` 可见 `local-path`（通常为默认）；`kubectl get pv,pvc` 可查看已创建的卷。
|
||
- **操作示例**：见 `03-05-k3s-local-path-pvc.md`。
|
||
|
||
### 8.2 hostPath 与 NFS（选读）
|
||
|
||
- **Pod 可以漂移，宿主机本地数据不会跟着漂移**：用 `hostPath` 把宿主机目录挂进容器时，数据只在这台机器上；Pod 被调度到另一台节点后，那台机器没有同样目录和数据，应用就会“丢数据”。
|
||
- **K3s 不会自动帮你搬本地数据**：调度器只管 Pod 放哪台节点，不会同步 `/var/lib/...` 或自建目录；所以“节点故障自动漂移”和“数据高可用”是两件事，要分别设计。
|
||
- **常见做法**：重要数据用共享存储（NFS / 云盘 / CSI），通过 PV/PVC 给 Pod 用（参考 `01-05`、`03-07`）；缓存、临时文件用本地目录（`emptyDir` 或 `hostPath`），接受节点挂了可丢；或靠备份/同步把本地目录定期同步到别处，再在新节点恢复。
|
||
|
||
**用途**：搞清楚数据放哪、节点挂了会不会丢，才能设计备份和高可用，不踩坑。
|
||
|
||
## 9. 删除部署
|
||
|
||
- **是什么**：通过 `kubectl delete` 从集群中移除已部署的资源（Deployment、Service、Ingress 等）。
|
||
- **用法**：用部署时的 YAML 删除，与 `apply` 一一对应；或按资源类型和名称逐个删除。
|
||
- **示例**：
|
||
- `kubectl delete -f nginx-matrix.yaml`：删除该文件定义的所有资源
|
||
- `kubectl delete -f ansible/files/02-05-nginx-matrix/ -R`：递归删除该目录下所有 manifest 定义的资源（02-05 矩阵）
|
||
- `kubectl delete -f ansible/files/03-02-nginx-matrix-tls/ -R`：删除 03-02 TLS 矩阵（或见该文档 / playbook `nginx-matrix-tls-deploy.yml -e mode=cleanup`）
|
||
- `kubectl delete deployment nginx-m1 -n default`：按名称删除单个 Deployment
|
||
- **用途**：清理测试应用、下线服务、重装部署前先删除旧资源。资源删除后对应 Pod 会被终止，数据（etcd 中记录）一并移除；若用了 PVC，PVC 本身通常需单独删除。
|
||
|
||
参考：`02-05-nginx-验证矩阵-一键部署.md` 删除小节。
|
||
|
||
## 10. 下一步
|
||
|
||
- `01-01-k3s-控制节点含traefik.md`
|
||
- `01-02-k3s-工作节点.md`
|
||
|
||
|