📚 课程目录第2章 K8s节点标签与拓扑键

2. K8s节点标签与拓扑键：node label的规划、topology.kubernetes.io/zone与topology.kubernetes.io/region的语义、自定义拓扑键

2.1 节点标签（Node Label）的规划原则

节点标签是Kubernetes集群拓扑感知的基石。合理的标签规划直接影响Pod调度、服务拓扑感知、Volume拓扑约束以及故障域隔离能力。标签规划应遵循以下原则：

语义明确：标签键值应能清晰表达节点所属的物理或逻辑位置，避免歧义。
层次一致：所有节点应使用相同的标签键体系，确保调度器能够统一识别。
覆盖完整：集群中每个节点都应被赋予完整的拓扑标签，避免出现“无标签”节点导致调度异常。
不可变设计：拓扑标签一旦设定，不应频繁变更，否则会影响已有Pod的拓扑分布约束。

最佳实践：在生产集群中，建议使用基础设施即代码（IaC）工具（如Terraform、Ansible）在节点加入集群时自动注入标签，避免人工操作导致的标签遗漏或错误。

2.2 标准拓扑标签语义：topology.kubernetes.io/zone 与 topology.kubernetes.io/region

Kubernetes社区定义了两组标准拓扑标签，用于描述节点的故障域层级：

标签键	语义	示例值	层级关系
`topology.kubernetes.io/region`	地理区域（Region），通常对应云服务商的一个大区，如华北、华东	`cn-north-1`	最高层级，包含多个Zone
`topology.kubernetes.io/zone`	可用区（Zone），通常对应数据中心内的独立故障域，如不同的机房或电力单元	`cn-north-1a`	Region下的子层级，一个Region包含多个Zone

语义说明：

topology.kubernetes.io/region 表示节点所在的“大区域”，同一Region内的节点间网络延迟较低，但可能共享某些基础设施风险。
topology.kubernetes.io/zone 表示节点所在的“可用区”，同一Zone内的节点共享相同的故障边界（如电源、网络交换机）。不同Zone之间通常具有独立的故障隔离能力。

注意：在自建机房或边缘场景中，如果没有云服务商提供的Region/Zone概念，建议自行定义等效的拓扑层级，例如将“机房”映射为Region，“机架”映射为Zone。

2.3 自定义拓扑键（Custom Topology Keys）

除了标准拓扑标签，Kubernetes允许用户定义自定义拓扑键，以满足特定场景的故障域划分需求。自定义拓扑键通常用于以下场景：

机架感知：使用 topology.kubernetes.io/rack 表示节点所在的物理机架。
网络分区：使用 topology.kubernetes.io/network-segment 表示节点所在的网络段。
存储拓扑：使用 topology.kubernetes.io/storage-pool 表示节点关联的存储池。
边缘节点分组：使用 topology.kubernetes.io/edge-group 表示边缘节点的逻辑分组。

自定义拓扑键的命名规范：

命名空间	示例	说明
`topology.kubernetes.io/`	`topology.kubernetes.io/rack`	Kubernetes官方保留前缀，建议优先使用
`topology./`	`topology.examplecorp.com/storage-tier`	企业自定义域名前缀，避免与官方键冲突

  关键点：自定义拓扑键必须通过 kubectl label node 或节点初始化脚本注入，并在Pod的 topologySpreadConstraints 或 nodeAffinity 中引用。调度器会根据这些键的值进行拓扑分布计算。

2.4 节点标签的注入与管理

节点标签可以通过以下方式注入：

手动注入：使用 kubectl label node 命令。
自动注入：在节点初始化脚本（如cloud-init、kubeadm join脚本）中指定。
控制器注入：通过自定义控制器监听节点创建事件，自动添加标签。

手动注入示例：

# 为节点 node-1 添加 region 和 zone 标签
kubectl label node node-1 \
  topology.kubernetes.io/region=cn-north-1 \
  topology.kubernetes.io/zone=cn-north-1a

# 添加自定义拓扑键
kubectl label node node-1 \
  topology.kubernetes.io/rack=rack-12 \
  topology.examplecorp.com/storage-tier=ssd

验证标签是否生效：

# 查看节点标签
kubectl get node node-1 --show-labels

# 使用标签选择器过滤节点
kubectl get node -l topology.kubernetes.io/zone=cn-north-1a

2.5 拓扑键在Pod调度中的应用

拓扑键在Pod调度中通过 topologySpreadConstraints 和 nodeAffinity 发挥作用。以下是一个使用自定义拓扑键的示例：

apiVersion: v1
kind: Pod
metadata:
  name: web-app
spec:
  topologySpreadConstraints:
  - maxSkew: 1
    topologyKey: topology.kubernetes.io/zone
    whenUnsatisfiable: DoNotSchedule
    labelSelector:
      matchLabels:
        app: web
  - maxSkew: 2
    topologyKey: topology.kubernetes.io/rack
    whenUnsatisfiable: ScheduleAnyway
    labelSelector:
      matchLabels:
        app: web
  nodeAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      nodeSelectorTerms:
      - matchExpressions:
        - key: topology.examplecorp.com/storage-tier
          operator: In
          values:
          - ssd

提示：上述配置要求Pod在Zone层面严格均匀分布（maxSkew=1），在机架层面尽量均匀分布（maxSkew=2），并且必须调度到SSD存储层级的节点上。自定义拓扑键 topology.examplecorp.com/storage-tier 在此处作为调度约束条件。

2.6 常见问题与避坑指南

问题	原因	解决方案
Pod调度失败，提示拓扑键不匹配	节点缺少Pod引用的拓扑标签	检查节点标签，确保所有节点都包含所需的拓扑键
拓扑分布不均匀	部分节点标签值相同，导致调度器认为它们属于同一拓扑域	重新规划标签值，确保每个故障域有独立的标签值
自定义拓扑键与标准键冲突	使用了 `topology.kubernetes.io/` 前缀但键名与官方未来版本冲突	使用企业自定义域名前缀，如 `topology.examplecorp.com/`
节点标签变更后Pod未重新调度	拓扑约束仅在Pod创建时生效	使用 `descheduler` 或手动重建Pod以应用新拓扑

重要提醒：在生产环境中，建议将拓扑标签的变更纳入变更管理流程。标签变更后，应使用 kubectl describe node 验证标签是否生效，并通过测试Pod验证调度行为是否符合预期。