# 00-01-k3s-基础概念

> 入门速查：先把核心概念看明白，再去做安装与排障。

## TL;DR

- **本文性质**：概念/术语速查（不对应独立铺栈）
- **推荐动作**：按 `00-00-构建总览.md` 进入主线；真机验收用 `./ansible/bin/verify.sh full`
- **成功判据**：能看懂后续文档中的 K3s/K8s 术语（node/pod/service/ingress 等）
- **排障**：执行类问题请转到对应实验篇（`01-*`/`02-*`/`03-*`）的「排障」

## 阅读建议

- 新手按本页顺序读完即可
- 遇到术语不懂，先回这里再继续操作文档

## 排障

- **概念读不懂**：先看 `00-02-部署环境说明.md` 了解本仓库“实验室约定”，再回到本篇对照术语与节点角色。
- **想跑命令但本篇没有**：本篇不提供部署/验收命令；按 `00-00` 找到对应实验篇，再跑 `./ansible/bin/verify.sh run <doc_id>`。

## 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-04`）。
- **查看**：`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-04`、`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/ -R`：递归删除该目录下所有 manifest 定义的资源（02-05 矩阵）
  - `kubectl delete -f ansible/files/03-02/ -R`：删除 03-02 TLS 矩阵（或见该文档 / playbook `03-02.yml -e nginx_matrix_tls_enable=true -e mode=cleanup`）
  - `kubectl delete deployment nginx-m1 -n default`：按名称删除单个 Deployment
- **用途**：清理测试应用、下线服务、重装部署前先删除旧资源。资源删除后对应 Pod 会被终止，数据（etcd 中记录）一并移除；若用了 PVC，PVC 本身通常需单独删除。

参考：`02-05-nginx-验证矩阵-一键部署.md` 删除小节。

## 10. Helm 简介（与本仓库）

- **是什么**：**Helm** 把 Kubernetes 应用打成 **Chart**（模板 + 默认配置），用 **`helm install` / `helm upgrade`** 一次装一类组件（如 Longhorn、Prometheus 全家桶），并可用 **values 文件**覆盖默认参数。
- **和 `kubectl apply` 的关系**：Helm 最终仍会把渲染后的 YAML **提交给 API Server**；你手里拿的 **values.yaml** 不是直接 `kubectl apply` 的对象，除非先从 chart 渲染出清单（`helm template`）。
- **和 K3s 的关系**：K3s 集群里常见两条线并存：
  - **`helm` 命令**：你在 shell 里对集群执行（需本机安装 CLI，见 `00-02` §1.2）。
  - **HelmChart / HelmChartConfig**（CRD）：由 k3s 在 **`kube-system`** 里调度部分内置 chart（如 Traefik）；改 Traefik 端口等可参见 `03-10` 的 `HelmChartConfig` 清单。
- **本仓库去哪学**：存储 **`03-07`**，监控 **`05-05`**，Traefik 参数注入 **`03-10`**，GitOps 里 Argo 安装方式 **`03-09`**；验证框架里对 Helm 超时与排障的约定见 **`00-03`** §2.1。

## 11. 下一步

- `01-01-k3s-控制节点含traefik.md`
- `01-02-k3s-工作节点.md`