看懂集群与核心资源

Kubernetes 的资源很多，但日常排障首先要能回答三个问题：应用在哪个 Namespace？Pod 跑在哪个 Node？谁负责维持这些 Pod？

本篇目标：建立集群组件心智模型，看懂 YAML 结构，理解标签/选择器机制，并会用 describe 和 events 获取故障证据。

1. 集群架构

1.1 控制面组件

控制面负责"集群应该是什么样"的决策：

组件	职责	出问题时的表现
kube-apiserver	所有操作的统一入口，REST API	`kubectl` 超时，所有变更失败
etcd	存储集群所有资源对象的"真相源"	集群失忆，已创建资源可能不可查询
kube-scheduler	为未调度的 Pod 选择 Node	新 Pod 一直 `Pending`
kube-controller-manager	运行各种控制器（Deployment、Node 等），持续调谐状态	副本数不对、Node 状态不更新
cloud-controller-manager	与云厂商 API 交互（负载均衡、云盘）	LoadBalancer 类型 Service 无外部 IP

1.2 Node 组件

每个 Node 上运行着让 Pod 能正常工作的基础组件：

组件	职责	出问题时的表现
kubelet	接收 Pod 定义，管理容器生命周期	节点 `NotReady`，Pod 无法启动
kube-proxy	维护 Node 上的网络规则，转发 Service 流量	Service 无法从该 Node 访问
容器运行时	实际运行容器（containerd、CRI-O）	容器无法创建或启动

1.3 资源关系图

Kubernetes 集群与核心资源关系

Pod 是会被替换的临时实例；Deployment、Service、PVC 等对象才是通常应长期管理的声明。

2. YAML 结构：每个资源都长这样

每个 Kubernetes 资源 YAML 都有四个顶层字段：

apiVersion: apps/v1          # API 组和版本（决定可用字段）
kind: Deployment             # 资源类型
metadata:                    # 名称、Namespace、标签、注解
  name: web
  namespace: learning
  labels:
    app.kubernetes.io/name: web
spec:                        # 期望状态（你想要的）
  replicas: 2
  selector: ...
  template: ...
# status:                    # 实际状态（Kubernetes 自动维护，YAML 中不写）

spec 是你声明的期望状态，status 是 Kubernetes 观察到的实际状态。控制器持续把 status 向 spec 调谐——这是声明式配置的核心。

3. 声明式 vs 命令式

同一件事的两种做法，理解差异很重要：

# 命令式：告诉 Kubernetes"做什么"（手动）
kubectl scale deployment web --replicas=3

# 声明式：告诉 Kubernetes"应该是什么样"（YAML + apply）
# 修改 YAML 中 replicas: 2 → 3，然后：
kubectl apply -f deployment.yaml

声明式的优势：

可审计：YAML 在 Git 中，谁改了什么一清二楚；
可重复：同一份 YAML apply 到任何集群都得到同样结果；
可自动恢复：有人手工改了副本数，控制器会自动调谐回 YAML 声明的值。

4. Namespace 是第一个隔离边界

Namespace 将同一集群中的资源按团队、环境或系统划分。它不是网络隔离的全部，也不是物理集群，但适合承载权限、配额和资源命名边界。

kubectl get namespaces
kubectl get all -n learning
kubectl get pods -A -o wide

生产常见划分是 platform-system、observability、staging-app、prod-app。不要把应用、监控和系统组件全部部署到 default。

5. Node 与 Pod

Node 是实际提供资源的机器或虚拟节点；Pod 是调度到 Node 上的最小单位。一个 Pod 可以包含多个紧密协作的容器，例如主应用和日志 Sidecar，但多数应用 Pod 只有一个主容器。

# 查看节点容量、版本、IP 与污点
kubectl get nodes -o wide
kubectl describe node <node-name>

# 查看 Pod 被调度到了哪个 Node，以及其 Pod IP
kubectl get pods -n learning -o wide

不要依赖 Pod IP

Pod 重建、扩缩容和重新调度都会改变 Pod IP。服务间访问应使用 Service DNS，例如 api.learning.svc.cluster.local，而不是记录某个 Pod IP。

6. 标签与选择器

标签（label）是 Kubernetes 把对象关联起来的基础。Deployment 用选择器管理 Pod，Service 也通过选择器找到后端 Pod。

metadata:
  labels:
    app.kubernetes.io/name: web
    app.kubernetes.io/part-of: learning
    app.kubernetes.io/component: api

kubectl get pods -n learning -l app.kubernetes.io/name=web

推荐使用 app.kubernetes.io/* 这组通用标签。选择器一旦与既有 Pod 不一致，Service 可能没有后端，Deployment 也可能无法正确识别它管理的副本。

6.1 Labels vs Annotations

	Labels	Annotations
用途	标识和选择对象（选择器匹配）	存储元数据（不能被选择器匹配）
典型值	`app.kubernetes.io/name: web`	`git-commit: a1b2c3d`、`updated-by: platform-team`
选择器可用	✅	❌
大小限制	名称 63 字符，值 63 字符	无硬限制（但不宜过大）

把运维信息（构建号、部署时间、联系人）放 annotation，把分组和路由信息（应用名、组件、环境）放 label。

7. 调谐循环：Kubernetes 如何工作

控制器通过"观察 → 对比 → 行动"的循环持续工作：

观察：控制器读到 spec.replicas=3
对比：实际只有 2 个 Pod Running
行动：创建第 3 个 Pod
回到步骤 1，持续循环

这就是为什么 YAML apply 之后不需要手动"运行"什么——控制器在后台持续调谐，即使 Pod 意外被删也会自动创建回来。也是为什么"手工删 Pod → 它又回来了"是正常行为而非 bug。

8. 用 describe 与 events 找证据

状态列表只能说明"有问题"，事件通常说明"为什么"：

kubectl describe pod <pod-name> -n learning
kubectl get events -n learning --sort-by=.lastTimestamp
# 查看最近 10 分钟的所有事件
kubectl get events -A --field-selector type=Warning --sort-by=.lastTimestamp

例如 FailedScheduling 指向资源、污点或节点选择问题；ErrImagePull / ImagePullBackOff 指向镜像地址、凭据或网络问题。后续排障章节会按现象展开。

9. 练习

练习 A

跑 kubectl get pods -n kube-system，识别哪些是控制面组件、哪些是每个 Node 都有的 Agent
修改之前创建的 Deployment YAML，把 replicas 从 2 改为 1，对比 kubectl get pods 前后变化
手误删一个 Deployment 管理的 Pod（kubectl delete pod <pod-name>），观察它是否被自动重建

练习 B

给一个 Pod 添加 annotation：kubectl annotate pod <pod> -n learning git-commit=abc123
用 kubectl describe pod <pod> -n learning 确认 annotation 生效
故意给 Service selector 加一个不匹配的 label，观察 kubectl get endpointslice 无后端

验收清单

能画出控制面和 Node 组件关系图，并说出各组件职责
能解释 Cluster、Node、Namespace、Pod 与控制器的关系
理解声明式 vs 命令式的差异和调谐循环原理
会区分 labels 和 annotations 的使用场景
会用 -n 和 -A 区分 Namespace 范围
知道 Pod IP 不是稳定服务地址
会按 label 查询一组 Pod
会用 describe 和 events 获取故障证据

下一篇：选择与管理工作负载。

1. 集群架构​

1.1 控制面组件​

1.2 Node 组件​

1.3 资源关系图​

2. YAML 结构：每个资源都长这样​

3. 声明式 vs 命令式​

4. Namespace 是第一个隔离边界​

5. Node 与 Pod​

6. 标签与选择器​

6.1 Labels vs Annotations​

7. 调谐循环：Kubernetes 如何工作​

8. 用 describe 与 events 找证据​

9. 练习​