Deploy-Laboratory/docs/00-01-k3s-基础概念.md

00-01-k3s-基础概念

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

TL;DR

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

阅读建议

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

排障

• 概念读不懂：先看 00-04-部署环境说明.md 了解本仓库“实验室约定”，再回到本篇对照术语与节点角色。
• 想跑命令但本篇没有：本篇不提供部署/验收命令；按 00-00 找到对应实验篇，再跑 ./scripts/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 列即节点名；或使用下面命令列出所有节点名：

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。

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 列：

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/ -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. 下一步

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